neatroots

See, check and replay your AI agent's runs on your own machine while you build it.

neatroots is where an agent starts out. It runs on your laptop, reads the traces your agent already
sends, catches what went wrong, and hands the evidence to your coding agent. When the agent grows up,
the same SDK sends its runs to Neatlogs Cloud instead. Nothing leaves your
machine unless you send it.

What it does

• Takes runs from anywhere. The Neatlogs SDKs (Python,
  TypeScript, Go, Browser), the Neatlogs HTTP trace API, or any OpenTelemetry exporter over OTLP
  HTTP or gRPC (OpenInference, OpenLLMetry, GenAI and Vercel AI SDK attributes). It also imports
  trace files, and pulls production traces from Neatlogs Cloud.
• Checks every run. Rules in code on every span (loops, repeated tool calls, error streaks,
  leaked keys, failed or empty runs). Yes/no questions picked for your agent, each answered with a
  probability by a decision model. An explanation with a suggested fix when something goes wrong.
• Shows a run four ways. An Overview that reads like a chat (user, assistant, tool calls,
  sub-agents you can open), the Trace tree, a Timeline, and the Conversation across a
  session's turns.
• Replays. Re-run one LLM call with an edited message, model or system prompt (no agent needed),
  or re-run the whole agent from the app. Edit a user message in the Overview to fork the run.
• Finds things. Search across every run's inputs, outputs and errors, with filters such as
  status:failed tool:lookup since:24h. ⌘K from anywhere.
• Works with your coding agent. neatroots connect gives Claude Code, Codex, Cursor and six
  others 23 MCP tools: read a run, explain it, search, compare runs, run SQL, write a check, replay.
  Or chat with Claude Code and Codex inside the app, with those tools attached.
• Nudges the running agent (opt-in). A finding becomes a note in the agent's next LLM call, or a
  check_my_work tool it can call.
• Runs locally by default. A local LLM (Ollama, LM Studio, llama.cpp, MLX) and a local decision
  model (Laya). Claude, OpenAI and other hosted
  models are opt-in.

How it works

flowchart TB
  AGENT["Your agent<br/>Neatlogs SDK · OpenTelemetry · HTTP API"]
  OTHER["Trace files · Neatlogs Cloud"]

  subgraph roots["neatroots · localhost:4100"]
    COL["Collector<br/>OTLP HTTP and gRPC · /v1/trace"]
    STORE[("Local store<br/>SQLite, lossless spans")]
    CHECKS["Checks<br/>rules → decision model → LLM"]
    COL --> STORE
    STORE --> CHECKS
  end

  subgraph out["Where it goes"]
    UI["Web app<br/>Overview · Trace · Timeline<br/>Conversation · Search · Replay"]
    MCP["Coding agents over MCP<br/>Claude Code · Codex · Cursor · …"]
    CLOUD["Neatlogs Cloud<br/>opt-in, redacted"]
  end

  AGENT --> COL
  OTHER -->|import| STORE
  CHECKS --> out
  CHECKS -.->|opt-in| STEER["Steering<br/>a note on the agent's next LLM call"]

The loop it is built for: run the agent, see what went wrong, let a coding agent fix it, replay,
compare.

sequenceDiagram
  autonumber
  actor You
  participant Agent as Your agent
  participant R as neatroots
  participant CA as Coding agent
  You->>Agent: run it
  Agent->>R: spans, as the run goes
  R->>R: rules, questions, explanation
  R-->>Agent: a note on the next LLM call (steering, opt-in)
  You->>R: open the run: problems, Overview, Trace, Timeline
  You->>CA: "Fix what neatroots found in my last run"
  CA->>R: MCP: get_current_run, explain_run, get_span
  CA->>CA: fixes the code, adds a check
  CA->>R: replay the run
  R->>Agent: same input, new code
  CA->>R: compare_runs: before and after
  You->>R: send a clean run to Neatlogs Cloud (opt-in)

Install

curl -fsSL https://raw.githubusercontent.com/neatlogs/neatroots/main/install.sh | sh
neatroots start                    # open http://localhost:4100

The installer downloads one prebuilt bundle (about 17 MB, macOS and Linux, arm64 and x64) into
~/.neatroots, uses your Node.js if it is 22 or newer (otherwise it fetches its own), puts a
neatroots command in ~/.local/bin, and offers to connect the coding agents it finds. No sudo, no
git, no build. Add -s -- --service to run neatroots at login. On Windows, use WSL.

The installer then asks whether to download Laya, the open model that answers neatroots' yes/no
checks on your machine (about 1.4 GB, once). Say no and set up Jev cloud for those answers instead
(neatroots jev login && neatroots jev on); until one of them is set up, your LLM answers them,
more slowly. Rules work right away either way, and you can change your mind in Settings → Decision
model.

Try it in two minutes, without API keys

The bundle ships 15 runnable examples and a mock LLM that speaks the OpenAI and Anthropic APIs:

neatroots mock-llm &
cd ~/.neatroots/app/examples/python-openai     # or examples/ in a clone of this repo
uv run agent.py "Please refund order 1001"
MODEL=mock-sloppy uv run agent.py "Please refund order 4512"   # claims success after a failed tool

Open http://localhost:4100 and click the run. sh ~/.neatroots/app/examples/run-all.sh runs every
example and checks each one produced a run. examples/ lists them: OpenAI, Anthropic,
LangGraph, OpenAI Agents SDK handoffs, sub-agents, multi-turn sessions, replay, plain OpenTelemetry,
TypeScript, Vercel AI SDK, the HTTP API, a browser page, and trace files to import.

Send your agent's runs

An agent that uses the Neatlogs SDK needs only two environment variables:

export NEATLOGS_ENDPOINT=http://localhost:4100
export NEATLOGS_API_KEY=neatroots-local      # any value works locally

import neatlogs
neatlogs.init(workflow_name="refund-agent", flush_interval=0.5, instrumentations=["openai"])

instrumentations names the libraries to trace ("openai", "anthropic"). Without it
init records only the spans you create yourself, and a plain OpenAI agent shows no runs.
flush_interval=0.5 lets neatroots check a run while it is still going. In production, unset
NEATLOGS_ENDPOINT and the same code sends to Neatlogs Cloud.

Add data in the app shows each of these with this machine's ports filled in.
python -m neatlogs doctor --probe passes against neatroots.

Use it

• Home shows how your agents have done over 24 hours, 7 or 30 days: what keeps failing, which
  tools and models break, what holds up.
• Runs lists every run with its most important open problem. A run page leads with its problems,
  each with a cause, a fix and the span that shows it. Explain run writes a likely cause for the
  whole run.
• Replay on a run re-runs one LLM call with your changes, or the whole agent once you register
  how to start it: neatroots rerun add <project> "uv run agent.py". During a replay the agent sees
  NEATROOTS_REPLAY_INPUT, _MODEL and _SYSTEM_PROMPT; neatroots_steer.replay_input() and
  wrap() apply them. Replays are new runs linked to the original.
• Search (⌘K) finds text in any span. Filters: project: status: kind: tool: model:
check: session: has:problems since:7d.
• Checks lists the rules and questions in force. New check turns a sentence into a check and
  previews it on recent runs. Checks are YAML; keep shared ones in your repo's .neatroots/checks/.
• Coding agents chats with Claude Code or Codex in your project folder, with neatroots' tools
  attached. Read-only unless you allow edits or commands for that chat.

Coding agents (MCP)

neatroots connect     # Claude Code, Codex, Cursor, OpenCode, Windsurf, Amp, Gemini CLI, VS Code, Claude Desktop

Each agent gets a neatroots entry in its own MCP settings; Claude Code and Codex also get four
skills. Any other MCP client can use http://localhost:4100/mcp or neatroots mcp (stdio). Then ask:
"Fix what neatroots found in my last run, and add a check so it's caught next time."

See docs/mcp.md.

Models

Rules need no model. Questions, explanations and notes need an LLM: a local one by default
(ollama pull qwen3:8b; neatroots picks one that fits your memory), or a hosted one you turn on:

neatroots llm login anthropic && neatroots llm use anthropic   # claude-opus-5-5; --model to choose
neatroots llm local                                            # back to this machine only

With a hosted LLM on, the run content each LLM task needs is sent to that provider with secrets
removed. Rules, storage and the app stay local. Settings → Models does the same in the app.

Steering (opt-in)

pip install ~/.neatroots/app/steer/python/neatroots-steer     # TypeScript: npm install ~/.neatroots/app/steer/ts
neatroots steering advisory --project refund-agent

import neatroots_steer
client = neatroots_steer.wrap(OpenAI())      # or Anthropic(); sync or async

Modes: advisory (a note on the next LLM call), gate (each call waits up to 300 ms for pending
checks), self-check (the agent gets check_my_work), and halt from rules you write. At most one
note per call and three per run. See docs/steering.md.

What leaves your machine

neatroots listens on 127.0.0.1 only. API keys live in the macOS Keychain (on Linux, a file only you
can read) and never in the database.

Commands

Documentation

• Getting started: install, models, sending runs, reading them, replay,
  coding agents, privacy and troubleshooting.
• Tester guide: a 45-minute session for people trying neatroots, and what to
  report.
• Use case, architecture, checks,
  steering, MCP, Neatlogs Cloud.

Repository

Development

pnpm install && pnpm build    # UI, then the server (copies the UI into packages/neatroots/dist/ui)
pnpm test                     # server tests (vitest)
pnpm --filter @neatlogs/neatroots-ui e2e     # UI end-to-end tests (Playwright; real server, mock LLM)
cd packages/steer-ts && pnpm test
cd python/neatroots-steer && python -m pytest
sh examples/run-all.sh        # every example, against a running neatroots
pnpm --filter @neatlogs/neatroots dev        # server with reload on 4100
pnpm --filter @neatlogs/neatroots-ui dev     # UI on 5173 (set NEATROOTS_DEV_ORIGIN=http://localhost:5173 on the server)

neatroots is built from public inputs: the public Neatlogs SDKs and their telemetry schema,
OpenTelemetry, MCP, publicly documented APIs, and openly licensed models. Issues and pull requests
are welcome; AGENTS.md has the conventions.

License

Apache-2.0. See LICENSE.