Quickstart
1. Install
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Stack-Cairn/K-brain/main/install.sh | sh
Windows PowerShell
& ([scriptblock]::Create((Invoke-WebRequest -UseBasicParsing https://raw.githubusercontent.com/Stack-Cairn/K-brain/main/install.ps1).Content))
The installers download platform binaries from GitHub Releases and verify SHA-256 checksums. Windows installs to %LOCALAPPDATA%\Programs\k-brain by default; open a new terminal for PATH changes to take effect. If a suitable release is not available, build from source.
Manual downloads: Windows, Linux, macOS × x64, ARM64
Main assets are named k-brain-<os>-<arch>, with .exe on Windows. os is windows, linux, or darwin; arch is x64 or arm64. Rename the main binary to kn (kn.exe on Windows), put it on PATH, and make it executable on Linux/macOS.
For computer-use, rename k-brain-computer-<os>-<arch> to k-brain-computer (with .exe on Windows) and place it beside the main binary. See Computer-use for runtime dependencies.
Edit ~/.k-brain/config.json, or $HOME\.k-brain\config.json on Windows. The file supports JSONC comments and trailing commas. Set K_BRAIN_HOME to use another configuration directory.
{
"defaultModel": "model1",
"providers": {
"demo": {
"name": "demo",
"api": "openai-completions",
"baseUrl": "https://api.example.com/v1",
"apiKey": "YOUR_API_KEY",
"models": [
{"id": "model1", "contextWindow": 128000, "maxTokens": 8192},
{"id": "model2", "contextWindow": 128000, "maxTokens": 8192}
]
}
}
}
Replace baseUrl, apiKey, model1, and model2 with your provider's values. K-brain supports third-party API-key connections only, with no built-in account login, OAuth, or subscription authentication.
api |
Protocol |
openai-completions |
OpenAI Chat Completions |
openai-responses |
OpenAI Responses |
anthropic-messages |
Anthropic Messages |
- Use an API prefix such as
https://api.example.com/v1 for baseUrl, not a complete /chat/completions endpoint.
- Declare models inside each provider's
models array. The legacy top-level models format is not supported.
contextWindow is the context token limit; maxTokens is the output token limit. Set them to the model's actual limits. Explicit configuration takes precedence over the model catalog.
/model refresh fetches baseUrl + "/models", which is /v1/models in this example. Use /model to select a model.
- Restart after editing the file. The TUI can open without API credentials, but model requests require a valid configuration.
3. Start a task
Run this in your project directory:
kn
Describe the task directly:
Read this project, find the cause of the failing tests, fix it, run the relevant tests, and summarize the changes.
The TUI uses a full-screen terminal view with a bottom-anchored input area. The session title appears at the bottom right after the first turn. Use kn -c to continue the latest session in the current directory, or kn --resume to open the session picker.
Usage
Interactive sessions
| Input |
Action |
/model · /effort |
Switch models and adjust reasoning effort |
/context · /compact |
Inspect context and compact it manually |
/rewind · /fork |
Rewind to an earlier turn or branch a session |
/title · /resume |
Rename or resume a session |
/diff [--staged] [--stat] |
Inspect tracked Git changes locally, without a model request |
/copy [N] [file] |
Copy the Nth latest assistant message with text, or save it to a new file |
/prompts [refresh] |
List or reload Markdown prompt templates |
/mcp · /tasks |
Manage MCP connections and inspect background tasks |
!command · !!command |
Run a shell command; the first adds output to the conversation, the second stays local |
/help |
Show all commands and keyboard shortcuts |
Use Ctrl+P for the command palette, Ctrl+J for a newline, Esc to interrupt the current task, and PgUp/PgDn to scroll. Launch with kn -cautious to request confirmation before commands or file writes.
Markdown prompt templates
Put global templates in ~/.k-brain/prompts/ and project templates in a trusted project's .k-brain/prompts/. Discovery is non-recursive. Project templates override global templates of the same name; built-in commands take precedence.
Example audit.md:
---
description: Review a module
argument-hint: "<module> [focus]"
---
Review $1, focusing on ${2:-correctness and test coverage}.
Additional requirements: ${@:3}
Run /prompts refresh, then enter /audit "internal/agent" "concurrency". The template expands into the input area; press Enter again to send it.
Supported substitutions: $1, $2, $@, $ARGUMENTS, ${1:-default}, ${@:-default}, ${ARGUMENTS:-default}, ${@:N}, and ${@:N:L}. Arguments accept single or double quotes. Templates do not perform shell or environment-variable expansion. Metadata supports simple single-line fields, not full YAML. Files are limited to 1 MiB.
Headless use and backend integration
kn run "Explain this project's structure"
git diff | kn run "Review these changes"
kn run --format json --quiet --max-turns 8 --timeout 5m "Find and fix the build failure"
--format json emits newline-delimited JSON events (NDJSON), not one JSON document.
| Entry point |
Purpose |
kn acp |
Connect ACP editors over standard input/output |
kn mcp serve |
Expose built-in file and command tools to other clients |
kn sessions |
List saved sessions |
kn update |
Update the installed version |
The execution core is separate from the TUI and shares model adapters, tool loops, context compaction, background subtasks, and SQLite session storage. Current backend entry points are CLI, ACP, and MCP—not a standalone HTTP service. This repository does not include a Desktop frontend.
- Windows shell: prefers PowerShell 7, falling back to Windows PowerShell. Set
K_BRAIN_SHELL to pwsh, powershell, bash, wsl, cmd, or an executable path. Native Windows does not support Unix-style interactive PTY forwarding.
- Computer-use: Windows uses PowerShell/UIA, macOS uses Python/PyObjC, and Linux uses Python/AT-SPI2. Linux X11 has GTK/Xvfb integration coverage. macOS awaits real-desktop validation; a general Wayland desktop-input portal is not implemented. See dependencies and platform coverage.
Building from source
Requires Git and Go 1.27+. The version requirement is recorded in go.mod.
git clone https://github.com/Stack-Cairn/K-brain.git
cd K-brain
go install ./cmd/kn ./cmd/k-brain-computer
Ensure Go's binary directory, usually ~/go/bin, is on PATH. To run or build directly from the repository:
go run ./cmd/kn
go build -o kn ./cmd/kn
On Windows, use go build -o kn.exe ./cmd/kn, then .\kn.exe. Build or install cmd/k-brain-computer separately when using computer-use.
Documentation
Repository layout
| Path |
Responsibility |
cmd/kn |
Main binary, TUI, headless execution, and protocol entry points |
cmd/k-brain-computer |
Computer-use RPC helper |
internal/agent |
Model/tool loop and subtask coordination |
internal/ai · internal/routing |
Protocol adapters, streaming, and model routing |
internal/config |
Configuration, model catalogs, and local settings |
internal/tools |
Shell, file access, and editing tools |
internal/prompts · internal/skills |
Prompts, templates, and skill loading |
internal/session · internal/memory |
Session persistence and durable memory |
internal/mcp · internal/acp · internal/lsp |
Tool, editor, and language-server protocols |
internal/browser · internal/computer |
Browser and desktop automation |
internal/tui |
Terminal layout, input, and event presentation |
Development
Start with tests for the changed packages, then run broader checks:
go test ./internal/computer/... -count=1
go vet ./internal/computer/...
go test ./...
Some integration tests need platform tools, a graphical session, or explicit environment opt-ins. A successful build does not imply a passing full test suite. Additional tasks are in Taskfile.yaml.
The GitHub Actions release workflow runs only on pushed v* tags. It cross-compiles Windows, Linux, and macOS for x64 / ARM64, generates checksums, and publishes release assets. Ordinary branch pushes do not trigger this workflow.
References and acknowledgments
K-brain references the architecture and implementation ideas of context-labs/whip. Its terminal interaction, execution core, and module organization also draw on OpenAI Codex, Grok Build, Pi, and Claude Code. This README's organization is inspired by Codex and Grok Build.
K-brain is independently maintained and does not represent those projects or their developers.
License
Apache License 2.0.