kloop

A terminal coding agent written in Rust from scratch. Give it a sentence and it reads the code, edits files, runs commands and looks things up until the job is done.

Status: in daily use by its author, not a release. Configuration and interfaces still change, and nothing here is a compatibility promise.

What it does

• Talks to any gateway — a complete implementation of each of the three wire protocols (messages / responses / chat); a provider is one profile in one file. Model, effort and context window are stated in that config; nothing is discovered at runtime.
• A full set of tools — read/write/edit files, bash (interruptible in the foreground, pollable in the background), grep/glob, notebooks, web fetch and search. On Windows that is native PowerShell, not an emulated bash.
• Asks before it acts — every tool call goes through a permission decision: reads pass, destructive things ask you, and an approval can be remembered. On macOS a seatbelt sandbox sits underneath: writes land only inside an allow-list, and the network can be shut off entirely.
• Sessions you can go back into — everything is persisted. -c continues the last one, -r picks one from a list, and --fork <id>#<line> branches from a step in the middle and runs it differently.
• Not one model doing the work — sub-agents (dispatched synchronously or run in the background), an MCP client (stdio / HTTP / OAuth login), skills, and code mode, where the model writes a little JavaScript to orchestrate tools so that a hundred-item loop comes back as one result.
• More than a TUI — --headless runs a single turn for scripts (optionally emitting an NDJSON event stream), --plain is a line-based REPL, and app-server turns it into an agent service speaking over stdio.

Install

Rust 1.98+. macOS is the primary platform (the sandbox has a macOS backend only); Linux and Windows build and run, but only macOS is exercised routinely — there is no CI, so make check on the developer's machine is the whole gate.

make install          # release build, installed into ~/.local/bin (override PREFIX=)

The first install also copies config/config-demo.toml to ~/.kloop/config.toml (directory 0700, file 0600) and you have to edit it before the first run — every key in the demo says REPLACE-ME, and kloop has no fallback. If a config is already there, it is not touched: only the binary is replaced.

Use it

kloop                          # start the TUI; the current directory is the workspace
kloop --mock                   # keyless scripted demo — one run shows you the shape
kloop -c                       # continue the previous session
kloop --headless "fix the flaky test in CI"
kloop --worktree=fix-ci        # work inside an isolated git worktree
kloop --help                   # every flag

Configuration

One file: ~/.kloop/config.toml. No environment variable decides which gateway a run talks to, so the answer cannot change with the shell that started it.

provider = "my-gateway"

[providers.my-gateway]
wire_api    = "messages"                                # messages | responses | chat
base_url    = "https://gateway.example.com"
auth_header = { Authorization = "Bearer ..." }          # or { x-api-key = "..." }
model       = "claude-opus-4-8"
effort      = "high"

Permissions, sandbox, MCP, hooks, skills, sub-agents and code mode are configured in that same file; the full field reference is config/config-demo.toml.

What is in the repository

Path	What it is
rust/	The cargo workspace, 10 crates: core is the engine, cli the binary entry point, tui / server two other front ends
rust/DESIGN.md	Design and behaviour in detail — why each trade-off is what it is. Long, and the only authority
docs/plan/	One numbered file per development task, including what went wrong; HANDOFF.md is the current state (written in Chinese)
config/	Configuration example

make help lists every build target (make check = fmt + clippy + test, the three commands to run before every commit).