Docs

Use Unfix inside your AI agent

Install Unfix so unfix is on PATH. Before starting an agent, reproduce the bug yourself in an interactive terminal with unfix bug (at least three runs for a deterministic or memory bug). The MCP server reads that stored BugSpec; the agent cannot create or replace it through MCP. Unfix remembers the CLI data directory for MCP clients that omit environment variables. An explicit MCP environment value takes precedence and is safer when you use a custom data directory.

Connect Claude Code

Run this in the project (replace the allowed parent directory):

claude mcp add --transport stdio unfix -- unfix mcp --allow-root /home/me/projects
claude mcp list

On Windows PowerShell, the corresponding command is:

claude mcp add --transport stdio unfix -- unfix mcp --allow-root C:\work
claude mcp list

For a custom data directory, run claude mcp add -e UNFIX_DATA_DIR=D:\unfix-data --transport stdio unfix -- unfix mcp --allow-root D:\unfix-test on Windows. Keep --transport stdio between -e and the server name because -e accepts multiple values. The server name is unfix; tool names have no unfix_ prefix. See Claude Code MCP connections.

Connect Codex CLI

Run this in PowerShell, replacing the allowed project directory:

codex mcp add unfix -- unfix mcp --allow-root D:\unfix-test
codex mcp list

For a custom data directory, use codex mcp add unfix --env UNFIX_DATA_DIR=D:\unfix-data -- unfix mcp --allow-root D:\unfix-test. The environment value is stored in Codex MCP configuration. You can instead add to ~/.codex/config.toml on Linux or %USERPROFILE%\.codex\config.toml on Windows (replace the parent directory):

[mcp_servers.unfix]
command = "unfix"
args = ["mcp", "--allow-root", "/home/me/projects"]

On Windows, use args = ["mcp", "--allow-root", "D:\\unfix-test"]. See Codex MCP configuration.

Run the agent without shell escalation

For Codex CLI 0.165 on Windows, keep shell commands in the workspace sandbox and deny escalation:

codex exec -C D:\unfix-test --sandbox workspace-write -c 'approval_policy="never"' -c 'sandbox_workspace_write.network_access=false' -c 'mcp_servers.unfix.default_tools_approval_mode="approve"' "Fix the bug. Use the unfix tools to verify your fix before you finish. Do not run unfix bug or unfix verify in a shell."

Do not use --approve-for-me or --dangerously-bypass-approvals-and-sandbox. The approval_policy, sandbox_workspace_write.network_access, and MCP tool approval keys are in the Codex configuration reference. The MCP approval setting applies to the trusted Unfix server only; shell commands still cannot leave the workspace sandbox.

For Claude Code, run in Linux or WSL2. Save unfix-agent-settings.json outside the agent's writable project:

{"sandbox":{"enabled":true,"failIfUnavailable":true,"allowUnsandboxedCommands":false,"autoAllowBashIfSandboxed":true,"network":{"allowedDomains":[]}}}

Then run:

Requires Claude Code v2.1.259 or later (for --permission-prompts); see the CLI reference.

claude -p --settings /path/to/unfix-agent-settings.json --permission-mode acceptEdits --permission-prompts none --allowedTools 'mcp__unfix__list_bugs,mcp__unfix__start_verify_current,mcp__unfix__verification_status,mcp__unfix__verification_result' 'Fix the bug. Use the unfix tools to verify your fix before you finish.'

--allowedTools approves only these trusted MCP calls without prompting; sandboxed Bash is auto-allowed by the sandbox setting. Native Windows cannot enforce Claude's shell sandbox, and failIfUnavailable makes this configuration stop there. See Claude sandboxing and CLI flags.

How the agent verifies itself

Ask the agent to fix the bug and use Unfix before finishing. It calls list_bugs(project) to choose a stored bug_id, start_verify_current(project, bug_id) to snapshot uncommitted changes, then polls verification_status(job_id) or verification_result(job_id). The result contains the verdict, gate statuses, reason, verification ID and HTML report path. VERIFIED means the checks proved this fix; stop editing. REJECTED means address the stated reason while preserving tests. NOT_VERIFIABLE means the required reproduction or evidence is missing. REVIEW needs a human decision.

The start call returns before the checks finish, so a build or repeated run lasting many minutes does not depend on the MCP client's tool-call timeout. Poll for progress. If the MCP server process exits, an in-memory job cannot be resumed; completed verification records remain in Unfix's data directory.

The agent cannot change Unfix settings, delete BugSpecs, disable gates, choose a lighter mode, or apply a patch to your branch via MCP. Project configuration comes from the committed baseline; an edited unfix.yaml or legacy cplus.yaml is rejected. Existing tests are protected by the verifier. Unfix alone computes the verdict. The agent can still edit ordinary project source files, so review its diff before merging.

MCP tool restrictions do not restrict an agent's separate shell access. Keep UNFIX_DATA_DIR outside the agent's writable workspace and use host file permissions or an OS sandbox when the agent is untrusted. The HTML path is local to the machine running the MCP server.

BugSpec's interactive/noninteractive creation mark is a disclosure hint, not a security boundary: terminal detection can be spoofed. The boundary is the agent's OS sandbox and its lack of write permission to the Unfix data directory. Do not give an untrusted agent unrestricted shell access to that directory.

Host projects and boards

The MCP workflow currently verifies host projects. Board /bug does not yet create a stored BugSpec, so list_bugs has no board bug to select. An explicit verify_patch call for a physical-board target returns NOT_VERIFIABLE and directs you to unfix verify, which performs the on-target checks. MCP never reports a host-only result as proof of a firmware fix.