agent-trace

agent-trace is a git-backed document store for agent workflows with two core guarantees:

1. Persistent observability across sessions (cross-session trace continuity)
2. Reliable recovery and easy resume after dropped processes or IDE sessions

What You Get

• Durable change history in .agent-trace/repo/ with actor attribution
• Generated AGENT-TRACE.md index for zero-cost agent discovery
• Generated context.md for current project state synthesis
• Session-scoped agent logs in logs/<agent>-<session_id>.md
• Permission enforcement with violation tracking and rejected-content capture

Installation

Pre-release: Until v0.1.0 is published, build from source (below) is the supported install path. cargo install agent-trace and GitHub Release downloads apply after the first release is published.

Install from crates.io (available after v0.1.0 is published):

cargo install agent-trace

Or download a prebuilt binary from GitHub Releases once v0.1.0 is published. Substitute {version} with the release version (for example 0.1.0):

version={version}
target=x86_64-unknown-linux-gnu
curl -LO "https://github.com/XxAndrewOxX/AgentTrace/releases/download/v${version}/agent-trace-v${version}-${target}.tar.gz"
curl -LO "https://github.com/XxAndrewOxX/AgentTrace/releases/download/v${version}/agent-trace-v${version}-${target}.tar.gz.sha256"
sha256sum -c "agent-trace-v${version}-${target}.tar.gz.sha256"
tar xzf "agent-trace-v${version}-${target}.tar.gz"
sudo mv agent-trace /usr/local/bin/

Build from source:

This is the supported path until v0.1.0 is published.

rustup toolchain install 1.88.0
cargo build --locked
./target/debug/agent-trace --help

See docs/INSTALL.md for Cargo, GitHub Release, checksum, platform notes (including Linux arm64), and MCP setup details. See docs/agent-plugin.md for the agent-native plugin distribution plan.

Quick Start

agent-trace model setup
agent-trace model serve-check
agent-trace init .
agent-trace add plan plan.md
agent-trace connect my-agent
agent-trace write plan.md --content "# updated"
agent-trace log --limit 10

For MCP-based agents:

agent-trace mcp --path . --actor my-agent

When developing from source, prefix commands with ./target/debug/agent-trace.

Resume After Crash

When a session drops:

1. MCP agents: call get_resume_context first (before list_documents or read_file)
2. CLI users: agent-trace resume show for the running summary briefing
3. Reconnect agent identity: agent-trace connect <name> (stale locks are replaced)
4. Review running_summary.md — incrementally updated after each write
5. Read plan.md only if the summary references new phases
6. If metadata is damaged, recover: agent-trace repair
7. Continue writing via agent-trace write or MCP write_file

MCP reconnect workflow

On every new MCP session:

1. Call get_resume_context (do not call list_documents first)
2. Read plan.md only if get_resume_context says phases changed
3. Read source files only listed under "Resume Here" or "Open Items"
4. Update plan.md and progress docs via write_file after each phase

Reliability Notes

• Store durability is provided by git commits and manifest persistence.
• Session lineage is tracked via .agent-trace/locks/agent-lock.toml heartbeat metadata.
• Unauthorized writes to protected docs are reverted and logged as violations.
• repair rebuilds manifest state from git when recovery is needed.

Contributing / validation

Before opening a PR, run:

cargo test --locked
cargo clippy --locked -- -D warnings
cargo fmt --check
./scripts/run_e2e.sh

See docs/VALIDATION-PLAN.md for the full checklist, E2E suite flags, and optional live-agent tests.

Releasing

1. Bump version in Cargo.toml and add a dated section to CHANGELOG.md (or run ./scripts/bump_version.sh X.Y.Z)
2. Tag vX.Y.Z and push the tag
3. CI builds platform artifacts and creates a draft GitHub Release
4. Review artifacts and release notes, then publish the release
5. Run cargo publish manually for crates.io

See .github/RELEASE_TEMPLATE.md for the maintainer checklist.

License

Licensed under the MIT License.