---
title: Agent integration
description: 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](/reference/mcp)** | `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](/agents/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 expected `AGENTS.md` or 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](/agents/setup).

## What agents can do

Through MCP, agents get three read-only tools (details in the [MCP reference](/reference/mcp)):

- **`get_timeline`** — the LLM-ready timeline; equivalent to `zanei timeline`. What agents call most.
- **`query_events`** — raw event lookup; equivalent to `zanei query`.
- **`get_status`** — is recording running, are permissions OK. When `running` is `false`, 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](/guides/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.