aitail

A terminal UI that tails the logs your coding agents leave behind — Claude Code and Codex — and renders them as a clean, live, readable feed. Think tail -f for your agent sessions, with a master-detail layout, per-session token/cost stats, error and token-spike call-outs, and themes.

Built with ratatui. No agent is contacted and nothing is sent anywhere — aitail only reads the session transcripts already on your disk.

Features

• Live feed of a focused agent session: user/assistant messages, thinking, tool calls, and tool results, formatted for reading instead of raw JSONL.
• Master-detail layout — a sidebar of sessions (project name, model, tokens, cost, relative time, live/idle dot) and a feed pane for the focused session.
• Truthful liveness — the ● live dot means an agent is actually running right now, read from each agent's own process state (Claude status:busy + live pid, Codex live pid), not guessed from file mtimes.
• Recognizable names — sessions are named by their git repo (worktrees resolve to the main repo), deduped per project, with stale/renamed/dead paths hidden from the default view.
• Call-outs — failed tool results get a red ⚠ ERR badge and tinted panel; unusually large turns get a ⚡ token-spike badge.
• Per-session stats — running token totals, a rough cost estimate, and context-window usage in the status bar.
• Filtering — cycle the sidebar between live (an agent running now), active (recent, on-disk projects, deduped), and all (full history, nothing hidden).
• Themes — midnight (GitHub Dark High Contrast) and daylight (GitHub Light High Contrast); cycle with t.
• Resilient — never crashes on malformed/unknown records, tails huge logs without loading them entirely into memory, and restores your terminal cleanly on exit.

Supported sources

Agent	Where aitail reads	Status
Claude Code	~/.claude/projects/<project>/<session>.jsonl	✅ supported
Codex CLI	~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl	✅ supported
OpenCode	split JSON / server SSE	🚧 planned

If a source directory doesn't exist (e.g. you don't use Codex), aitail simply shows nothing for it.

Install

Requires a Rust toolchain (edition 2021).

From this repo:

./scripts/install.sh

By default, this builds the release binary and installs it to ~/.local/bin/aitail.

Choose another install directory:

AITAIL_INSTALL_DIR=/some/bin ./scripts/install.sh

Or build/install manually:

cargo build --release        # binary at ./target/release/aitail
cargo install --path .       # installs aitail onto your cargo PATH

Usage

aitail                          # tail your real Claude Code + Codex sessions
aitail --demo                   # fake, looping, realtime demo data (no real logs)
aitail --active-window-secs 600 # treat sessions written in the last 10 min as "active"
aitail --help

On launch the sidebar lists your sessions, most-recently-active first. Select one and press ⏎ to focus it; its feed streams live. Press q to quit.

Keybindings

Key	Action
↑ / ↓	move the session selection
⏎	focus the selected session (start tailing it)
j / k	scroll the feed down / up one line
PageDown / Space / PageUp	scroll the feed by a page
g / Home	jump to the top of the feed
G / End	jump to the bottom (resume live-follow)
a	cycle filter: live → active → all
t	cycle theme: midnight ↔ daylight
n / N	jump to next / previous flagged event (errors, spikes)
q / Esc	quit

While following, the feed stays pinned to the newest event; scrolling up detaches follow so the view holds still, and G snaps back to live.

How it works

Each agent has a small adapter that knows how to discover its sessions and parse its log records into one shared, normalized event model. Everything above the adapter — the UI, the highlight rules, the stats — only ever sees normalized events and never the raw formats, so adding a new agent is one new adapter. Two background threads (a session discovery poller and a tailer that follows the focused file) feed the UI over channels; there's no async runtime.

Privacy

aitail is read-only and local. It opens the transcript files your agents already write under your home directory and renders them. It never contacts the agents, the model providers, or any network service.

License

MIT.