Palimpsests / Integrations

Integrations · Claude Code · Codex · OpenTelemetry · LiteLLM · MCP

Audit logging for the tool calls your agents already make

Your agents may run a local model or call a hosted one. Either way, their tool calls can be recorded on a tamper-evident log that stays on your own machine. The audit record stays on your machine, even when the model doesn't.

Before you start

pip install 'palimpsests[serve]'
palimpsests-serve --api-key "$PALIMPSESTS_SERVE_API_KEY"   # http://127.0.0.1:11435

Every integration below reports to this local server, which writes each tool call and its result into a PALA-1 chain. Arguments and results are stored as SHA-256 digests of a canonical form; their content never enters the chain. The key is optional on a machine only you use, and recommended anywhere else. Since 0.13.1 palimpsests serve --api-key … takes it the same way; in 0.13.0 only palimpsests-serve did.

Every integration below has a recorded run on real traffic — a real client and a real model — with what reached the chain and what did not: run records R1–R5.

What a reported record proves

RecordWhat the chain proves
wire-parsed pair: the server ran the tool loop itselfthe runtime saw the dispatch and the returned result
reported pair, marked reported-by-clienta client reported a call and a result; the server recorded the report, its digests and the time. It doesn't show that the tool ran.

Since 0.13 every result also says what its recorder could see: ok or error where the client reports failures, unobserved where it can't tell a failed call from a successful one. An ok means a result came back, never that the action succeeded.

Claude Code

Claude Code sends its hooks over HTTP, so there's nothing to install. Add PreToolUse, PostToolUse and PostToolUseFailure entries to ~/.claude/settings.json, each pointing at /v1/pala/hooks/claude with your key in the Authorization header. List the key's variable in allowedEnvVars: without it Claude Code sends an empty header and every report is refused while the agent keeps working.

Results: ok or error, because Claude Code reports failures. On real traffic (Claude Code 2.1.310): eleven pairs from a ten-prompt session, the failed read recorded as error. Four of the session's 26 hook posts arrived without the key for a reason not yet established; the server now logs each refusal with its event and tool. Claude Code runs reads, searches and edits through its shell tool, so the chain names Bash where you might expect more variety. The route is watched by the surface checker.

Codex

Codex runs only command hooks, so a one-file forwarder, palimpsests_hook.py, passes each event to /v1/pala/hooks/codex. Add it as the PreToolUse and PostToolUse command in ~/.codex/hooks.json, then trust them: Codex asks at startup, before the first prompt (Trust all and continue). Codex skips an untrusted hook without a warning, and the tools then run with nothing recorded — measured, with the hooks on disk and correctly formed. On Windows Codex also asks to set up a sandbox; that question does not affect the hooks.

Results: unobserved, because Codex has no failure hook — including for reads that certainly failed. On real traffic (Codex CLI 0.164.0): thirteen pairs, all unobserved; before trusting, zero.

OpenTelemetry GenAI

Frameworks instrumented with OpenTelemetry already put one execute_tool span on each tool execution. Point the trace exporter at the server and those spans become recorded tool calls:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:11435/v1/traces
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer $PALIMPSESTS_SERVE_API_KEY"

OTLP over HTTP only, JSON or protobuf. To record digests of arguments and results, turn on the instrumentation's content capture; without it the pair is recorded with no digests. Results: error for a span with error status, ok otherwise. Tested against a real export from pydantic-ai 2.57.0, and on real traffic with a local model: three pairs per run, failures as error. Note that pydantic-ai stops an agent when a tool raises; the failing span is still exported.

LiteLLM

A one-file callback for the LiteLLM client library or proxy. It reports the model's tool_calls and the role: tool results that come back, which makes it a natural fit when your agents reach hosted models through a LiteLLM gateway.

import litellm
from palimpsests_audit import PalimpsestsAudit   # integrations/litellm/palimpsests_audit.py
litellm.callbacks = [PalimpsestsAudit()]

Install mcp beside LiteLLM: LiteLLM imports it as soon as a request carries tools, and does not install it itself.

Results: unobserved, because LiteLLM never sees the tool run. On real traffic (LiteLLM 1.106, a local model): ten turns, ten pairs, all unobserved — the three reads of a missing file among them.

MCP servers over stdio

A one-file proxy in front of any MCP server that speaks standard input and output. It sees both the request and the response of every tools/call, forwards every byte unchanged and never blocks a call.

Results: ok, error or cancelled. On real traffic (Claude Code as the client, a filesystem server): eleven pairs, the server's isError recorded as error — and the only adapter whose chain carries the real tool names, because it sits at the MCP boundary. Since 0.13.1 the proxy starts npx and uvx servers on Windows by name; before, it needed the full path.

OpenCode

A dependency-free plugin you copy into .opencode/plugins/. It reports the tools OpenCode runs, including calls the model wrote as plain text. Status on OpenCode 1.18.31: one reported pair has reached the chain from a real session, a failed read that was bound correctly. A successful result arriving the same way hasn't been observed yet.

Limits

  • A reported record proves the report, not the action, and nothing is recorded for a tool the client never reports.
  • Hook interfaces change between client versions. Each adapter's README states the version its behaviour was measured on.
  • The record is only as trustworthy as the chain it sits in; see what makes an audit log tamper-evident.