traceary

README

Traceary

日本語

Traceary is a local-first CLI and MCP server for recording and searching AI agent work logs, session boundaries, and shell command audits.

Why Traceary

AI-assisted development gets messy quickly when:

• session context disappears after clear or compact
• Git history explains what changed, but not always why
• shell command output is hard to connect back to the right agent or session
• work is split across Claude, Codex, Gemini, and manual terminal steps
• multiple sessions and worktree moves make the timeline harder to follow

Traceary keeps those records in one local SQLite store so the same history can be reused from the CLI, hooks, and MCP clients.

What it stores

• notes and review records
• session start/end events
• shell command audits
• attribution such as client, agent, session_id, and repository/work context

Traceary is local-first. It writes to SQLite on your machine and does not include built-in telemetry, analytics, or hosted storage.

Install

go install

go install github.com/duck8823/traceary@latest

Homebrew

brew tap duck8823/traceary https://github.com/duck8823/traceary
brew install traceary

Prebuilt binaries

Tagged releases publish macOS and Linux archives on GitHub Releases. See the release guide when you want the packaging details.

Quick start

traceary init is optional. Commands create the database and run migrations on demand. Use init only when you want to create the DB path up front or confirm write permissions before a session starts.

1. Start a session and write a note

sid=$(traceary session start --client dogfood --agent codex)
event_id=$(traceary log --client dogfood --agent codex --session-id "$sid" --id-only "Investigating failing tests")
traceary show "$event_id" --json

2. Record command output in the same session

traceary audit \
  --client dogfood \
  --agent codex \
  --session-id "$sid" \
  --command "go test ./..." \
  --input '{"stdin":""}' \
  --output '{"stdout":"panic: boom","stderr":"stacktrace","exitCode":1}'

traceary search boom --json
traceary session active

3. Use script-friendly output when needed

traceary log --id-only "Investigating failing tests"
traceary audit --id-only --command "go test ./..." --input '{}' --output '{}'
traceary session end --session-id "$sid" --id-only

Core commands

traceary init
traceary log <message>
traceary audit [<command> <input> <output>]
traceary list
traceary search <query>
traceary show <event-id>
traceary context
traceary handoff
traceary session start
traceary session end
traceary session latest
traceary session active
traceary hooks print --client <claude|codex|gemini>
traceary hooks install --client <claude|codex|gemini>
traceary hooks guide --client <claude|codex|gemini>
traceary mcp-server
traceary doctor
traceary backup create --output <path>
traceary backup restore --input <path>
traceary gc

Defaults worth knowing

• traceary log and traceary audit reuse the latest non-stale active session for the resolved repo/work context when --session-id is omitted
• traceary session active treats sessions older than 24h as stale unless you pass --allow-stale
• traceary session start prints a session ID; traceary session end prints the recorded event ID
• default operator-facing CLI output is English; set TRACEARY_LANG=ja when you want Japanese messaging
• --json output stays language-neutral

Documentation

Use the documentation index for the full map. The most common next pages are:

• CLI reference
• Hooks guide
• MCP guide
• Environment and storage notes

Contributing and support

• bug reports and feature requests belong in GitHub Issues
• security reports should follow the private contact path in CONTRIBUTING.md
• this is an actively evolving v0.x OSS tool, so check the changelog before upgrading automation around it

Documentation

Overview

Package main defines the Traceary entrypoint. Environment loading and dependency wiring happen only in this package.