---
title: Agent integration
description: 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](/reference/mcp)** | `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](/agents/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 expected `AGENTS.md` or 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](/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 `tadoru timeline`. What agents call most.
- **`query_events`** — raw event lookup; equivalent to `tadoru 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 — most importantly, it **cannot touch [capture-time filters](/guides/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.