trailback

Vendor-neutral CLI/TUI for browsing local agent logs.

Note: The package is called trailback (uv pip install trailback), but the CLI command is trail — short to type, easy to remember. See docs/NAMING.md for background.

Current MVP supports Codex, Claude, and Gemini sessions for listing, viewing transcripts, and usage stats.

Install

Install the CLI as a uv tool so the trail executable is available from anywhere:

uv tool install -e .

Ensure the uv tool bin directory is on your PATH (usually ~/.local/bin):

export PATH="$HOME/.local/bin:$PATH"

Verify:

command -v trail
trail tui

CLI

• trail sources
• trail ls [--source codex] [--no-cwd]
• trail ls [--group] [--header] [--show-ids]
• trail open <session_id> [--source codex]
• trail open <group_id>
• trail stats [--source codex] [--format text|csv|json] [--period all|daily|monthly|yearly] [--no-header]
• trail tui
• trail init [--path PATH] [--force]

Config

Use ~/.config/trail/config.toml to add sources. Default Codex example:

[sources.codex]
kind = "codex"
path = "~/.codex"
include = ["sessions/**/*.jsonl", "sessions/**/*.json"]

Claude example:

[sources.claude]
kind = "claude"
path = "~/.claude"
include = ["projects/**/*.jsonl"]

Gemini example:

[sources.gemini]
kind = "gemini"
path = "~/.gemini"
include = ["tmp/*/chats/session-*.json", "tmp/*/logs.json"]

Log sync (multi-machine)

Use scripts/sync-logs.sh to sync logs from a secondary machine to a primary. It is designed for one-way sync (secondary -> primary) and uses a quiet window to avoid in-progress files.

Manual run:

PRIMARY_USER=youruser PRIMARY_HOST=your-primary-host ./scripts/sync-logs.sh

Dry run:

DRY_RUN=1 PRIMARY_USER=youruser PRIMARY_HOST=your-primary-host ./scripts/sync-logs.sh

Optional SSH options:

SSH_OPTS="-i ~/.ssh/your_key -o StrictHostKeyChecking=accept-new" \
  PRIMARY_USER=youruser PRIMARY_HOST=your-primary-host ./scripts/sync-logs.sh

LaunchAgent example (runs every 6 hours):

~/Library/LaunchAgents/com.trail.logs-sync.plist

Reload after edits:

launchctl unload -w ~/Library/LaunchAgents/com.trail.logs-sync.plist 2>/dev/null || true
launchctl load -w ~/Library/LaunchAgents/com.trail.logs-sync.plist
launchctl kickstart -k gui/$(id -u)/com.trail.logs-sync

For design details, see docs/LOG_SYNC.md.