traceary

README

Traceary

日本語

Changelog

Documentation guide

Contributing

Security policy

MCP guide

Backup guide

Release guide

Traceary is a local-first CLI and MCP server for recording and searching AI agent work logs and audit logs.

Why

Using AI agents in daily development creates a few persistent problems.

• Session context is easy to lose after clear / compact
• Git history can show what changed, but not always why it changed
• It is hard to see which agent ran which command
• Context gets fragmented across Claude / Codex / Gemini
• Parallel sessions and worktree moves make history harder to follow
• Log data keeps growing, so retention and gc matter

Traceary keeps session logs and audit logs in one local store, so multiple AI tools can read and write the same history.

Features

• Store session logs and audit logs locally in SQLite
• Search logs by text and date range
• Share context across Claude Code / Codex / Gemini via MCP
• Ingest session boundaries and shell audits from Claude Code / Codex / Gemini hooks
• Associate records with repositories by git remote URL
• Keep attribution with client, agent, and session_id
• Manage long-term data growth with retention and gc

Install

go install

go install github.com/duck8823/traceary@latest

Prebuilt binaries

Tagged releases publish macOS and Linux archives on GitHub Releases. See docs/release/README.md for the release flow and local snapshot builds.

Platform support

• prebuilt release archives are published for macOS and Linux
• the core CLI and traceary mcp-server are actively tested on macOS and Linux
• other Go-supported Unix-like environments may work via go install, but they are not part of the current support promise
• hooks currently target bash-based Unix-like environments; native Windows PowerShell / cmd.exe workflows are not supported today
• if you need Windows today, use WSL or another POSIX-compatible environment

CLI language

• default operator-facing help, success messages, and common errors use English
• set TRACEARY_LANG=ja when you want Japanese CLI messaging instead
• --json output is language-neutral

Quick start

If you only want to see what Traceary changes in daily work, this is the shortest loop.

traceary init is optional. Every command creates the SQLite DB and applies migrations on demand. Use init when you want to bootstrap the DB path explicitly or verify write permissions before a session starts.

traceary init
sid=$(traceary session start --client dogfood --agent codex)
traceary log --client dogfood --agent codex --session-id "$sid" "Investigating failing tests"
event_id=$(
  traceary audit \
    --client dogfood \
    --agent codex \
    --session-id "$sid" \
    "go test ./..." \
    '{"stdin":""}' \
    '{"stdout":"panic: boom","stderr":"stacktrace","exitCode":1}' |
    awk '{print $2}'
)
traceary search boom --json
traceary show "$event_id" --json
traceary session active

Example output:

$ traceary init
Initialized: /Users/you/.config/traceary/traceary.db

$ traceary session start --client dogfood --agent codex
session-1ceee1eaa50a31687cfdb2c8a6fcc85d

$ traceary audit ... | awk '{print $2}'
0dc6d0c579df5e539c27df56e131570a

$ traceary search boom --json
[
  {
    "event_id": "0dc6d0c579df5e539c27df56e131570a",
    "kind": "command_executed",
    "message": "go test ./..."
  }
]

$ traceary show 0dc6d0c579df5e539c27df56e131570a --json
{
  "event": {
    "kind": "command_executed",
    "message": "go test ./..."
  },
  "command_audit": {
    "output": "{\"stdout\":\"panic: boom\",\"stderr\":\"stacktrace\",\"exitCode\":1}"
  }
}

$ traceary session active
session-1ceee1eaa50a31687cfdb2c8a6fcc85d

Notes:

• traceary session active treats sessions older than 24h as stale by default
• use traceary session active --allow-stale when you need to inspect an old unclosed session

What changes after this:

• you can search past command output by text
• you can recover the current session ID without manually tracking it
• you can inspect one event in detail and hand it to another AI tool
• large audit payloads are truncated before they grow the DB too much

Core commands

Current core commands:

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

Useful search --kind values:

traceary search --kind command_executed
traceary search --kind note
traceary search --kind session_started

• valid values: note, command_executed, reviewed, session_started, session_ended
• alias: audit = command_executed

list and search use stable offset pagination with ORDER BY created_at DESC, event_id DESC. Use the same filters with a larger --offset when you want the next page.

traceary list --limit 20 --offset 20
traceary search boom --limit 20 --offset 40 --json

traceary session active defaults to --stale-after 24h; pass --allow-stale to inspect an older unclosed session.

traceary session start prints the session ID so scripts can capture it immediately. traceary session end prints the recorded event ID because the caller already knows which session it is closing.

Hook setup: docs/hooks/README.md

MCP integration: docs/mcp/README.md

Backup and machine transfer: docs/backup/README.md

All commands resolve the SQLite path in this order: --db-path → TRACEARY_DB_PATH → ~/.config/traceary/traceary.db.

traceary audit keeps input/output at 64 KiB each by default. Use --max-input-bytes, --max-output-bytes, or TRACEARY_MAX_AUDIT_INPUT_BYTES / TRACEARY_MAX_AUDIT_OUTPUT_BYTES when you want a stricter limit. The CLI prints a notice when truncation happens.

traceary audit also redacts common secret-like values before they reach SQLite (for example Authorization: headers, TOKEN=..., JSON access_token, and private key blocks). This is a best-effort safeguard, not a complete DLP system. Use --allow-secrets or TRACEARY_ALLOW_SECRETS=true only when you intentionally want raw payload persistence.

CLI failures are printed to stderr as plain Error: ... lines so hooks and shell scripts can parse them without JSON log noise.

License

MIT. See LICENSE.

Non-goals

• Semantic search / embeddings
• Team sharing or cloud sync
• Web UI / dashboard
• Enterprise audit / RBAC
• Full file-state snapshot reproduction
• Live observability

Documentation

Overview

Package main は traceary の起動関数を定義するパッケージです。 環境変数の読み込みと依存関係の組み立てはこのパッケージのみで行います。