Content
# 🐟 Remora
**See what your agent is actually doing.** A local, zero-config tap for LLM + MCP traffic with a live timeline UI.
Point your agent's base URL at Remora, and every model call and tool call shows up on a live waterfall with full payloads, token counts, and time-to-first-token. Think Wireshark, for agents.
<!-- TODO before launch: record the hero GIF against a real agent session and save it to docs/assets/hero.gif -->
## Quickstart
Start Remora and open the UI:
```sh
npx remora-ai
```
Open http://localhost:4100 and click **Setup**. From there you can do everything without touching a config file:
- **Connect** shows the base URLs to point any agent at, with copy buttons and a live "connected" indicator.
- **Integrations** detects Claude Code and lets you tap its LLM traffic and each stdio MCP server with a single toggle. Remora rewrites `~/.claude.json` / `~/.claude/settings.json` for you, keeps a `.remora.bak` backup, and untapping restores the original exactly.
- **Settings** covers the default session name, retention, and clearing sessions.
That's it: no API keys, no accounts, no hand-edited config. (Remora itself needs no keys; your agent's own API key flows through to the provider untouched.)
### Doing it by hand
Prefer the shell, or using an agent Remora doesn't auto-detect? Point any framework that respects base URLs at Remora:
```sh
export ANTHROPIC_BASE_URL=http://localhost:4100/anthropic
# or
export OPENAI_BASE_URL=http://localhost:4100/openai/v1
```
And wrap a stdio MCP server in your agent's config (this is exactly what the Integrations toggle writes for you):
```json
{
"mcpServers": {
"your-server": {
"command": "npx",
"args": ["remora-ai", "mcp", "--", "npx", "your-mcp-server"]
}
}
}
```
Remora sits between the agent and the server, forwarding stdin/stdout untouched while reporting every tool call to the timeline.
## How it works
```
┌─────────────────────────────┐
agent ── LLM calls ──► remora (localhost:4100) ├──► api.anthropic.com
│ │ ├──► api.openai.com
│ │ /anthropic /openai/v1 │
└── MCP stdio ─────► remora mcp -- <server> │
│ │
│ events ──► JSONL on disk │
│ └─► live UI (WS) │
└─────────────────────────────┘
```
Remora is a passthrough proxy. Requests and streaming responses are forwarded byte-for-byte to the upstream API; capture happens off to the side. The UI is a live waterfall: LLM spans in cyan, MCP tool calls in teal, errors in coral. Click any span to inspect the full request/response payload, token counts, and TTFT. A session picker lets you flip between runs.
## Your traces are just files
Every event is a line of JSON in `~/.remora/sessions/*.jsonl`. No database, no export step. Grep them, `jq` them, commit them, diff them, send one to a coworker:
```sh
jq -r 'select(.kind == "tool_call") | .payload.name' ~/.remora/sessions/*.jsonl | sort | uniq -c
```
Sessions roll over automatically after a 10-minute idle gap, or pin a name with `remora --session my-run`.
## Fail-open, local-only
Remora must never break your agent. Streaming passthrough is unconditional: if capture fails for any reason, bytes still flow and your agent never notices. The server binds to `127.0.0.1` only, and the UI's WebSocket checks `Origin` and `Host` headers, so neither remote hosts nor malicious web pages can reach your traces.
## v1 scope
In: Anthropic + OpenAI-compatible HTTP proxying, stdio MCP tapping, live timeline UI, JSONL sessions.
Not yet (deliberately): run diffing, OpenTelemetry export, HTTP/SSE MCP transports, auth, cost dashboards. If Remora can't show you what your agent did in the first ten seconds, nothing else matters.
## License
MIT
