Quickstart

From clone to first capture — 10 minutes

Six steps. Five terminals. One end-to-end loop: gateway capturing Claude Code's traffic, dashboard showing the realtime feed, TUI rendering metric cards, and an MCP server letting Claude Code query its own past sessions.

What you'll have at the end

  • A Recondo gateway on :8443, TLS-MITM capturing all agent-to-LLM traffic
  • A PostgreSQL database with your first captured sessions, turns, and tool calls
  • The dashboard at http://localhost:5173 rendering the realtime feed
  • The TUI in another pane updating metric cards within 500 ms
  • Claude Code querying its own captured history via MCP — ask "what tools have I called in the last hour?" and watch it call recondo_tool_call_stats

Prerequisites

Required Why
gitClone the repo
Docker + ComposePostgreSQL + MiniStack (S3/IAM/KMS emulation)
Rust 1.80+Build the gateway and TUI (rustup)
Node 20+ · pnpm 10+API and MCP services, dashboard build
Agent clientClaude Code, Cursor, or Goose
2 GB disk · ports freeContainers, build artifacts, the ports below

Ports the stack needs free

:8443 · GatewayTLS-MITM listener for all agent traffic
:4000 · APIGraphQL @ /graphql · REST @ /v1/*
:4001 · MCPStreamable HTTP @ /mcp for agent introspection
:5173 · DashboardReact + Vite dev server
:5432 · PostgreSQLCaptures schema, append-only triggers
:4566 · MiniStackS3 / KMS / IAM emulation

Optional but recommended: just (brew install just) and tmux/screen for the multi-terminal layout below.

Step 1 — Clone & bootstrap

git clone github.com/recondodev/recondo
cd recondo
just setup       # installs cargo-nextest (one-time, ~30s)
just dev-setup   # starts Postgres + MiniStack and runs migrations (~2 min)

Manual control if you don't want the combined recipe: just dev-infra  ·  just api-migrate.

Step 2 — Start the stack (four terminals)

Terminal 1 · just dev-run-localGateway on :8443 writing to Postgres + local objects
Terminal 2 · just api-devGraphQL API on :4000
Terminal 3 · just dashboard-devVite dev server on :5173
Terminal 4 · (ready for Claude Code)Keep this terminal available for Step 4

Step 3 — Install the gateway CA

# One-time: sync the gateway CA into the system trust store
just dev-trust

Step 4 — Route Claude Code through the gateway

NODE_EXTRA_CA_CERTS=$HOME/.recondo/ca/ca.crt \
HTTPS_PROXY=http://localhost:8443 \
claude

Send a trivial prompt ("what time is it?") and wait for the response. Open http://localhost:5173/ — within 5 seconds a new row appears in the realtime feed with session id, user, timestamp, token count, and cost.

Step 5 — Run the TUI

cargo run -p recondo-tui

First run compiles in 30–60 seconds; subsequent runs are instant. The TUI lands on the realtime lens — press s for sessions, c for cost, a for agents. Full keybindings on the TUI page.

Step 6 — Register the MCP (optional)

recondo-mcp config claude-code >> ~/.claude/mcp_servers.json

Restart Claude Code, run /mcp to confirm recondo is registered, then ask: "What tools have I called in the last hour?" — the agent invokes recondo_tool_call_stats and returns structured results. Full setup details on the MCP page.

Verify everything works

  • Dashboard at http://localhost:5173 shows a non-zero session count
  • API responds at http://localhost:4000/graphql (a GET returns 400 / 200, not connection refused)
  • TUI realtime lens (d) renders metric cards within 500 ms of the dashboard
  • Claude Code invokes recondo_tool_call_stats when asked about recent tool usage

Where the data lives

Location Contents
~/.recondo/objects/req/Gzipped request bodies — content-addressable, deduplicated by SHA-256
~/.recondo/objects/resp/Gzipped response bodies
~/.recondo/captures/JSON metadata linking req/resp hashes, session id, timestamps
PostgreSQL :5432Normalized schema — sessions, turns, tool_calls, costs, tokens

Common first-run problems

"Connection refused" on :8443

Gateway didn't bind. lsof -i :8443 to see what holds the port; verify Rust is installed with rustup --version; re-check Terminal 1 for the TCP listener bound to 127.0.0.1:8443 line.

"Invalid CA cert" / CERTIFICATE_VERIFY_FAILED

The agent doesn't trust the gateway's CA. Re-run just dev-trust. Last-resort fallback for debugging only: NODE_TLS_REJECT_UNAUTHORIZED=0 — do not use this in production; it disables certificate validation entirely.

Dashboard shows "No data" / GraphQL 500

The API can't reach Postgres. docker ps | grep postgres, then psql -h localhost -U recondo -d recondo -c "SELECT COUNT(*) FROM sessions;" (password recondo_dev). Zero rows means the gateway never wrote captures — re-check Step 4.

"Another recovery in progress"

A prior gateway crashed while holding the recovery lock. Inspect with lsof ~/.recondo/.recovery.lock. If a PID is alive, kill it; if the process is gone, remove the stale lock and re-run just dev-run-local.

TUI doesn't show data

Verify the gateway and API are both running, then confirm you've sent at least one prompt through Claude Code. For TUI-side debugging: cargo run -p recondo-tui 2>&1 | tee tui.log.

Next steps

You're now end-to-end. Pick where to go deeper:

Read the architecture TUI keybindings & lenses MCP install & tool catalog CLI reference & env vars