Agent integration
How Tadoru plugs into AI agents — the two surfaces, the skill instruction layer, which agents are covered, and what agents can (and cannot) do.
Tadoru exists to give agents the context you didn’t type: what you were reading, which PR you were reviewing, where you left off. The integration is deliberately thin — every surface is a wrapper over the same local store.
Two surfaces, one instruction layer
Tadoru exposes your history through two surfaces — both thin wrappers over the same local store:
| Surface | What it is | Who uses it |
|---|---|---|
| CLI | The tadoru binary itself. Agents with a shell call it directly |
Terminal agents (Claude Code, Codex CLI, opencode, pi, …) |
| MCP server | tadoru 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 |
A skill is not a third surface — it is the instruction layer that tells the agent when to reach for 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 — which is why setup for Claude Desktop only registers the server. - The CLI is not self-describing to an agent, so Tadoru 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; they are never injected.
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 totadoru timeline. What agents call most.query_events— raw event lookup; equivalent totadoru 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 — most importantly, it cannot touch capture-time filters. An agent can never widen what gets recorded or weaken your privacy boundary.
A note on data flow
Tadoru itself never sends data anywhere. But an agent that reads your timeline will typically forward it to its LLM provider — that hop belongs to the agent, not Tadoru. The shipped skill files instruct agents to narrow the time range before sending (e.g. --since 2h, token budget 4000) rather than pulling days of history by default.