Egoushka/chargehand

chargehand turns a request into a typed **Task Spec**, runs it on one or more coding-agent sessions
(OpenCode or Claude Code), and returns a **result contract** with evidence for every claim.
People call it from a CLI; programs call it over HTTP or MCP.
**Status: before 1.0** (the release badge shows the version). Workers are read-only by default; the code preset (since 0.8.0) makes one write a branch that passes its tests in a sandbox. See the changelog for what shipped, the roadmap for what comes
next, and benchmarks for how it performs. The guide walks through
using it, and what it does, and how we know gives each capability's status with its evidence.
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 caller inputs, plus a confidence and the exact prompt chain behind the answer.
chargehand keeps control flow (task graph, budgets, retries, parallelism) in code, not in a prompt. Each worker's
context stays small, cached and disposable.
Non-goals: its own agent loop, direct calls to model providers, parallelism for its own sake.
How a run works
1. **Intake** reads request/v1 and writes a Task Spec with one action.
2. The action decides what happens next:
- answer runs one worker session.
- split runs 2–4 read-only subtasks as a task graph; later nodes fork the first node's cached prefix.
- deny, ask and improve stop and return a reason, questions or an improved request.
- A preset can require approval above a risk or cost estimate.
3. The **evidence resolver** checks every claim. Claims that do not resolve move to open_questions.
4. You get result/v1. The run log records tokens, cache hits, cost and the prompt chain of every call.
**Presets** set tools, budgets and allowed actions: default, cheap, thorough, strict, and draft for program
callers that bring their own facts. Optional long-term **memory**, a **cache report** per run, **Prompt CI** that gates
prompt changes on paired evals, and a **routing report** round it out.
**Memory and services** come from MCP servers you list in the profile's mcp_servers; with none listed, a run is
unchanged. A run recalls from any number of memory servers at once, each fact labelled with its source, and with retain
on it stores only claims whose citations resolved, with their locators, repository and commit. A preset can give
workers read-only tools from a server. chargehand extensions check verifies the setup before a run does. See
Memory and services for the Hindsight and Chronicle setups.
Quick start
To run the server from the release images instead, with Docker Compose and no .NET SDK, see
Install with Docker Compose (deploy/compose/). To run from a clone, you need the .NET 10 SDK
and one worker runtime.
1. Copy profiles/example.json to profiles/local.json and fill in your gateway, models, prices and secret-store
item names. Profiles reference secrets by item name and never hold them.
2. Pick a runtime:
- **OpenCode**: with opencode on PATH (pinned 2.0.18), no profile block is needed. run, serve and mcp
start their own opencode serve on 127.0.0.1 and a free port, with a random password and their own state