A terminal coding agent that runs itself: it reads, patches, searches and runs commands, then shows you what it did. It runs in a container, keeps its own state out of your repository, and talks to any OpenAI-compatible provider or to Ollama.
- Tools with an intent. Every call carries a short phrase saying why, shown next to the result and kept in the context.
- A sandbox, not a shell.
run_bashaccepts one allow-listed command and no shell metacharacters; file tools refuse to leave the project root. - Verified writes.
patch_fileapplies a unified diff and reads the file back byte-for-byte before reporting success. - A context budget it manages. Usage is estimated per call, compaction is announced before it runs, and the tail of the conversation stays verbatim.
- Three intent modes.
chatreads only,designalso writes the tracking files,workis unrestricted.Tabwalks the ring. - Nothing leaves the machine but the model calls. No telemetry, no analytics.
curl -fsSL https://raw.githubusercontent.com/moncho-cli/moncho-cli/main/scripts/install.sh | bashThe installer stages the payload under ~/.config/moncho-cli and links moncho-cli
onto your PATH. It needs curl, tar and a working Docker daemon — and no Node.js
on the host, because the agent runs in a container. Pin a release with
MONCHO_REF=v0.1.1; install elsewhere with MONCHO_HOME=/opt/moncho.
Then, in any project directory:
moncho-cliThe first run prepares the directory: it adopts an existing Dockerfile when there is
one, otherwise it asks for the project kind and writes a Monchofile from a starter.
It bakes the agent base image once, builds the project image, and starts the agent with
your workspace mounted at /app. State — sessions, task.md, the plan, the log —
lives in a named volume, so nothing is written into your repository.
- The first
FROMismoncho-agent; the agent's runtime sits under your app's. - No
ENTRYPOINT: the runner appends the agent's own, so your server does not start instead of the agent.
Everything else is an ordinary Dockerfile. See templates/README.md for the contract and demos/README.md for a run-through.
| Document | What it covers |
|---|---|
| USAGE.md | Install and run on Linux and macOS, configuration, commands, sessions, modes |
| REQUIREMENTS.md | What the host, the container and the provider must provide |
| CONTRIBUTING.md | Forks, pull requests, the maintainer loop, the realm rule |
| PRIVACY.md | What is sent, what is stored, and where |
| LIABILITY.md | The warranty and responsibility position |
| docs/README.md | The behavioural contract: one spec per capability |
| tests/README.md | The proof: one suite per capability |
The numbers below are the provider's own accounting for a real session, read from the OpenRouter dashboard. The cache-hit rate is the reason a long session stays affordable: the request prefix never changes between calls, so the prompt cache is hit on every turn after the first.
The same accounting appears in the transcript, with the summary chunk in place of the block it replaced — the conversation above it is gone, its essence is not.
| Realm | Where | Role |
|---|---|---|
| Code | app/, api/, config/, tools/, utils/, main.js |
The truth: what the agent does |
| Docs | docs/<domain>/<capability>/ |
The contract: behaviour.md plus spec.yaml |
| Tests | tests/ |
The proof: one suite per capability |
A behaviour is finished when a spec describes it and a test proves it. npm test
enforces the links: a spec directory without its pair, a path#symbol that names
nothing, or a source module no spec covers all fail the suite.
main.js the host loop: front end, sessions, commands, tracking
app/ conversation manager, tool batches, context window, TUI
api/ the provider call: retries, normalisation, the system prompt
config/ constants and config/prompt.md
utils/ sandbox, patch, sessions, logger, compaction, usage
bin/ the container runner (moncho-cli) and its libraries
scripts/ the installer
docs/ tests/ the contract and the proof
agent/ is gitignored and holds the session state, tracking files and the log. It is
disposable: delete it and the next run starts clean.
The maintainer loop runs this checkout in its own container, through ./start.sh. See
CONTRIBUTING.md for the full instructions; the short version is
./start.sh run (or make dev) to run it, and ./start.sh exec npm test for the
suite — inside that container.
MIT. See LICENSE. The warranty position is in LIABILITY.md.




