简体中文 · Install · NexoToken setup guides · Compatibility · Report an issue
A local reliability and guidance layer for AI coding agents.
Agent Doctor is an open-source local tool by NexoToken, an AI API and agent tools platform for developers.
Codex and Claude Code do the work. Agent Doctor watches the evidence, detects when a task is looping, losing context, or trying to finish without validation, and sends a bounded next-step instruction back to the running agent. It also explains why a task became slow, expensive, repetitive, or unreliable. Missing data stays unavailable instead of becoming a fabricated zero.
Its shared project brain also carries work across clients. When you leave a captured Codex task and open Claude Code in the same repository, Agent Doctor automatically injects a bounded handoff containing the latest goal and result, confirmed project memory, source provenance, and explicit limitations. It does not paste the full transcript, and every delivery is visible in the local dashboard.
The guidance engine is deterministic, runs locally, and does not call another model. Raw prompts, source files, commands, tool inputs, and tool results are not used by the guidance rules; supported hooks retain only bounded labels and non-reversible evidence fingerprints.
Clone the repository and run one command. It installs dependencies, builds and tests the product, installs the binary, configures the owned Codex and Claude Code assets, opens the dashboard, and keeps the local service running:
./scripts/install-local.shstart checks and idempotently prepares the Agent Doctor-owned Codex integration,
refreshes detected clients, starts the loopback services, and opens the dashboard
in the default browser. Use start --no-open when you want to copy the printed
URL yourself. Agent Doctor never binds a public interface. The dashboard includes
Overview, Task evidence, Costs, Memory, Comparison, Trends, Integrations, and
Privacy.
The simplest live capture path reuses the API base URL already configured in your terminal and injects the local proxy only into the child process:
agent-doctor start # check integrations and open dashboard
agent-doctor run -- codex # start Codex with live capture
# or: agent-doctor run -- claudeAGENT_DOCTOR_UPSTREAM_URL has priority when a client does not expose its
configured base URL through OPENAI_BASE_URL or ANTHROPIC_BASE_URL. A client
that was already running must be restarted through the wrapper; Agent Doctor
does not attach to arbitrary existing processes or rewrite credentials.
The published v0.1.0-beta.1 archives and checksums passed independent verification. Install the public beta with:
curl --fail --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/18534516725/Agent-Doctor/main/install.sh | shirm https://raw.githubusercontent.com/18534516725/Agent-Doctor/main/install.ps1 | iexBoth installers download only the official GitHub release, verify its SHA-256, install the binary, and run the consented setup step. See installation and uninstallation before using a remote installer.
agent-doctor doctor --json
agent-doctor diagnose --json
agent-doctor costs --json
agent-doctor dashboard --no-openThe first dashboard panel is the Task Guardian: it shows whether work is on track, needs redirection, is waiting for validation, or has been blocked by a capable hook. The result states evidence provenance and precision. A diagnosis is not a verdict: unsupported evidence and absent billing records remain visible limitations.
- Claude Code: official hooks can return guidance and, in
guardorautopilot, enforce supportedPreToolUseor unverifiedStopdecisions. - Codex: MCP and Skill assets provide evidence-backed guidance at task checkpoints. The client can ignore MCP/Skill text, so this is not a deterministic block.
- Other clients: capability depends on the public interface listed in the compatibility matrix. Agent Doctor never claims enforcement where only observation or MCP advice exists.
Project control levels are observe (record only), guide (advise), guard
(enforce supported high-confidence rules), and autopilot (strongest supported
local controls). The default is guide.
| Command | Purpose |
|---|---|
agent-doctor setup --json |
Preview detected clients and exact owned changes |
agent-doctor setup --yes --json |
Apply the reviewed Codex MCP block |
agent-doctor setup --all --yes --json |
Install owned Codex MCP/Skill/AGENTS and Claude Hook/Skill assets |
agent-doctor start |
Check managed integrations, start loopback services, and open the dashboard |
agent-doctor start --no-open |
Same startup flow without opening a browser |
agent-doctor dashboard |
Alias for the visual workspace |
agent-doctor diagnose --json |
Summarize available task evidence |
agent-doctor compare --json |
Report matched-cohort readiness/results |
agent-doctor context --json |
Report bounded memory state without content |
agent-doctor costs --json |
Separate exact, estimated, and unavailable cost |
agent-doctor doctor --json |
Check database and detected clients |
agent-doctor pause --json |
Persistently pause local lifecycle capture |
agent-doctor pause --resume --json |
Resume local lifecycle capture |
agent-doctor export --json |
Export sanitized aggregates, never event payloads |
agent-doctor forget --yes --json |
Delete the local Agent Doctor database |
agent-doctor run -- <command> |
Start a client through the local capture proxy without shell evaluation |
agent-doctor uninstall --yes --json |
Remove only Agent Doctor-owned Codex config |
agent-doctor version |
Print the installed version |
Codex, Claude Code, Cline, OpenCode, Cursor, Windsurf, Roo Code, Continue, Aider, Cherry Studio, and generic command-line tools have declared capability contracts. “Supported” does not mean that a client exposes every signal. See the compatibility matrix for exact A/B/C capability levels and installation boundaries.
- exact: a charge reported by a compatible billing source;
- estimated: local token usage multiplied by a versioned public catalog;
- unavailable: the required evidence does not exist.
These values are never merged into a misleading total. Currency conversion requires a versioned rate. Read the cost methodology.
The SQLite database lives in the current user's configuration directory with user-only permissions. When live capture is enabled, complete user, assistant, system, and tool messages are stored locally so the owner can inspect the real conversation. API keys, Authorization headers, cookies, and transport headers are forwarded in memory and never written to SQLite. Replay is disabled until the user approves the exact hashed plan, base commit, commands, call limit, and cost limit. Read the privacy model.
documented client interface → sanitizer → local event contract → SQLite
↑ ↓
Hook / MCP / Skill ← deterministic guidance ← evidence fingerprints
↓
safe aggregates → loopback Task Guardian
setup --allowns only the documented Agent Doctor files/marked blocks for Codex and Claude Code, creates backups, and is safe to run repeatedly.- Descriptive comparison starts with two captured sessions. A cohort-level result still requires at least 15 matched samples and never invents a winner.
- Agent Doctor does not read private client databases or bypass client permissions.
- No public release or ranking claim is valid until the tagged GitHub workflow completes and the published checksums are independently verified.
- NexoToken AI API and tool setup guides
- Codex setup guide
- Claude Code setup guide
- Install
- Privacy
- Cost methodology
- Diagnosis methodology
- Compatibility
- Troubleshooting
- Chinese usage guide
Apache License 2.0. See LICENSE.
Real projects are more useful than synthetic demos. If a diagnosis, cost state, client boundary, or handoff is wrong, choose the matching issue form. Never attach a complete SQLite database, full transcript, credential, private source file, or authorization header. See the feedback guide.