AgentDir

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:

Ask the agent to do the task.
Review the result.
Use AgentDir only when you want the trail.

The agent handles the recording surface:

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):

uv tool install agentdir-cli
# or
pipx install agentdir-cli

Or use the GitHub Release installer:

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:

agentdir --version
agentdir --help

Update an existing install to the latest release and refresh adoption for the current repository:

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

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@<tag-or-commit>

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 for details.

Adopt A Repository

Run once from a git repository:

agentdir adopt

Coding agents use the non-interactive form below so .agentdir/ is ignored at the user level without creating a repository .gitignore change:

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:

agentdir adopt --dry-run --json

If you want generated integration files to stay inside the AgentDir store instead of project instruction files:

agentdir adopt --install-skill store --install-generic store --integration-target store

Adoption adapts to repos where other tools own these files. When 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 for details.

For non-interactive installs, choose the ignore destination explicitly:

agentdir adopt --gitignore project  # write <repo>/.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:

agentdir unadopt          # dry-run
agentdir unadopt --apply  # remove managed hooks and guidance

What Gets Written

Default adoption writes only local files:

<repo>/.agentdir/                         # evidence, artifacts, indexes, state
<repo>/.agentdir/hooks.json               # installed-hook drift manifest
<active-hooks-directory>/*                # managed hook shims with backups
<repo>/AGENTS.md                          # generic / Codex-readable guidance
<repo>/CLAUDE.md                          # Claude Code guidance
<repo>/.github/copilot-instructions.md    # Copilot guidance
<repo>/.cursor/rules/agentdir.mdc         # Cursor guidance
<repo>/.windsurf/rules/agentdir.md        # Windsurf guidance
<repo>/.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:

# 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.

agentdir status
agentdir evidence --brief
agentdir timeline
agentdir report final --format json
agentdir replay
agentdir memory search "checkout failure"

For final-answer support:

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:

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:

<repo>/.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.

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:

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:

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:

agentdir context build "checkout failure" --emit
agentdir context consume --pack <pack-id> --source <source-id> --purpose plan
agentdir context cite --pack <pack-id>
agentdir audit context --pack <pack-id>

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.

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:

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:

agentdir doctor
agentdir secrets scan
agentdir secrets redact
agentdir secrets redact --apply

Upgrade And Rollback

Upgrade an existing install and refresh current repo adoption:

agentdir --upgrade

Rollback to the previous stable release:

curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/rollback.sh | bash

Learn More

• Install Guide
• Agentic Coding Guide
• Technical Brief
• Release Guide
• PRD

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.