chargehand

[chargehand]

[status: Active] [CI] [last commit]

chargehand

Ask a question about your code from Claude Code or any MCP client and get back claims that each cite a file at a pinned commit, checked before you see them.

Active. I work on it this month.

flowchart LR  caller[You or a program<br/>CLI · HTTP · MCP] -- request --> intake[Intake<br/>picks an action]  intake -- answer or split --> workers[Agent sessions<br/>Claude Code or OpenCode]  intake -- ask · deny · improve --> result  workers -- claims + citations --> resolver[Evidence resolver<br/>checks each citation]  resolver --> result[Typed result<br/>claims · open questions · cost]  workers -. code preset, driven batches .-> branch[Tested branch<br/>or draft pull request]  resolver --> log[(Run log<br/>tokens · cache · prompts)]

Why

Coding agents answer in prose. A program that calls one needs something it can check: claims tied to files at a commit, diffs, session messages or the caller's own inputs, plus a confidence and the exact prompts behind the answer. I also wanted the control flow (the task graph, budgets, retries, parallelism) in code rather than in a prompt, so each agent's context stays small, cached and disposable.

What it does

Answers with checked citations. You ask a question about a repository; chargehand runs a read-only agent session (Claude Code or OpenCode) on a clone at a pinned commit and returns typed JSON (result/v1): claims, open questions, a confidence, the cost and the prompts behind it. A citation is a file and line range, a commit, a diff range, a session message or an input id. Each one must exist at the pinned commit before a claim leaves its worker; the worker gets one repair turn, and claims that still fail move to open questions.

You reach it as an MCP server (stdio or HTTP), an HTTP API or a CLI. Presets (default, cheap, thorough, strict, draft, review) set the tools, the token and dollar budgets and whether a question may be split into 2 to 4 read-only subtasks.

Also in the box, each with its own guide:

• A code preset and driven batches that write a tested branch or a draft pull request in a sandbox (Writing a branch, Driven sessions).
• /chargehand:change, a Claude Code plugin command: one prompt to a reviewed change on a local branch (the change command).
• An operator console in the browser (Web UI).
• Prompt CI, which gates prompt and preset changes on paired evals; the run log records tokens, cache hits, cost and the prompt chain of every call (Prompt CI).

Not here: an agent loop of its own, direct calls to model providers, a model gateway, a memory store (it uses yours over MCP), a hosted service. A citation that resolves points at something that exists; checking that the cited text supports the claim is planned, not built (roadmap).

[!WARNING] Before 1.0. The images have no latest tag: pin an exact version and read the changelog before you upgrade.

Quick start

Ask Claude Code a question about your own repository, with no clone of chargehand.

You need:

• the .NET 10 SDK (dotnet --version prints 10.x), which provides dnx;
• Claude Code 2.1.283 on PATH (claude --version), signed in (run claude once);
• a token for the workers: claude setup-token prints one for your subscription (an ANTHROPIC_API_KEY works too and bills per token).

claude mcp add chargehand -e CLAUDE_CODE_OAUTH_TOKEN=<token> -- dnx [email protected] --yes -- mcp

Replace 0.19.4 with the newest version of the Chargehand package on nuget.org and pin it: the package changes before 1.0. In a Claude Code session in the repository you want to ask about, say: use chargehand to find where retries are decided, and cite the code. The answer lists claims, each with its file and lines. Other editors and agents (Cursor, VS Code, Codex, Gemini CLI and more) are in Connect your editor or agent.

From a clone, to ask one question about chargehand itself without MCP: it needs the .NET 10 SDK, git and the same Claude Code, signed in. With no profile, the workers use the CLI's own login and default model.

git clone https://github.com/Egoushka/chargehand.git && cd chargehandcat > request.json <<EOF{  "contract_version": "request/v1",  "text": "Where does a split node decide whether to fork the first node's session? Cite the code.",  "context": { "interactive": false, "preset": "default",               "repository": { "path": "$PWD", "commit": "$(git rev-parse HEAD)" } }}EOFdotnet run --project src/Chargehand.Cli -- run < request.json

It prints result/v1 on stdout: claims with citations, open questions, a confidence and the cost. The quickstart guide explains every field, OpenCode instead of Claude Code, and what to do when a run fails.

How it works

1. Intake reads the request (request/v1) and writes a Task Spec: one action, answer, split, ask, deny or improve. The last three stop the run with questions, a reason or a better request. A preset can also stop a run for approval above a risk or cost estimate.
2. Workers are ordinary Claude Code or OpenCode sessions on a clone of the repository at the pinned commit, inside the directories the profile allows. chargehand never calls a model provider itself.
3. The evidence resolver checks every citation against git, the session and the request. The invariant: no claim reaches the result unless its citations resolved.
4. The result (result/v1) carries the claims, the open questions, usage and the prompt chain. The same record goes to the run log, which show, cache and routes read.

Writing runs follow the same path with a sandboxed worker: the code preset verifies a branch with the repository's tests, and driven batches add an egress allowlist, a runner that alone holds the Docker socket, and a check gate before a pull request opens. ARCHITECTURE.md maps the code.

Numbers

Lessons

• Parallelism did not pay on the questions I measured. Splits resolved every citation but cost half again as much for a small score gain, so the shipped default, review and draft presets allow no split (ADR 0017).
• A score that measures what run-time checks already enforce catches nothing. The first Prompt CI score measured grounding, which the resolver already forces, so a prompt that dropped a third of the claims passed. The score now multiplies grounding by completeness (ADR 0019).

Docs

• Overview: what it is, how a run works, what it leaves out, status
• What it does, and how we know: each capability with its status and evidence
• Quickstart · Install with Docker Compose: from a clone, or from the release images
• Use it from an MCP client · Run the HTTP server · Web UI
• Writing a branch · Driven writing sessions · Several runners
• The change command: the Claude Code plugin
• Memory and services · Prompt CI · Benchmark
• Reference: commands, routes, presets, contracts, profile fields, environment variables
• Architecture · Decisions · Changelog · Roadmap
• Contributing · Security · License (FSL-1.1-ALv2)

License

Versions after v0.19.19 are under the Functional Source License, Version 1.1, ALv2 Future License (FSL-1.1-ALv2): you may use, copy, modify and redistribute the code for any purpose other than a competing use, and each version converts to Apache-2.0 two years after its release.

Releases up to and including v0.19.19 were published under Apache-2.0 and remain Apache-2.0 (LICENSE-APACHE-2.0). See NOTICE.