uncut README

README проекта с github.com/Balanov/uncut. Одним файлом markdown: README.md.

UNCUT — the lossless, headless coding agent harness. One static binary, four tools, zero silent context cuts.

Full context in. Complete results out. Explicit failure when the provider cuts.

Linux · macOS · Windows · amd64 + arm64 · MIT

Install · Quick start · Lossless proof · Measurements · Website · Русский

CI Latest release MIT license Go 1.26+

UNCUT lossless proof: six recorded checks pass, including complete byte transport and explicit rejection of provider truncation

Six recorded scenarios against a deterministic local provider. Raw results · Run it yourself. Transport checks, not a model-quality benchmark.

UNCUT is a tiny coding-agent harness for shell pipelines, CI jobs, containers, and agent experiments. It deliberately has no TUI, telemetry, plugin system, background agents, automatic retries, or context compaction.

The entire conversation is sent on every model call. File contents and combined command output are never truncated by UNCUT. If the provider cuts a response at its output limit, UNCUT exits with an error instead of presenting a partial answer as success. Run the proof yourself or inspect the recorded measurements.

Why UNCUT?

The UNCUT agent loop and recorded proof: 442,400 bytes of file and prompt unchanged, 213,018 bytes of combined output unchanged, and exit 3 with zero partial stdout on provider truncation

The lossless contract, with links to reproducible evidence in BENCHMARKS.md.

Install

Linux

VERSION=0.1.1
ARCH=amd64  # Use arm64 on ARM64.
curl -fSLo uncut "https://github.com/Balanov/uncut/releases/download/v${VERSION}/uncut-linux-${ARCH}"
mkdir -p "$HOME/.local/bin"
install -m 0755 uncut "$HOME/.local/bin/uncut"
export PATH="$HOME/.local/bin:$PATH"
uncut --version

Make sure $HOME/.local/bin is on your PATH.

macOS

VERSION=0.1.1
ARCH=arm64  # Use amd64 on Intel.
curl -fSLo uncut "https://github.com/Balanov/uncut/releases/download/v${VERSION}/uncut-darwin-${ARCH}"
mkdir -p "$HOME/.local/bin"
install -m 0755 uncut "$HOME/.local/bin/uncut"
export PATH="$HOME/.local/bin:$PATH"
uncut --version

Windows PowerShell

$Version = "0.1.1"
$Arch = "amd64"  # Use arm64 on ARM64.
$Dest = "$env:LOCALAPPDATA\Programs\UNCUT"
New-Item -ItemType Directory -Force $Dest | Out-Null
Invoke-WebRequest -Uri "https://github.com/Balanov/uncut/releases/download/v$Version/uncut-windows-$Arch.exe" -OutFile "$Dest\uncut.exe"
$env:Path = "$Dest;$env:Path"
uncut --version

Add $Dest to your user PATH to make UNCUT available in future terminals.

Checksums and OS warnings

Every release includes checksums.txt. For example, verify a Linux download with:

VERSION=0.1.1
ARCH=amd64
curl -fSLO "https://github.com/Balanov/uncut/releases/download/v${VERSION}/checksums.txt"
grep "uncut-linux-${ARCH}$" checksums.txt | sha256sum -c -

The binaries are not code-signed yet, so SmartScreen or Gatekeeper may warn. Verify the SHA-256 checksum before allowing a downloaded executable. On macOS, after verification, remove quarantine from this file only:

xattr -d com.apple.quarantine "$HOME/.local/bin/uncut"

You can also build from source instead.

Go install and source builds

With Go 1.26+:

go install github.com/Balanov/uncut/cmd/uncut@latest

Or build a checkout:

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.

Quick start

Set a model and API key:

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 its base URL:

export UNCUT_BASE_URL="https://openrouter.ai/api/v1"

For a local Ollama server with an installed tool-capable model (this exact setup was smoke-tested with qwen3:8b):

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. In PowerShell, set variables with $env:UNCUT_BASE_URL = "..." and $env:UNCUT_MODEL = "...". Replace the example model with one actually installed on your machine; tool-call behavior depends on the model.

Unix pipelines

git diff | uncut "Review this diff. Do not edit files."
cat failing-test.log | uncut "Find the likely cause"

Piped input is appended to the prompt verbatim. UNCUT accepts valid UTF-8 text and rejects invalid input rather than replacing bytes silently.

JSONL events

uncut --json "Run the tests and fix the failure"

The event stream contains user, assistant, assistant_meta, tool, and finally done or error records. Assistant messages include complete tool calls; tool messages include complete results. Usage and finish reasons are separate assistant_meta events.

Sessions

uncut --session .uncut/work.jsonl "Start the refactor"
uncut --session .uncut/work.jsonl "Continue with the tests"

If the file exists, UNCUT resumes its complete history. New messages are appended and synced after each step. A model step that UNCUT rejects — provider truncation, a tool call without an id or name, or an empty message — is not written to the session, so a failed run never leaves a session that the next run cannot resume. Invalid or partial records cause an explicit error; they are never discarded to make a session load.

Session files can contain source code, command output, and secrets. Store them accordingly and do not commit them accidentally.

Configuration

Environment variable Purpose Default
UNCUT_MODEL Model ID; required unless --model is used none
UNCUT_BASE_URL OpenAI-compatible base URL OPENAI_BASE_URL, then https://api.openai.com/v1
UNCUT_API_KEY Bearer token OPENAI_API_KEY, then no token

Useful flags:

Flag Default Meaning
--cwd <dir> current directory Workspace for file tools and shell commands
--session <file> disabled Create or resume an append-only JSONL session
--max-steps <n> 32 Maximum model calls before exit code 4
--max-tokens <n> provider default Explicit provider output limit
--request-timeout <duration> 10m Per-request timeout; 0 disables it
--no-agents false Do not read workspace AGENTS.md
--json false Emit NDJSON events instead of only final text
--version — Print version and exit

AGENTS.md is read in full from the workspace root and added to the system prompt. On a resumed session, the original stored system message is reused.

Tools

Tool Behavior
read_file Reads an entire UTF-8 text file
write_file Writes complete file contents and creates parent directories
replace Replaces exactly one occurrence; zero or multiple matches fail
run_command Returns the exit code and complete combined stdout/stderr

File paths must stay inside the workspace. run_command uses /bin/sh -c on Unix and cmd.exe /D /S /C on Windows.

Some Windows utilities can emit UTF-16 or code-page output rather than UTF-8. UNCUT rejects that output instead of guessing a conversion; configure commands to emit UTF-8 when possible.

Exit codes

Code Meaning
0 Successful final answer
1 Provider, I/O, session, or execution error
2 Invalid command-line usage
3 Provider returned finish_reason=length or max_tokens; partial answer rejected
4 --max-steps reached before a final answer

What “lossless” means

UNCUT does not truncate, summarize, or rewrite valid UTF-8 prompts, stored messages, file contents, or command output. It does not extend a model's context window, and it cannot control provider-side processing. When the context or output limit is exceeded, the provider may reject or cut the response; UNCUT surfaces that failure instead of hiding it.

Binary files and invalid UTF-8 are rejected explicitly. UNCUT uses non-streaming Chat Completions and supports text plus tool calls, not images.

Safety

UNCUT is not a sandbox. The model can execute shell commands with your operating-system user's permissions. Workspace checks on file tools do not constrain what a shell command can access. Run untrusted tasks in a disposable container or isolated environment, and review sessions and changes yourself.

There are no approval popups, automatic commits, automatic retries, or hidden recovery loops.

Verify the lossless contract

The proof script drives the real binary against a deterministic local provider. It needs Python 3, but no API key, model, or third-party package:

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

It checks complete large-file and command-output transport, exact session resume, edits, explicit truncation failures, step limits, and invalid UTF-8 handling. See the recorded results and reproduction commands. These are transport tests, not model-quality benchmarks.

Develop

gofmt -w cmd internal
go test -count=1 ./...
go vet ./...

The test suite includes complete large-file and large-command-output round trips, session resume, provider truncation, JSON output, and platform-specific shell behavior. See CONTRIBUTING.md for the project contract and PR checklist.

cmd/uncut/          CLI and process exit codes
internal/harness/   agent loop, provider, tools, sessions, platform shells
bench/              lossless proof and benchmark drivers
assets/             logo and editable brand source
docs/               launch material

License

MIT. Fork it, modify it, ship it. See LICENSE.

uncut (Balanov/uncut)

Ищем в базе…

270 ·GitHub
Что это такое?UNCUT — небольшая обвязка (harness) для агента-кодера в терминале, созданная для конвейеров shell, CI-задач и контейнеров. У неё нет TUI, она отправляет всю переписку при каждом вызове модели и никогда не обрезает содержимое файлов или вывод команд.
Это фреймворк или библиотека?Ни то, ни другое. Это самостоятельный CLI-бинарник, который вы запускаете из командной строки, а не код, который подключается к вашему проекту.
Как его запустить?Скачайте бинарный файл релиза для вашей ОС, проверьте его по checksums.txt и поместите в PATH. Затем задайте ID модели и API-ключ (или базовый URL для локального сервера) через переменные окружения или флаги.
Что хранится в файле сессии?Необязательные сессии — это файлы JSONL, которые только дописываются и сохраняют каждое сообщение и результат инструмента. Так как они содержат полную историю, в них может оказаться исходный код, вывод команд и секреты.
Что на практике означает «без потерь» (lossless)?UNCUT не обрезает, не сокращает и не переписывает корректные UTF-8 промпты, сохранённые сообщения, содержимое файлов и вывод команд. Ограничения контекста и выходных данных на стороне провайдера по-прежнему действуют, и UNCUT сообщает об этих ошибках, а не скрывает их.
Можно ли использовать его в скриптах или конвейерах?Да. Входные данные из пайпа добавляются к промпту дословно, итоговый текст выводится в stdout, а флаг --json выдаёт структурированные события в формате NDJSON.
Какие коды выхода должен ожидать CI-скрипт?0 означает успешный итоговый ответ, 1 — ошибку провайдера, ввода-вывода, сессии или выполнения, а 2 — неверное использование. Код 3 означает, что вывод обрезан по лимиту, а код 4 — что --max-steps закончились до получения итогового ответа.
Какой размер у кодовой базы?В README указано, что это около 837 строк реализации на Go, четыре инструмента, один протокол провайдера и один цикл агента.
Какие есть похожие проекты?Baize, shim, claw-code, ordewell, memdoor, qwen-code, Codewhale, OpenHarness
Автор
Balanov
Размер
1.1 MB
Звёзды
270
Возраст
17 д
Коммиты · 90 дней