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.
With Zanei, an agent can look up what you were doing before the conversation started: the pages you were reading, the PR you were reviewing, where you left off.
Two surfaces and 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 |
Chat clients that cannot run the CLI (Claude Desktop), for which 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 every agent that runs the CLI; each one reads it through its own skill discovery model.
Supported agents
| Agent | CLI + skill | MCP (stdio) |
|---|---|---|
| Claude Code | ✅ SKILL.md |
✅ |
| Codex CLI | ✅ SKILL.md (~/.codex/skills/) |
✅ codex mcp add |
| opencode | ✅ SKILL.md ($XDG_CONFIG_HOME/opencode/skills/, or .opencode/skills/ with --scope project) |
✅ opencode.json (manual JSON printed) |
| Hermes Agent | ✅ SKILL.md (~/.hermes/skills/) |
✅ hermes mcp add |
| pi | ✅ SKILL.md (~/.pi/agent/skills/, or .pi/skills/ with --scope project) |
— (pi has no MCP by design; the skill covers it) |
| Claude Desktop chat (cannot run the CLI) | — | ✅ only path |
The Claude desktop app hosts both surfaces. Its chat reaches Zanei over MCP; Claude Code running inside the same app has a shell and uses the Claude Code row above.
Setup installs skill files and prints the MCP registration command for your agent; opencode’s MCP JSON is printed for you to place. 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. This is the tool agents call most.query_events— raw event lookup; equivalent tozanei query.get_status— is recording running, are permissions OK. Whenrunningisfalse, an agent can tell you that history isn’t being recorded instead of answering from guesswork.
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 transmission is the agent’s responsibility. 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.