Traceary

日本語

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

Install the CLI first, then add the plugin for your AI agent host to enable automatic recording.

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, Antigravity (Gemini CLI for legacy installs), 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 and hooks.

Three-layer model

Traceary is no longer just a local event log. v0.5.0 organizes the product around three layers that map to how agent workflows actually need context.

Layer	What lives there	How it is fed
Audit / Archive	raw events (prompts, transcripts, command audits), session boundaries	host hooks (SessionStart, UserPromptSubmit / BeforeAgent, PostToolUse / AfterTool, Stop / AfterAgent, PreCompact / PreCompress, SessionEnd) — see host coverage matrix
Working memory	handoff / context packs assembled from recent sessions	handoff packs are assembled on demand by traceary context --handoff (raw events remain traceary context). From v0.34 the session summary itself is materialised by consolidation: the stop hook asks the agent to fold the session while the material is still in the agent's context, and the result is stored as a session refinement
Durable memory	reusable facts such as decisions, constraints, preferences, and artifact refs	curated through the traceary-memory-review skill (review-intent triggers) and the traceary-memory-remember skill (explicit-write triggers)

In practice, Traceary acts as a local-first memory substrate for AI agents: hooks feed L1 mechanically, L2 is normally consolidated at stop while the material is already in context (anything left unfolded is later reduced to a mechanical summary), and L3 stays small because hook-driven auto-extraction lands memories in a review inbox as status=candidate and only human review promotes them. Only the finished summary is used afterwards — wake-time recomputation is deliberately avoided.

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

Getting started

Step 1: Install the Traceary CLI

The CLI is required first — agent plugins invoke the traceary binary via hooks.

# Homebrew (recommended)
brew tap duck8823/traceary https://github.com/duck8823/traceary
brew install traceary

# or go install
go install github.com/duck8823/traceary@latest

Tagged releases also publish macOS and Linux archives on GitHub Releases. See the release guide for packaging details.

After installing, run traceary --help (or bare traceary) to see the command surface. Call script-friendly subcommands directly (traceary list, traceary search, traceary doctor --json, etc.). The former traceary tui / traceary dashboard cockpit entrypoints, the traceary top alias, and traceary sessions were removed; use list / search / report / context --handoff instead.

Step 2: Install the plugin for your agent host

Claude Code (guide)

/plugin marketplace add duck8823/traceary
/plugin install traceary

Codex (guide)

git clone https://github.com/duck8823/traceary ~/src/traceary
cd ~/src/traceary
codex   # then, inside Codex: /plugins -> Traceary Plugins -> Traceary

The traceary integration codex install helper was retired in v0.14.0 and the cleanup-only traceary integration codex uninstall surface was removed in v0.15.0. Use Codex CLI's official /plugins flow shown above for install / uninstall. See the Codex plugin guide for migration details and manual cleanup steps for legacy installs.

Kimi Code (guide)

git clone --depth 1 --branch "v$(traceary -v | awk '{print $2}')" https://github.com/duck8823/traceary ~/src/traceary
cd ~/src/traceary
./scripts/install-kimi-plugin.sh

Pin the release tag matching your Traceary CLI. Kimi Code's official /plugins install <path-or-url> flow also works when pointed at integrations/kimi-plugin/. Verify with traceary doctor --client kimi.

Google agent hosts: install the Antigravity plugin unless your organization still uses Gemini CLI through Gemini Code Assist Standard/Enterprise or a paid Gemini or Gemini Enterprise Agent Platform API key. Google stopped serving Gemini CLI to free and Google AI Pro/Ultra users on 2026-06-18 and directs them to Antigravity. Traceary therefore maintains the Gemini extension for those enterprise and paid-API installations, but does not recommend it for new free/Pro/Ultra setups. See Google's transition announcement.

For Antigravity, the quickest route is to install Traceary's hooks directly with traceary hooks install --client antigravity. The Antigravity hooks and plugin guide distinguishes that route from installing the packaged plugin through agy plugin install. Existing supported Gemini CLI installations can continue with the Gemini extension maintenance guide, which includes the migration path.

For the integration overview, use the native integrations guide. Direct Anthropic API users can also try the experimental native memory-tool backend.

Step 3: Verify

traceary doctor

For CI or smoke checks that should fail only on broken states, use traceary doctor --json --warnings-ok. Warning-only reports then exit 0, while failures still exit 1 and the JSON report keeps the warning counts.

Quick start

The store is created and migrated on demand by the first write or traceary doctor. Data-dependent offline migrations are not applied implicitly; run traceary doctor --fix to apply them (this can take minutes on a large store). The v0.8.x top-level alias traceary init was removed in v0.14.0; traceary store init was removed in v0.42.0. See the CLI stability and deprecation policy.

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

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

4. Promote reusable context when it matters

traceary memory store propose \
  --type decision \
  --workspace github.com/duck8823/traceary \
  --fact "Use traceary context --compact-only for compact resume context" \
  --evidence issue:#502

traceary context --handoff --workspace github.com/duck8823/traceary

5. Curate the memory review queue

traceary memory ... is grouped by intent: memory inbox for candidate review, memory store for deliberate writes (propose / distill), and memory admin for extraction, host-side I/O (import / export / activate), maintenance (hygiene / graph), and lifecycle (supersede / expire / set-validity). Daily-read commands (memory search / memory show) stay top-level; enumerate with memory search --all. The flat verbs from earlier releases (memory remember, memory accept, ...) were removed in v0.15.0 after the v0.14 compatibility window; memory store remember was removed in v0.36.0. Use the canonical grouped paths above.

For interactive review of the memory review queue at the terminal:

traceary memory inbox review
traceary memory inbox review --workspace github.com/duck8823/traceary --type preference --limit 10

memory inbox review is a TTY-only walk-through built on a shared Bubble Tea TUI. Inside the screen a accept, x reject, s skip, e edit/distill, r attach evidence (and optional artifacts), v view evidence, ? help, q quit. Edit/distill never auto-accepts LLM-authored text — it routes through traceary memory store distill and requires you to type the operator-authored fact. Non-interactive shells receive a refusal with exit code 2 and a pointer to the script-friendly fallback (memory inbox list plus memory inbox accept|reject, both of which now also accept a positional id and --id-only).

Inspect recent and live activity

Traceary ships complementary inspection views so you can switch between "what's happening now" and "what happened across a span" without leaving the terminal:

When	Command	Use it to
Discovering the command surface	traceary / traceary --help	print help (TTY and non-TTY)
Following what is happening now	traceary list --follow	confirm hooks are firing, watch failures in real time
Understanding what happened across a span	traceary list --blocks	see gap-separated work blocks with a per-workspace activity summary
Inspecting raw events directly	traceary list / traceary search	jump to an exact kind / session / query
Resuming with assembled working memory	traceary context --handoff	start a follow-up session with curated context

traceary list --follow

$ traceary list --follow --limit 3
07:06:44  command_executed  sess=4a70c526  ws=traceary  ls ~/.traceary 2>&1; find ~ -name "traceary…
07:06:47  command_executed  sess=4a70c526  ws=traceary  ./traceary list --blocks --db-path /Users/d…
07:06:52  command_executed  sess=4a70c526  ws=traceary  timeout 1 ./traceary list --follow --db-pat…

Compact single-line rows (local time by default) fit inside ~100 columns. Add --wide --utc to restore the pre-v0.6.1 tab-separated seven-column layout byte-for-byte, or --json for NDJSON when piping into tooling.

traceary list --blocks

$ traceary list --blocks --limit 2
2026-04-15 06:37 - 07:06 (29m21s) total events: 165
  github.com/duck8823/traceary (153) — 自律的に進めてください。
  github.com/duck8823/dotfiles  ( 12) — rust インストールしました
2026-04-15 05:39 - 06:10 (31m1s) total events: 136
  github.com/duck8823/traceary (136) — <analysis> This conversation is a resumption after compaction. …

Each block shows one sub-row per workspace with an activity summary picked from the fallback chain compact_summary → first prompt → kind counts, so you can see what was being done in each workspace instead of just a comma-joined list. Pass --utc to switch text timestamps to UTC; --json adds a workspace_breakdown array alongside the existing block fields.

See docs/cli/README.md for the full flag reference and more examples.

Host capture matrix

The query surface is shared: once Traceary is installed, every host can use the same CLI memory/context commands. What differs is how much context each host can capture automatically via hooks.

Host	Session lifecycle	Tool audit	Prompt capture	Compact-summary capture	Automatic capture tier
Claude Code	Full	Bash + MCP + failure hooks	Yes	Yes	Full
Codex	Full (SessionStart + Stop)	Tool hooks	Yes	No	Partial
Kimi Code	Full (SessionStart + SessionEnd)	Tool hooks + failure hooks	Yes	Markers (no summary body)	Full
Grok Build	Partial (SessionStart; SessionEnd documented but not emitted)	Tool hooks (result variants incl. failures)	Yes	Markers (no summary body)	Partial
Gemini CLI	Full (SessionStart + SessionEnd)	Tool hooks	No	No	Basic (legacy)
Antigravity	Full (PreInvocation start; Stop turn boundary)	run_command hooks (PreToolUse + PostToolUse paired)	No	No	Partial

v0.21.1 note: Gemini CLI is the legacy Google AI agent host. Antigravity (/Applications/Antigravity.app, bundle ID com.google.antigravity) is the active successor. As of v0.21.1, Traceary supports Antigravity as a real hook client with a packaged plugin (integrations/antigravity-plugin/) against the documented public hook surface. Install with traceary hooks install --client antigravity. The Gemini CLI extension package remains available for existing installs. See the Antigravity hooks and plugin guide.

2026 Q2 note: Claude Code's SubagentStop / PreCompact hooks are available but not wired into Traceary's managed hook set. The Codex memory feature flag in ~/.codex/config.toml changes Codex's own capture behaviour, not Traceary's — traceary memory admin import codex works regardless. traceary doctor surfaces the same notes under <client>-host-capabilities, and the full list lives in the hook contract.

For the full contract and hook semantics, see the hook contract and event lifecycle.

Defaults worth knowing

• traceary log and traceary audit reuse the latest non-stale active session for the resolved workspace 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 start prints a session ID; traceary session end prints the recorded event ID
• traceary search --json includes a sessions tier when summaries match the query
• 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
• Architecture principles
• Durable memory guide
• CLI reference
• CLI stability and deprecation policy
• Hooks guide
• Hook contract and capability tiers
• Event lifecycle
• Environment and storage notes

Contributing and support

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