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.

If your goal is automatic recording, start with the host integration instead of the raw CLI.

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 into your agent host

These are the fastest paths when you want Traceary to record sessions and shell commands automatically.

Host	Install path	Guide
Claude Code	claude plugins marketplace add https://github.com/duck8823/traceary then claude plugins install traceary@traceary-plugins --scope user	Claude Code plugin
Codex	git clone https://github.com/duck8823/traceary ~/src/traceary then python3 ~/src/traceary/scripts/codex/install_plugin.py	Codex plugin
Gemini CLI	gemini extensions install https://github.com/duck8823/traceary --ref <tag>	Gemini CLI extension

For the integration overview, use the native integrations guide.

Install the Traceary CLI

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

Manual CLI workflows

If you need one-off/manual usage outside the host integrations, the usual entry points are:

• traceary session start
• traceary log
• traceary audit
• traceary list / traceary search
• traceary doctor

Use the CLI reference for the full command surface.

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; when remote.origin.url is missing inside a git worktree, Traceary falls back to the worktree root path
• 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:

• Native integrations
• 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.