Balanov/uncut

What it is

UNCUT is a headless coding agent harness for shell pipelines, CI jobs, containers, and agent experiments. It has a single statically linked Go binary, no TUI, and no telemetry. The design is deliberately minimal: four tools, one OpenAI-compatible Chat Completions protocol, one agent loop, and roughly 837 lines of Go implementation under the MIT license UNCUT repository.

The central contract is "lossless": the entire conversation is sent on every model call, and file contents plus combined command output are never truncated by the harness. If the provider cuts a response at its output limit or context window, UNCUT exits with an error rather than presenting a partial answer as success. It does not summarize, prune, or use sliding windows, and it does not extend a model's context window Lossless contract.

This suits developers who want an agent they can script and pipe into, and who prefer explicit failure over hidden context trimming. It is also small enough to fork and adapt.

Quick start

Install a prebuilt binary or build from source. For a source build with Go 1.26+:

git clone https://github.com/Balanov/uncut.git
cd uncut
go build -trimpath -ldflags="-s -w" -o bin/uncut ./cmd/uncut

On Windows, use bin/uncut.exe as the output path Source builds. Release binaries for Linux, macOS, and Windows (amd64 and arm64) are also available from the latest release; every release includes a checksums.txt for SHA-256 verification checksums.

Set a model and API key, then give the agent a task:

export UNCUT_API_KEY="your-api-key"
export UNCUT_MODEL="your-model-id"
uncut "Inspect this repository and fix the failing tests"

For an OpenAI-compatible provider, also set UNCUT_BASE_URL. For a local Ollama server with a tool-capable model, the documented setup is:

ollama pull qwen3:8b
export UNCUT_BASE_URL="http://localhost:11434/v1"
export UNCUT_MODEL="qwen3:8b"
uncut "Explain this repository"

No API key is required by default for local endpoints. Replace the example model with one actually installed, since tool-call behavior depends on the model Quick start.

The final answer goes to stdout. Add --json for NDJSON events, or --session <file> to create or resume an append-only JSONL session JSONL events, sessions. Piped input is appended to the prompt verbatim, so git diff | uncut "Review this diff. Do not edit files." works as expected pipelines.

Configuration and tools

UNCUT_MODEL is required unless --model is passed. UNCUT_BASE_URL falls back to OPENAI_BASE_URL, then https://api.openai.com/v1; UNCUT_API_KEY falls back to OPENAI_API_KEY, then no token. Useful flags include --cwd, --session, --max-steps (default 32), --max-tokens, --request-timeout (default 10m), --no-agents, and --json Configuration. A workspace AGENTS.md is read in full and added to the system prompt unless --no-agents is set.

The agent has four tools: read_file, write_file, replace (exactly one occurrence must match), and run_command, which returns the exit code and complete combined stdout/stderr. File paths must stay inside the workspace, but shell commands are not constrained by those checks Tools.

Exit codes are meaningful in CI: 0 success, 1 provider/I/O/session/execution error, 2 invalid usage, 3 the provider returned finish_reason=length, and 4 the step limit was reached Exit codes.

Constraints

UNCUT is not a sandbox. The model executes shell commands with your operating-system user's permissions, and workspace checks on file tools do not limit what a shell command can access. Run untrusted tasks in a disposable container or isolated environment Safety. There are no approval popups, automatic commits, automatic retries, or hidden recovery loops.

Input must be valid UTF-8 text. Binary files and invalid UTF-8 are rejected explicitly rather than silently converted, and UNCUT uses non-streaming Chat Completions with text and tool calls, not images Lossless contract. On Windows, commands that emit UTF-16 or code-page output are rejected; configure them to emit UTF-8 where possible Tools.

Session files can contain source code, command output, and secrets, so store them accordingly and avoid committing them sessions. The provider may still reject inputs that exceed its context window, and UNCUT has no control over provider-side processing. Release binaries are not yet code-signed, so SmartScreen or Gatekeeper may warn checksums and warnings.

Verify the contract

The repository includes a proof script that drives the real binary against a deterministic local provider, requiring Python 3 but no API key or model:

go build -o bin/uncut ./cmd/uncut
python bench/proof.py ./bin/uncut

It checks large-file and command-output transport, exact session resume, edits, explicit truncation failures, step limits, and invalid UTF-8 handling proof script. The author notes these are transport tests, not model-quality benchmarks; see the recorded measurements and reproduction commands. Build and contribution commands are gofmt -w cmd internal, go test -count=1 ./..., and go vet ./... Development.

HotRepo's take

The project's strongest design choice is the explicit failure mode: exit code 3 on provider truncation and a rejection of partial answers. Combined with the four-tool surface and sub-megabyte static binary, it is positioned for CI and pipelines where silent context loss would corrupt the result. The bundled proof script against a deterministic local provider is a practical way to check the transport claims without an API key.

The main trade-off is that "lossless" does not mean the model can handle unbounded input. UNCUT sends everything and surfaces provider rejection, so very large repositories or logs will fail at the provider rather than being summarized. Users who expect automatic context management, approval prompts, or retries should look elsewhere. HotRepo has recorded the repository on its new-project list with 109 stars in the observed window starting 2026-11-01, but has no GitHub daily rank or Hacker News discussion for this project, so there is not enough history to comment on adoption trends.