README
¶
kvit-coder
A coding agent in Go. Two binaries: kvit-coder runs one turn (user question -> multiple steps calling tools -> model's answer) and exits. And kvit-coder-ui - the interactive terminal front end.
The agent started as experiment to see how much coding can be done with locally ran weak models and was extended with features more suitable to strong models. Weak/strong modes change how tools behave and how much handholding is done. Each model added to the agent flagged as weak or strong.
It uses small amound of RAM (<30 Mb) compared to hundreds Mbs other agents use. See docs/agents-ram.md.
This is important to me as I often have dosens of agents opened/running/waiting at any moment.
Install
curl -fsSL https://raw.githubusercontent.com/kvit-s/kvit-coder/main/install.sh | sh
To build from source, see CONTRIBUTING.md.
Windows (native, 10/11). Download the portable zip for your machine
(kvit-coder_<version>_windows_amd64_portable.zip, or arm64) from the
latest release,
extract it where you want to keep it (e.g. C:\apps\kvit-coder), then run the
install.ps1 inside that folder — it adds the folder to your user PATH and
seeds %USERPROFILE%\.kvit-coder\config.yaml:
powershell -ExecutionPolicy Bypass -File install.ps1
Or install a published release straight into %USERPROFILE%\bin:
irm https://raw.githubusercontent.com/kvit-s/kvit-coder/main/install.ps1 | iex
Platforms. Linux is where this is developed and used daily, including under
Windows Subsystem for Linux (WSL). The macOS builds compile and are published,
but never tested. Native Windows (10/11, amd64 and arm64) builds, runs, and passes tests;
it needs Git for Windows (for sh.exe, grep, and git itself) and installs
via the portable zip or install.ps1 (see above). WSL stays supported regardless; benchmarks stay
WSL/unix-only (see spec/windows.md).
Configure
Copy config.example.yaml to
~/.kvit-coder/config.yaml (on Windows: %USERPROFILE%\.kvit-coder\config.yaml)
and point the llm: block at an endpoint you have —
a local llama.cpp, vLLM or Ollama server, or any hosted API that speaks the same
protocol:
Without -config, both binaries take the first of $KVIT_CODER_CONFIG,
./config.yaml, ~/.kvit-coder/config.yaml (%USERPROFILE%\.kvit-coder\config.yaml
on Windows), and config.yaml beside the binary with symlinks resolved.
Every key is documented in
docs/configuration.md, including the parts
config.example.yaml leaves out: defining more than one model and switching
between them, Model Context Protocol (MCP) servers that provide external tools,
tool groups that hide tools until the model asks for them,
and the path and shell safety rules.
Run
# Interactive. The directory it starts in is the workspace.
kcu
# One turn, headless. This is what you script against.
kvit-coder -p "Find all TODO comments in the codebase"
# Only the final answer on stdout.
kvit-coder -pq "What does main.go do?"
A turn that fails exits non-zero and says why. On a terminal the final answer is
rendered as styled markdown; piped output, --json, NO_COLOR and TERM=dumb
stay raw. Every flag is in docs/cli.md.
Running commands on your machine
This program executes shell commands and edits files. workspace.path_safety_mode
decides what happens when a path outside the workspace directory is read or
written: allow, block, warn, ask_once or ask_always, where the asking
modes prompt on /dev/tty and remember the answer for the run. Shell commands
are parsed into a syntax tree and each simple command in the line is checked on
its own against the built-in rules and the allow and deny lists in
tools.shell. A refused command comes back to the model as a tool result saying
what it would have done, so the turn can continue with something else. --yolo
disables these prompts for a run.
Benchmarks
The harness includes three benchmarks. These are designed to check basic agentic
skills of weak models. See benchmarks/README.md.
Documents
docs/ holds the reference documentation: the
tools the model can call, every
command-line flag, every configuration key,
how to add an OpenCode model,
sessions and steering, external tools, the
memory measurements quoted above, and
how the program is built: one process per turn, sessions
as directories, and the other design decisions behind it.
License
MIT
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
kvit-coder
command
|
|
|
kvit-coder-ui
command
|
|
|
internal
|
|
|
acp
Package acp is the wire side of the Agent Client Protocol: JSON-RPC 2.0 messages, one per line, read from the client on standard input and written to it on standard output.
|
Package acp is the wire side of the Agent Client Protocol: JSON-RPC 2.0 messages, one per line, read from the client on standard input and written to it on standard output. |
|
agent
Package agent provides the agent runner for executing LLM interactions.
|
Package agent provides the agent runner for executing LLM interactions. |
|
benchmark
Package benchmark provides benchmarking infrastructure for testing LLM tool usage.
|
Package benchmark provides benchmarking infrastructure for testing LLM tool usage. |
|
filelock
Package filelock provides an exclusive, non-blocking file lock with the same "already in use by another process" semantics on every OS.
|
Package filelock provides an exclusive, non-blocking file lock with the same "already in use by another process" semantics on every OS. |
|
inbox
Package inbox is the one place a turn picks up anything that arrives while it is running: a line you type, a file dropped in the session's inbox directory by "kvit-coder steer", or an event from a background process.
|
Package inbox is the one place a turn picks up anything that arrives while it is running: a line you type, a file dropped in the session's inbox directory by "kvit-coder steer", or an event from a background process. |
|
markdown
Package markdown renders the final assistant answer as styled terminal output.
|
Package markdown renders the final assistant answer as styled terminal output. |
|
mcp
Package mcp implements a Model Context Protocol (MCP) client for kvit-coder.
|
Package mcp implements a Model Context Protocol (MCP) client for kvit-coder. |
|
permissions
Package permissions decides whether a shell command may run, from what the command actually is rather than from what its text looks like.
|
Package permissions decides whether a shell command may run, from what the command actually is rather than from what its text looks like. |
|
procs
Package procs runs commands that outlive the turn's iterations.
|
Package procs runs commands that outlive the turn's iterations. |
|
procutil
Package procutil abstracts the per-OS process plumbing the agent needs:
|
Package procutil abstracts the per-OS process plumbing the agent needs: |
|
prompt
Package prompt provides system prompt generation for the agent.
|
Package prompt provides system prompt generation for the agent. |
|
repl
Package repl provides the exec mode runner for the agent.
|
Package repl provides the exec mode runner for the agent. |
|
report
Package report holds the structured end-of-turn report: its shape, the checks it must pass before the agent accepts it, and the rendering the agent and the interactive front end both draw it with.
|
Package report holds the structured end-of-turn report: its shape, the checks it must pass before the agent accepts it, and the rendering the agent and the interactive front end both draw it with. |
|
session
Package session stores a conversation and everything else that outlives one turn: spilled tool output, the steering inbox and the record of background processes.
|
Package session stores a conversation and everything else that outlives one turn: spilled tool output, the steering inbox and the record of background processes. |
|
stats
Package stats provides statistics tracking for agent operations.
|
Package stats provides statistics tracking for agent operations. |
|
tui
Package tui provides the interactive terminal UI for kvit-coder-ui.
|
Package tui provides the interactive terminal UI for kvit-coder-ui. |
|
update
Package update checks the GitHub releases for a newer build and installs it.
|
Package update checks the GitHub releases for a newer build and installs it. |
|
workspace
Package workspace provides workspace-level utilities including locking.
|
Package workspace provides workspace-level utilities including locking. |