# AgentDir

AgentDir records observable agent reasoning artifacts, tool calls, evidence, and handoffs across Codex, Claude, Pi, and other coding agents.

Local-first memory and evidence for agentic engineering.

CI status

AgentDir is a flight recorder for coding agents. It lets agents record what happened during a software task, then gives engineers a clean way to inspect, replay, search, and audit that work later. The goal is simple: AgentDir should be nearly invisible while you work. Engineers should not have to manually start sessions, wrap commands, collect evidence, or maintain agent memory by hand. Once a repository is adopted, the agent operates AgentDir in the background and leaves behind a useful trail. ## Why AgentDir Exists Agentic engineering has a trust gap. Agents can edit code, run tools, and summarize results, but their work often ends up scattered across chat history, terminal scrollback, temporary files, and unverified final claims. That makes it hard to answer basic questions: - What did the agent actually do? - Which commands support the final answer? - Were tests, builds, lint, or release checks really run? - What context did the agent retrieve and rely on? - Can a future agent learn from this session? - Can the index or memory layer be rebuilt if it breaks? AgentDir gives those answers a local, durable home. ## What You Get | Capability | What it means | | --- | --- | | Invisible agent workflow | Agents run AgentDir commands during normal work, so engineers keep using their coding assistant normally. | | Evidence-backed claims | Test, build, lint, typecheck, doctor, and release claims can be checked against recorded tool results. | | Replayable sessions | Inspect the task, decisions, commands, outputs, blockers, summaries, and handoffs after the fact. | | Local-first storage | Records live in the repo-local `.agentdir` directory by default. No hosted service is required. | | Rebuildable memory | Raw event files are the source of truth. SQLite search and memory indexes can be rebuilt. | | Context lineage | Agents can emit context packs, then record which retrieved sources were consumed or cited. | | Cross-repo memory | Explicitly registered AgentDir roots can be searched together without moving canonical records. | | Secret-aware persistence | Common secret-like patterns are redacted before storage, with scan and cleanup commands for older records. | ## The Invisible Workflow AgentDir is designed around a small separation of responsibility. | Human does | Agent does | | --- | --- | | Install AgentDir once. | Start and finish AgentDir sessions. | | Run `agentdir adopt` once per repo. | Capture evidence-bearing commands with `agentdir run`. | | Ask the coding agent to do work. | Record decisions, blockers, context, and handoffs. | | Inspect evidence only when needed. | Audit session quality and final claims before reporting. | In day-to-day use, the human workflow stays the same: ```text Ask the agent to do the task. Review the result. Use AgentDir only when you want the trail. ``` The agent handles the recording surface: ```bash agentdir work start "fix checkout failure" --emit-context agentdir run -- pytest -q agentdir audit session agentdir work finish --json ``` ## Install Install from PyPI (the package is `agentdir-cli`; the command it installs is `agentdir`): ```bash uv tool install agentdir-cli # or pipx install agentdir-cli ``` Or use the GitHub Release installer: ```bash curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/install.sh | bash ``` The installer uses `pipx` when available. Otherwise it creates a self-contained virtual environment under `~/.local/share/agentdir` and links the CLI into `~/.local/bin`. It does not edit Git configuration or ignore files; after installation it prints the explicit adoption choices. Verify: ```bash agentdir --version agentdir --help ``` Update an existing install to the latest release and refresh adoption for the current repository: ```bash agentdir update agentdir update --dry-run ``` The older `agentdir --upgrade` interface remains supported for compatibility. ## Pi Package Pi users can install this repository as a Pi package so the AgentDir skill is available automatically during coding tasks: Package page: [@jstxn/agentdir-pi](https://pi.dev/packages/@jstxn/agentdir-pi) ```bash pi install npm:@jstxn/agentdir-pi@0.8.0 # or install directly from a local checkout / release tag: pi install /absolute/path/to/agentdir pi install git:github.com/jstxn/agentdir@ ``` The package exposes `skills/agentdir/SKILL.md`; it teaches Pi to start AgentDir sessions, wrap evidence-bearing commands, use local memory/context packs, and produce evidence-aware handoffs. See [AgentDir Pi Package](docs/PI_PACKAGE.md) for details. ## Adopt A Repository Run once from a git repository: ```bash agentdir adopt ``` Coding agents use the non-interactive form below so `.agentdir/` is ignored at the user level without creating a repository `.gitignore` change: ```bash agentdir adopt --gitignore user ``` This is intentionally boring setup. It prepares the repository once, then agents operate AgentDir during normal coding work: - creates the repo-local `.agentdir` store - installs AgentDir-managed git hook shims - installs the Codex skill into the user skill directory - writes managed project guidance for common agent tools - asks interactive users whether `.agentdir/` should be added to the project or user-level Git ignore file - runs `doctor` to confirm the store is healthy After that, agents have the guidance they need to use AgentDir without the engineer manually operating it during normal work. Preview setup without writing anything: ```bash agentdir adopt --dry-run --json ``` If you want generated integration files to stay inside the AgentDir store instead of project instruction files: ```bash agentdir adopt --install-skill store --install-generic store --integration-target store ``` Adoption adapts to repos where other tools own these files. When [rulesync](https://github.com/dyoshikawa/rulesync) generates the guidance files, the managed rule is written to `.rulesync/rules/agentdir.md` instead so it survives regeneration, and files with generated-file headers are never edited without `--force`. When lefthook, husky, or pre-commit own the Git hooks, adopt warns up front, `agentdir doctor` flags hook shims those tools later overwrite, and `agentdir hooks install` restores them. See [docs/INSTALL.md](docs/INSTALL.md#coexisting-with-rule-generators-and-hook-managers) for details. For non-interactive installs, choose the ignore destination explicitly: ```bash agentdir adopt --gitignore project # write /.gitignore agentdir adopt --gitignore user # write the user-level Git excludes file agentdir adopt --gitignore none # leave ignore files unchanged ``` Generated AgentDir guidance selects `--gitignore user` by default. The plain interactive command still prompts, and all three explicit choices remain available. Undo managed setup while keeping the `.agentdir` evidence store: ```bash agentdir unadopt # dry-run agentdir unadopt --apply # remove managed hooks and guidance ``` ## What Gets Written Default adoption writes only local files: ```text /.agentdir/ # evidence, artifacts, indexes, state /.agentdir/hooks.json # installed-hook drift manifest /* # managed hook shims with backups /AGENTS.md # generic / Codex-readable guidance /CLAUDE.md # Claude Code guidance /.github/copilot-instructions.md # Copilot guidance /.cursor/rules/agentdir.mdc # Cursor guidance /.windsurf/rules/agentdir.md # Windsurf guidance /.rulesync/rules/agentdir.md # rulesync source, when detected ~/.codex/skills/agentdir/SKILL.md # Codex skill, by default ``` Managed guidance is wrapped in AgentDir markers. Existing unmanaged content is preserved where the target format supports managed blocks. The active hooks directory is `.git/hooks` by default and follows `core.hooksPath` or linked worktree configuration. In rulesync repos, the source rule replaces the listed project guidance files as the managed source of truth. ## Git Worktrees A repository has one store, shared by every `git worktree` checkout. Commands run inside a linked worktree resolve to the main working tree's `.agentdir`, so evidence and memory from all worktrees stay searchable together instead of fragmenting into one store per branch. Each worktree still keeps its own active session, so parallel agents in different worktrees do not overwrite each other. Two cases keep a store inside the worktree instead: ```bash # a store already present in the worktree always wins AGENTDIR_WORKTREE_STORE=local agentdir adopt # or opt out explicitly ``` `agentdir doctor` warns when a worktree holds a store separate from the main one and names the command that joins them for search. ## Inspect A Session Most users will not need these commands every day, but they are the reason AgentDir exists. ```bash agentdir status agentdir evidence --brief agentdir timeline agentdir report final --format json agentdir replay agentdir memory search "checkout failure" ``` For final-answer support: ```bash agentdir audit session agentdir audit claims # recorded structured claims agentdir audit claims --text final-response.md # prose, when not instrumented ``` Audits are advisory by default. Use `--strict` when unsupported or contradicted claims should fail a check. ## How AgentDir Works AgentDir has one source of truth and several rebuildable views: ```text raw envelopes -> SQLite index -> memory/search/audit/report ^ | rebuilt from envelopes ``` 1. **Raw envelopes** Each meaningful event is stored as an immutable file in a Maildir-inspired directory layout. These files are the source of truth. 2. **Derived indexes** SQLite indexes, search tables, memory passages, context packs, and audit views are derived from the raw event files and can be rebuilt. Default project layout: ```text /.agentdir/ sessions/ actors/ artifacts/ archives/ indexes/agentdir.sqlite3 state/ integrations/ ``` The important property is recoverability: deleting the derived index does not destroy the session. AgentDir can rebuild from the envelope store. The agent-facing report surface is JSON. `agentdir report final --format json` and `agentdir work finish --json` include an `agent_handoff` object with verification evidence, failed evidence, claim support, context lineage, known gaps, and recommended next agent actions. ## Unique Capabilities ### Claims-To-Evidence Checks Agents record what a check showed, and AgentDir compares that against the recorded tool results. It does this deterministically, not with an LLM. ```bash agentdir claim test --passed agentdir claim build --failed --note "linker error in release profile" agentdir claim list agentdir audit claims # checks recorded claims against evidence agentdir audit claims --strict # exit 1 when a claim is not supported ``` A structured claim names its family and outcome outright, so checking it is a comparison rather than an interpretation of prose: | Claim | Evidence | Result | | --- | --- | --- | | passed | succeeded | `supported` | | passed | failed | `contradicted` | | failed | failed | `acknowledged` | | failed | succeeded | `contradicted` | | either | none recorded | `unsupported` | | none recorded | failed | `unreviewed` | Recording a family again replaces its earlier claim, so a check re-run after a fix supersedes rather than accumulates. Claiming a failure honestly is `acknowledged` and does not count against the audit. A claim made in error can be withdrawn: ```bash agentdir claim build --retract ``` Claims are append-only events, so retracting supersedes the earlier claim in the latest-claim view while leaving both in the record. Recorded claims also reach the `agent_handoff` object without any final text being supplied. Supported claim families: - test - lint - typecheck - build - doctor - release #### Auditing prose instead For final responses that were not instrumented, `agentdir audit claims --text` reads claims out of prose: ```bash agentdir audit claims --text final-response.md ``` This path has to infer intent from wording, so prefer recorded claims when the agent can emit them. Claim detection is keyword-based, so ordinary phrasing such as "everything works" or "verified locally" matches no family. When recorded evidence failed and the text makes no checkable claim about it, the audit reports that family as `unreviewed` and is not `ok`, rather than passing because it found nothing to check. `claims_detected` reports how many claims were actually parsed, so "nothing to audit" is never mistaken for "audited and clean". Text that states the failure instead ("tests failed", "two tests fail") is reported as `acknowledged` and does not count against the audit, so honest failure reporting is never flagged like text that hid the failure. Failure vocabulary asserting success ("no test failures") is treated as a success claim and checked against evidence like any other. ### Context Packs Agents can package retrieved context into auditable source manifests: ```bash agentdir context build "checkout failure" --emit agentdir context consume --pack --source --purpose plan agentdir context cite --pack agentdir audit context --pack ``` This does not prove a model paid attention, but it does make cooperative agent behavior visible. ### Local Agent Memory AgentDir builds searchable local memory from prior sessions. Agents can search similar work, explain why a memory hit matched, and include relevant history in new context packs. ```bash agentdir memory search "release evidence" agentdir memory explain "release evidence" agentdir context build "release evidence" --emit ``` Optional semantic extras exist, but the default path does not require a vector database or external embedding service. ### Federated Memory For multi-repo work, AgentDir can search explicitly registered roots: ```bash agentdir roots register ../other-repo --name other-repo agentdir memory search --federated "release evidence" ``` Each repository remains the canonical owner of its own `.agentdir` store. ## Safety Model AgentDir is local-first and advisory by design. - It records what agents choose to record. - It does not replace code review or CI. - It does not send data to a hosted AgentDir service. - It treats raw envelopes as the source of truth. - It redacts common secret-like patterns before persistence. - It provides `secrets scan` and `secrets redact --apply` for cleanup. Useful commands: ```bash agentdir doctor agentdir secrets scan agentdir secrets redact agentdir secrets redact --apply ``` ## Upgrade And Rollback Upgrade an existing install and refresh current repo adoption: ```bash agentdir --upgrade ``` Rollback to the previous stable release: ```bash curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/rollback.sh | bash ``` ## Learn More - [Install Guide](docs/INSTALL.md) - [Agentic Coding Guide](docs/AGENTIC_CODING.md) - [Technical Brief](docs/TECH_BRIEF.md) - [Release Guide](docs/RELEASING.md) - [PRD](docs/PRD.md) ## Project Status AgentDir is beta software for local-first agentic engineering workflows. The core model is stable: agents operate the recorder, engineers get the evidence, and raw local envelopes remain the recoverable source of truth.