Agent Trail — Development skill for Claude Code

AgentTrail

Local (self-hosted) web viewer to browse **Claude Code** and **Codex CLI** conversation history across **multiple profiles**.

[](https://github.com/softaworks/agent-trail/actions/workflows/checks.yml) [](https://coveralls.io/github/softaworks/agent-trail?branch=main) [](LICENSE)

AgentTrail scans configured folders (for example `~/.claude/projects` plus backups), lists sessions by project/profile, supports **quick/deep search**, **pinning**, **custom tags**, and live updates (SSE + file watch).

For the full specification (features, endpoints, UI), see `SPEC.md`.

Why

Many viewers assume a single session location (usually `~/.claude`). AgentTrail adds:

• Multi-profile support via persistent config (~/.config/agenttrail/config.json)
• Profile-isolated chaining (sessions only chain within the same profile)
• Pins and custom tags that persist across restarts
• Quick search (client-side) and deep search (server-side, scans file content)
• Live updates while .jsonl session files change
• Support for multiple session sources (Claude + Codex) with per-profile configuration

Requirements

• Bun >= 1.0.0

Install (local dev)

bun install

Usage

Quickstart (no install)

# Bun
bunx agenttrail

# npm (still requires Bun installed on your machine)
npx -y agenttrail

Run from source

Start the server:

bun run start

Open:

• http://localhost:9847

CLI

The entrypoint is a CLI (`src/index.ts`) that starts the Elysia server:

# help
bun run start -- --help

# custom port
bun run start -- --port 8080

# initialize config (if it doesn't exist yet)
bun run start -- --init

Build the executable:

bun ru