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 installer for your machine
(kvit-coder_<version>_windows_amd64_setup.exe, or arm64) from the
latest release and run
it. It installs for your user only, without an administrator prompt, into
%LOCALAPPDATA%\Programs\kvit-coder, adds that folder to your user PATH, puts
kc.exe and kcu.exe beside kvit-coder.exe and kvit-coder-ui.exe as the
short names, and seeds %USERPROFILE%\.kvit-coder\config.yaml when there is
none. Open a new terminal afterwards so it sees the new PATH. Uninstall it from
Settings > Apps; that removes the PATH entry and leaves
%USERPROFILE%\.kvit-coder alone.
Without the installer, download the portable zip
(kvit-coder_<version>_windows_amd64_portable.zip, or arm64), extract it
where you want to keep it (e.g. C:\apps\kvit-coder), then run the
install.ps1 inside that folder. It does the same for the folder it runs from:
powershell -ExecutionPolicy Bypass -File install.ps1
Or install a published release straight into %USERPROFILE%\bin, which the
script also puts on the PATH:
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 installer, the portable zip or install.ps1 (see above). WSL stays supported regardless; benchmarks stay
WSL/unix-only (see spec/windows.md).
Configure
Run kcu. With no model configured it opens :setup: choose OpenCode Zen,
OpenCode Go, a local llama.cpp, vLLM, Ollama or LM Studio server, or any other
endpoint that speaks the same protocols; paste its key; and tick the models
you want. It fills in each model's protocol, context size and effort levels
from the endpoint and the models.dev catalog, saves them
to ~/.kvit-coder/models.yaml and the key to ~/.kvit-coder/credentials.json,
and leaves config.yaml alone. Once a model is saved it offers web search,
which needs a Brave Search API key. :setup adds more later and turns web
search on or off, :models switches between models, and :keys replaces a
key; see docs/cli.md.
The installers put a copy of config.example.yaml at
~/.kvit-coder/config.yaml (on Windows: %USERPROFILE%\.kvit-coder\config.yaml),
and kcu offers to write it when there is none. It holds everything except the
model; a model can also be written into it by hand
(docs/models.md).
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
Documentation
¶
Overview ¶
Package kvitcoder holds files from the repository root that the programs need at run time, so there is one copy of each.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ExampleConfig []byte
ExampleConfig is config.example.yaml. kvit-coder-ui writes it to ~/.kvit-coder/config.yaml when it finds no configuration at all; the installers copy the same file from the release archive.
Functions ¶
This section is empty.
Types ¶
This section is empty.
Source Files
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. |
|
modelsetup
Package modelsetup holds what kvit-coder-ui needs to add a model without the person editing a file: the providers it knows, the models.dev catalog that says how each model is served, the endpoint's own list of models, the model row built from those, and a test request that checks a row works.
|
Package modelsetup holds what kvit-coder-ui needs to add a model without the person editing a file: the providers it knows, the models.dev catalog that says how each model is served, the endpoint's own list of models, the model row built from those, and a test request that checks a row works. |
|
office
Package office converts Word, Excel and PowerPoint files to GitHub-flavored Markdown, so that Read can return them as text.
|
Package office converts Word, Excel and PowerPoint files to GitHub-flavored Markdown, so that Read can return them as text. |
|
office/formats
Package formats identifies document formats from content bytes.
|
Package formats identifies document formats from content bytes. |
|
office/formats/docx
Package docx converts WordprocessingML packages into the document model: package parts, then the style and numbering models, then spec-order property resolution over the body, notes and drawings.
|
Package docx converts WordprocessingML packages into the document model: package parts, then the style and numbering models, then spec-order property resolution over the body, notes and drawings. |
|
office/formats/omml
Package omml converts Office Math (m:oMath) trees, shared by WordprocessingML and PresentationML, into LaTeX math for the model.
|
Package omml converts Office Math (m:oMath) trees, shared by WordprocessingML and PresentationML, into LaTeX math for the model. |
|
office/formats/ooxml
Package ooxml holds the content extraction the office frontends share: text cleaning, target and media classification, and the textual content of DrawingML charts and SmartArt.
|
Package ooxml holds the content extraction the office frontends share: text cleaning, target and media classification, and the textual content of DrawingML charts and SmartArt. |
|
office/formats/pptx
Package pptx converts PresentationML packages to the document model: slides in presentation order through the full text cascade, with speaker notes quoted after each slide.
|
Package pptx converts PresentationML packages to the document model: slides in presentation order through the full text cascade, with speaker notes quoted after each slide. |
|
office/formats/xlsx
Package xlsx converts SpreadsheetML workbooks (.xlsx, .xlsm) to the document model: visible sheets in order, each a table of cell values formatted through their number formats, with hidden rows, columns and sheets omitted and merges remapped onto the surviving grid.
|
Package xlsx converts SpreadsheetML workbooks (.xlsx, .xlsm) to the document model: visible sheets in order, each a table of cell values formatted through their number formats, with hidden rows, columns and sheets omitted and merges remapped onto the surviving grid. |
|
office/model
Package model is the intermediate representation office-format frontends produce and the GFM renderer consumes.
|
Package model is the intermediate representation office-format frontends produce and the GFM renderer consumes. |
|
office/opc
Package opc reads ZIP-based OOXML packages under fixed resource limits: part access, content types, relationships with OPC target resolution, and a namespace-aware XML tree.
|
Package opc reads ZIP-based OOXML packages under fixed resource limits: part access, content types, relationships with OPC target resolution, and a namespace-aware XML tree. |
|
office/render/gfm
Package gfm serializes the document model to GitHub-Flavored Markdown.
|
Package gfm serializes the document model to GitHub-Flavored Markdown. |
|
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. |