GitHub - Latand/live-log-viewer-next

Agent Log Viewer

agent-log-viewer is a local web UI that turns raw Codex / Claude Code agent logs into a readable, live-updating chat feed. It discovers every session, subagent and background shell task on your machine, links them into a parent→child tree, and tails the selected one in real time.

The default setup runs locally against transcripts already on disk. It reads ~/.claude and ~/.codex directly, while operational Viewer state is kept in a local SQLite database under its private configuration directory. Optional outbound integrations stay disabled until you configure them:

bunx agent-log-viewer   # or: npx agent-log-viewer

See WakaTime activity integration for opt-in activity export, its disclosure boundary, and disablement steps.

Prefer video? A 45-second cut of the full flow lives at docs/media/demo.mp4.

The tour

Read any session as a chat

User bubbles, assistant prose, tool-call cards with ✓/✗ statuses, expandable command output and diffs — for Claude Code sessions and their subagents (~/.claude/projects/**/*.jsonl), Codex CLI rollouts (~/.codex/sessions/**/rollout-*.jsonl) with command cards, patches and service events, and background shell tasks (recovered from the transcript and shown above the terminal output).

Hand a project to an orchestrator

Each project can designate one agent as its orchestrator. Press Orchestrator in the project header, tell it what you want shipped, and it opens a lane per issue, spawns the implementer, runs a fresh reviewer each round and merges on APPROVE. Its mandate and any handoff from a predecessor are written for you — there is no "you are an orchestrator" prompt to compose — and you come back to the board when an agent needs a decision.

docs/orchestrator.md walks the whole flow on a fresh install: the dock, the board, pipelines, tasks, the attention queue, the model/effort matrix the conveyor uses, and when three tasks a week does not need any of it.

Spawn agents from the board

Each project is a pannable, zoomable scheme — root conversations on top, spawned agents one generation below, arrows colored by engine. Draft a new agent right on the board: pick Claude or Codex, a model and reasoning effort, type the first prompt, and it launches into tmux.

Run implement → review loops

The viewer orchestrates review cycles: a long-lived implementer in tmux, a fresh read-only reviewer each round over the full diff, findings relayed automatically, and a verdict deck in the scheme view.

Answer a blocked agent from the browser

When an agent stops on an AskUserQuestion, the question surfaces as a card with clickable options. The answer is delivered into the agent's tmux pane and confirmed against the transcript — the agent just keeps going.

And everything around it

• Parentage tree: session → subagents → rollouts → background tasks, built server-side by scanning transcripts (append-only incremental, cached — the warm /api/files poll stays around 100 ms).
• Live activity: content-based badges — a transcript reads working while it is mid-turn and done once the final assistant message lands.
• Deep links: every selection is reflected in the URL (#f=<path>), so a link opens that exact log.
• English or Ukrainian UI, model chips (opus, gpt-5.6-sol, sonnet…), collapsible tree with persisted state, follow-mode autoscroll, service-event toggle, and a line filter.

The session parentage tree, wiring root conversations to their spawned agents:

A Codex CLI session	The overview board

All media above is regenerated deterministically from a synthetic fixture — see docs/media/README.md.

Run

The package is published to npm, so the quickstart above needs no clone:

bunx agent-log-viewer
# or
npx agent-log-viewer

This starts the server on 127.0.0.1:8898 and opens your browser. The CLI also starts and supervises the packaged structured runtime host, including restart backoff and Ctrl-C cleanup. Pipelines and the orchestrator work from this installation without Docker. Both launch paths require Bun because the runtime journal and authoritative state stores use Bun SQLite.

From a local clone

bun install
bun run build
bun bin/cli.mjs --no-open --port 8898 --hostname 127.0.0.1
# open http://127.0.0.1:8898/

The CLI serves the output of the last build, so run build first. For development, bun dev runs the app with hot reload and expects a separately managed runtime host (it needs a high OS file-watch limit for large home directories).

The Viewer server runs on Bun. The runtime journal and hot state collections use bun:sqlite, and macOS process ownership uses the kernel's microsecond start token. The Docker runtime and agent-log-viewer CLI select Bun for every feature-flag configuration.

Spawn transport

Agents launch through a structured runtime host. The installed CLI supervises that host with the same Bun executable as the Viewer and places its Unix socket and runtime journal under the Viewer state directory with installation-specific names. Ambient deployment runtime settings are ignored so separate bunx installations cannot attach to each other's host or claim each other's journal epoch. Startup fails clearly when Bun, the packaged host entry, the managed socket, or its directory permissions are unavailable. The CLI log carries the host failure and the pipeline card directs the operator to it. There is no tmux fallback.

Connect an orchestrator through MCP

The package includes agent-log-viewer-mcp, a local stdio MCP server. It invokes Viewer services in-process and shares their durable stores, locks, and idempotency rules. Keep the Viewer package and the MCP process under the same OS user so they resolve the same state directory.

For an installed package, add this server to the orchestrator's standard MCP configuration:

{
  "mcpServers": {
    "viewer": {
      "command": "agent-log-viewer-mcp"
    }
  }
}

For a local clone, point the client at the launcher:

{
  "mcpServers": {
    "viewer": {
      "command": "bun",
      "args": ["/absolute/path/to/live-log-viewer-next/bin/mcp-server.mjs"]
    }
  }
}

Quick install from the CLI:

# Claude Code (user scope)
claude mcp add viewer -s user -- bun /absolute/path/to/live-log-viewer-next/bin/mcp-server.mjs

# Codex — append to ~/.codex/config.toml
[mcp_servers.viewer]
command = "bun"
args = ["/absolute/path/to/live-log-viewer-next/bin/mcp-server.mjs"]

To register the server everywhere at once — the operator's Claude Code and Codex configs plus every Viewer-managed account under ~/.config/agent-log-viewer/accounts (their spawned agents each run with their own CLAUDE_CONFIG_DIR/CODEX_HOME, so each account needs its own registration) — run the idempotent installer and re-run it after adding accounts:

scripts/install-mcp.sh                     # uses the managed stable launcher when present
LLV_MCP_BIN=/path/to/mcp-server.mjs \
  scripts/install-mcp.sh                   # select an explicit launcher

Exact deployments keep the managed executable at ~/.agents/tools/llv-mcp-runtime/bin/mcp-server.mjs. Existing Claude and Codex registrations retain that path. Each fresh MCP process reads the atomic Viewer release target and starts the runtime bundle staged from the same revision. Deployment receipts expose the staged runtime digest plus durable activation or restore evidence.

The server name must stay viewer (or another isViewerMcpServer() match: viewer-*, agent-log-viewer*) — transcript calls attributed to other names do not render as Viewer cards.

The MCP surface includes:

• conversations and the board: board_snapshot, list_conversations, get_conversation, send_message, message_receipt (what became of an accepted send, by its operation id), and conversation_action for interrupt, kill, resume, compact, and dialog-key;
• review flows: list_flows, get_flow, and flow_action;
• pipelines: create_pipeline, list_pipelines, get_pipeline, pipeline_action, and link_task_to_pipeline;
• tasks: create_task, list_tasks, get_task, and update_task;
• operator/runtime reads: operator_snapshot, deployment_status, and resources;
• agent liveness and lifecycle: agent_activity for the per-conversation {lastRecordAt, turnState, host alive/gone, stalledForMs} stall snapshot, and lifecycle_events for the durable lifecycle journal (mode: "query", by project/pipeline/conversation and cursor) and its bounded relay digest (mode: "digest", terminal events immediately, routine progress coalesced and rate-limited to one per five minutes per subscriber);
• agent/runtime mutations: spawn_agent, conversation_migration, and deploy_exact_sha;
• the operator's attention: request_attention, which offers to move their Viewer to a target and waits for their answer. It only asks — nothing moves until they agree on a device, and the request names the root agent by an identity the server resolves, never one the caller supplies.

Every call requires a stable clientRequestId. Reusing that id with the same arguments returns the durable result as a replay. Reusing it with different arguments returns an idempotency conflict. Read tools are inert, bounded, and secret-redacted. Mutating tools return stable operation receipts, and their durable MCP receipt prevents a replay from applying the action twice. deploy_exact_sha accepts a full 40-character commit SHA and requires confirm: "deploy".

The package exposes the MCP launcher as agent-log-viewer/mcp-server in addition to the agent-log-viewer-mcp executable.

Tool results contain the durable entity identifiers available for that action, including conversation ids, transcript paths, pipeline ids, task ids, and runtime operation ids. Viewer transcripts render calls attributed to the viewer MCP server as live cards and turn those identifiers into navigation chips.

Prerequisites: Node ≥ 20.9, and bun or npm/pnpm. tmux is optional — see Platform support.

Docker (reproducible runtime)

For a pinned, reproducible deployment the repo ships a Dockerfile and docker-compose.yml that build .next inside the image and run the Viewer with host parity. The container reuses your real tmux, claude, codex, and home directory. Runtime-host owns production releases and the listener. Complete the bootstrap listener migration before the first runtime-host activation.

export LLV_DOCKER_GID="$(stat -c %g /var/run/docker.sock)"
LLV_RUNTIME_EVENTS=1 LLV_VIEWER_DEPLOYMENTS=1 docker compose --profile runtime-host up -d runtime-host
scripts/rebuild.sh
LLV_TEST_PORT=8901 docker compose --profile test up -d viewer-test

See docs/docker.md for the parity model, the nsenter shims, and volume/port details.

Attach to a live tmux pane

The Viewer resolves and copies a complete command for each live pane. Paste that command into a normal shell; it selects the supervisor endpoint and the current pane coordinate. The read-only variant adds -r.

TMUX_TMPDIR='/run/user/1000/agent-log-viewer' tmux attach-session -t 'agents:2.0'
TMUX_TMPDIR='/run/user/1000/agent-log-viewer' tmux attach-session -r -t 'agents:2.0'

Detach with Ctrl-b d and the agent keeps running. An unqualified tmux command may use a different server. Refresh and copy again after a stale-pane or restarted-server message; the fresh command accounts for window renumbering. See the Docker guide for the supervisor migration context.

CLI options

agent-log-viewer [options]

Platform support

Linux is the native target: process discovery reads /proc directly. macOS is supported through a portable backend that shells out to ps and lsof instead — same live-process detection, tmux composer targeting, agent spawn/kill and background-task discovery, just a bit more subprocess overhead per scan. The backend is chosen automatically by process.platform (see src/lib/proc/); VIEWER_PROC_BACKEND=portable forces the portable path on Linux too, for testing.

The package supports Linux and macOS. The package's os field blocks Windows installs with EBADPLATFORM. WSL works as Linux.

tmux is optional. Without it, log viewing, the parentage tree, live activity and deep links all work; the composer, agent spawn/kill and resume-into-pane features need tmux (brew install tmux on macOS, or your distro's package on Linux).

Language

The UI defaults to English and shows a compact EN/UK toggle in the project list header. The locale is resolved as localStorage key llv_lang first, then the browser language (Ukrainian if the browser prefers it), then English.

CLI messages are English by default, and switch to Ukrainian with LLV_LANG=uk or a uk_* value in LANG/LC_ALL.

Dictation / voice input

Composers that talk to agents have a mic button for dictating messages. By default transcription runs fully locally via faster-whisper — no audio leaves the machine. Run scripts/setup-whisper.sh once to install the local engine.

Two cloud backends are available as an explicit per-machine opt-in (never a UI toggle): ChatGPT (reuses your local Codex login) and ElevenLabs Scribe (the only one with live, streaming transcription). Select with LLV_TRANSCRIBE_BACKEND=local|chatgpt|elevenlabs or by writing the backend name to ~/.config/agent-log-viewer/transcribe-backend; local is the default.

See docs/transcription.md for setup, key locations, and troubleshooting.

Review loops

The viewer orchestrates implement→review cycles: a long-lived implementer agent in tmux, a fresh read-only reviewer per round over the full diff, automatic relay of findings, and a verdict deck in the scheme view. Start one from the Flow chip above a conversation pane; presets pair engines and reasoning efforts per role (e.g. Terra high → Sol xhigh). New Codex agents also expose explicit GPT-5.6-Sol and GPT-5.6-Terra choices beside effort and speed.

See docs/review-loop.md for the round protocol, presets, the HTTP automation API, and troubleshooting. A Claude Code skill for driving flows from an agent ships in .claude/skills/review-loop/ — agents working in a clone pick it up automatically.

Tailscale access

bunx agent-log-viewer --tailscale

--tailscale starts the local server on 127.0.0.1 and exposes it inside your tailnet through a foreground tailscale serve <port> process. The public internet (Funnel) is never used.

The CLI generates a 32-character access key, appends it to the tailnet URL as ?k=..., and after the first visit the server sets an llv_auth cookie for 30 days. --new-token generates a fresh key and immediately invalidates every old cookie — each request compares the hash against the current token, so a cookie minted with a previous key no longer passes.

The terminal prints the tailnet URL along with a QR code to scan with a phone. The same QR is available inside the web UI: the QR-icon button in the project list header opens a popover with the code and the link as text (with a copy button). The QR is rendered entirely client-side (the qrcode package, no external requests) and is served only to already-authorized clients — the same token gate from src/proxy.ts also protects /api/access. When the server runs without --tailscale, the button shows a hint to start bunx agent-log-viewer --tailscale.

Anyone with tailnet access to this URL can read all agent transcripts, including any sensitive data that landed in a session, and can execute commands through /api/tmux and /api/spawn. Treat the tailnet URL as a secret — do not forward it to anyone else.

Security model

The log APIs refuse any path that does not resolve into one of the whitelisted log roots (see src/lib/scanner/roots.ts). Mutating endpoints exist: /api/tmux sends keys to tmux sessions and /api/spawn starts commands.

By default the CLI binds to 127.0.0.1. With --tailscale, access is exposed inside the tailnet via tailscale serve and guarded by the token gate in src/proxy.ts. Non-loopback binds also force token mode. Treat any URL containing ?k= as a credential.

Environment variables

All optional. Transcription variables are documented in full in docs/transcription.md.

Config paths

The viewer keeps its state under the standard XDG directories, named after the package:

• ~/.config/agent-log-viewer/ — access token, transcribe-backend, and elevenlabs-api-key.
• ~/.cache/agent-log-viewer/whisper-venv — the local transcription virtualenv.

Legacy live-log-viewer paths remain valid fallbacks. When a legacy config or cache file is the resolved existing file, subsequent updates keep using that same path so existing setups continue without a forced move.

Architecture

See ARCHITECTURE.md: route handlers under src/app/api/*, a pure scanner pipeline under src/lib/scanner/* (discover → describe → activity → model → links), React components under src/components/*. Caches live on globalThis and survive dev hot-reload.

License

MIT