BoundedCode

Problem

Coding agents working on large codebases fail in two predictable ways. They overflow context: pouring the repository into the prompt exceeds what a local model can hold and drives up the cost of frontier models. And they mistake green tests for done: an agent reports success because the suite passes, even when no test touches the code it changed.

BoundedCode is a Go control plane around existing tools — llama.cpp for local inference, the OpenHands agent SDK, a code-graph index and language servers — that is built around the opposite defaults.

Context

It is meant for one engineer running long tasks against real repositories on their own machine, with a local model by default and a cloud model only when they choose one. It is a public alpha: validated on a small held-out sample of real tasks, on one machine, with one model.

Constraints

• One laptop: an 8 GB consumer GPU and 64 GB of RAM. The local model has to be useful within that.
• The agent's code is untrusted. It may follow prompt-injected instructions found in the repository.
• Tasks run for a long time and must survive Ctrl-C, crashes and reboots without losing work.
• Nothing is pushed or merged on the user's behalf.

Architecture

Each attempt starts from a small, task-specific context pack. The agent runs in a container with no network and has only terminal, file-edit and task-tracker tools; its model calls travel back over stdio to a gateway in the control plane. Work lands as commits on a task branch in its own git worktree. Verification runs targeted, then full, inside the sandbox, followed by the behavioural-evidence check. A SQLite ledger records every attempt so a task can resume anywhere.

Hard problems

Telling "verified" apart from "green". The obvious gate — run the tests — accepts a change that no test exercises. The gate instead re-runs the change's new or modified tests against the base commit: only a test that fails there and passes with the change counts. Tests that also pass on the base, or that do not even build on the base, are not credited.

Surviving a SIGKILL mid-turn. A killed runner leaves an active lease, a half-finished attempt and uncommitted edits. A second runner must not race the first, must take over once the lease is stale, and must resume from authoritative state rather than from the dead process's memory.

Containing an agent that has been turned against you. Text in the repository can instruct the agent to weaken verification or exfiltrate secrets. Configuration is therefore read from the base commit, protected paths are enforced, and context reads are confined so a planted symlink cannot pull a host secret into the model's context.

Decisions

• ADR-0002 — embedded SQLite for control-plane state: one file, transactional, no service to run.
• ADR-0003 — the agent runs in a container sandbox, not on the host.
• ADR-0009 — frontier escalation is an optional, policy-triggered exception.

Rejected alternatives

Failure model

Security model

The agent and everything it runs are untrusted. The container gets no network, drops all capabilities, runs as a non-root user with no-new-privileges, and never mounts the home directory, ~/.ssh or the Docker socket. Secret paths are masked. Diffs are secret-scanned on the host. Escalation packets have API keys and host paths removed.

Observability

Every task writes an audit log to the ledger: attempts, strategies, verification stages, escalations and recoveries (task.recovered events after a crash). The validation reports are built from those records.

Tests and verification

CI on every push to main runs gofmt, go vet, go test ./... and go test -race ./..., govulncheck, golangci-lint, license checks, cross-builds for six platforms and a gitleaks scan of the full history. The claims on this page cite the specific test functions that assert them. At the pinned release, all CI jobs succeeded.

Tests that need a real container engine are skipped in CI. The live sandbox escape probes, for example, run only locally. That limit is stated on the claims it affects.

Benchmarks

BoundedCode's validation results are published as reports with machine-readable run records in the repository. They are task-outcome evaluations, not latency or throughput benchmarks, so they are linked as documents rather than shown on /benchmarks. As the README states: on six held-out tasks not used during development, five ended task-verified and passed the datasets' hidden acceptance tests, all five using only the local model. That is a small sample, not a statistical evaluation. Earlier rounds scored 0 of 8 and then 1 of 8 on differently screened tasks, and in development runs the gate classified five changes as task-verified that then failed hidden tests; the reports explain each case. Fail-before/pass-after is evidence, not proof of correctness.

Incidents

No incident replays are published for this project.

AI assistance and human verification

From the project's README: "I designed the architecture, the threat model, the verification model and the evaluation protocol, and made the release and scope decisions. Implementation, test runs and first drafts of the reports were produced with heavy use of AI coding agents, under that design and review." The validation reports are published unedited, including results that did not support a release.

Reproduce

git clone https://github.com/akynte/boundedcode.git && cd boundedcode
git checkout v0.1.0-alpha.3
go test ./...          # what CI runs, minus Docker-gated tests
go test -race ./...

The repository README documents the full set-up for running tasks with a local model (Linux, Docker, an NVIDIA GPU for local inference, or a cloud model API instead).

Limitations

• Validated on six held-out tasks, with one model, on one machine. It shows no proven advantage over the same model run without BoundedCode.
• macOS and Windows are experimental, and some test packages fail there.
• Frontier escalation is implemented and tested against a fake, but it has not been shown to improve outcomes.

At 10x scale

The single SQLite ledger and per-machine sandbox are deliberate for a single-user tool. Running many engineers' tasks would first need a shared task store with real leases, such as Postgres with row locks, and a scheduler for GPU time. The control plane's state boundaries were drawn so those parts could change without changing the verification gate.

Source and evidence

Repository akynte/boundedcode at release v0.1.0-alpha.3. Every claim above links to files at commit be1aa9f. See the evidence matrix at /proof.