Agent integration
How Zanei plugs into AI agents — the two surfaces, the skill instruction layer, which agents are covered, and what agents can (and cannot) do.
Zanei gives agents the context you did not type: what you were reading, which PR you were reviewing, where you left off. Every integration surface is a wrapper over the same local store.
Two surfaces, one instruction layer
Zanei exposes your history through two surfaces — both thin wrappers over the same local store:
| Surface | What it is | Who uses it |
|---|---|---|
| CLI | The zanei binary itself. Agents with a shell call it directly |
Terminal agents (Claude Code, Codex CLI, opencode, pi, …) |
| MCP server | zanei mcp, a stdio JSON-RPC server exposing read-only tools |
Shell-less clients (Claude Desktop, ChatGPT connectors) — for these, MCP is the only path. Terminal agents can use it too |
The skill is not a third surface; it is the instruction layer that tells the agent when to read your history and how to keep token usage low. How those instructions reach the agent differs by surface:
- Over MCP, they are built in: tool names, descriptions, defaults, and schemas travel inside the protocol (
tools/list), so MCP clients need nothing else. This is why setup for Claude Desktop only registers the server. - The CLI is not self-describing to an agent, so Zanei keeps one canonical
skills/SKILL.md. Setup installs it unchanged for agents with native skill support. For opencode and pi, it derives the expectedAGENTS.mdor README instructions and prints them for you to place yourself. Each agent reads those instructions through its own discovery model.
Supported agents
| Agent | CLI + skill | MCP (stdio) |
|---|---|---|
| Claude Code | ✅ SKILL.md |
✅ |
| Codex CLI | ✅ SKILL.md (~/.codex/skills/) |
✅ codex mcp add |
| opencode | ✅ user-placed AGENTS.md snippet derived from SKILL.md |
✅ opencode.json (manual JSON printed) |
| Hermes agent | ✅ SKILL.md (~/.hermes/skills/) |
✅ hermes mcp add |
| pi | ✅ recommended path (CLI + user-placed README instructions derived from SKILL.md) |
— (pi has no MCP by design; the CLI path covers it) |
| Claude Desktop, ChatGPT connectors (no shell) | — | ✅ only path |
Setup installs skill files, prints the MCP registration command for your agent, and prints the manual instructions needed for opencode and pi — see setup.
What agents can do
Through MCP, agents get three read-only tools (details in the MCP reference):
get_timeline— the LLM-ready timeline; equivalent tozanei timeline. What agents call most.query_events— raw event lookup; equivalent tozanei query.get_status— is recording running, are permissions OK. Whenrunningisfalse, a well-behaved agent tells you that history isn’t being recorded instead of answering from nothing.
Through the CLI, agents can use everything — including starting and stopping recording — subject to your approval flow. The shipped skill teaches the read paths, status/doctor diagnostics, and that recording settings change only on your explicit request.
What agents cannot do
The MCP server is a read-only view over the store, running as a separate process from the recording daemon:
- It cannot start or stop recording.
- It cannot change configuration, including capture-time filters. An agent cannot widen what gets recorded through MCP.
A note on data flow
Zanei itself does not send data anywhere. An agent that reads your timeline will typically forward it to its LLM provider; that hop belongs to the agent. The shipped skill instructs agents to narrow the time range before sending (for example --since 2h, token budget 4000) rather than pulling days of history.