Metadata-Version: 2.4
Name: trailback
Version: 0.1.0
Summary: Vendor-neutral CLI/TUI for browsing local agent logs
Project-URL: Homepage, https://trailback.dev
Project-URL: Repository, https://github.com/vr000m/trailback
Project-URL: Issues, https://github.com/vr000m/trailback/issues
Author: Varun Singh
License: MIT
License-File: LICENSE
Keywords: agent,ai,claude,cli,codex,gemini,logs,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: textual>=0.57.1
Requires-Dist: tiktoken>=0.7.0
Description-Content-Type: text/markdown

# 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](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=vr000m PRIMARY_HOST=trail-primary ./scripts/sync-logs.sh
```

Dry run:

```
DRY_RUN=1 PRIMARY_USER=vr000m PRIMARY_HOST=trail-primary ./scripts/sync-logs.sh
```

Optional SSH options:

```
SSH_OPTS="-i ~/.ssh/id_ed25519_trailsync -o StrictHostKeyChecking=accept-new" \
  PRIMARY_USER=vr000m PRIMARY_HOST=trail-primary ./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`.
