README
¶
kaku
Kaku (書く, "to write") is a coding agent that lives in your terminal. One static Go binary, no runtime to install, no cloud lock-in. Point it at the Anthropic API or at any OpenAI-compatible endpoint: chat completions or the Responses API, a llama.cpp or MLX server on your own hardware, or a hosted proxy.
Sibling of yomi: yomi reads the web, kaku writes code.
Why another coding agent
Everything is a file and everything is a plugin.
- Sessions are JSONL you can cat, grep, and resume.
- Skills, subagents, and project memory are Markdown you can edit by hand.
- External tools arrive over MCP; the builtin set stays small and trusted.
- Permissions are explicit: plan, ask, or auto, with allow and deny rules in settings.
- The engine is a plain Go package; the CLI, TUI, and server are thin adapters over it.
Docs live at kaku.tamnd.com.
Install
brew install tamnd/tap/kaku # macOS, Linux
scoop bucket add tamnd https://github.com/tamnd/scoop-bucket && scoop install kaku
go install github.com/tamnd/kaku/cmd/kaku@latest
docker run -it -v "$PWD:/work" -e ANTHROPIC_API_KEY ghcr.io/tamnd/kaku
Signed apt and dnf repositories and prebuilt archives are covered in the installation docs.
Quick start
export ANTHROPIC_API_KEY=...
kaku # interactive TUI in the current project
kaku -p "fix the failing test" # headless, prints the answer, exits
To run against a local model:
kaku --provider openai --base-url http://127.0.0.1:8080/v1 --model qwen3-30b
Servers that speak the newer OpenAI Responses API work too:
kaku --provider responses --base-url http://127.0.0.1:8000/v1 --model gpt-5
Sandbox
kaku --sandbox confines bash writes to the working directory and temp locations, using Seatbelt on macOS and landlock on Linux.
Reads and network stay open, so builds and tests keep working.
On Linux kernels without landlock the flag degrades to no confinement.
Checkpoints
In a git repository, kaku snapshots the working tree before the first file-changing tool call of every turn.
Snapshots live under a hidden ref (refs/kaku/checkpoint), so your branches, index, and HEAD are never touched.
kaku rewind --list # show checkpoints
kaku rewind # restore the newest one
kaku rewind 8602b78 # restore a specific one
The state before a rewind is snapshotted too, so a rewind can itself be undone.
Server and MCP
kaku serve exposes one conversation over HTTP with SSE streaming:
kaku serve --mode auto &
curl -N localhost:8377/v1/messages -d '{"prompt":"run the tests"}'
curl localhost:8377/v1/history
kaku mcp turns the whole agent into an MCP server on stdio.
Add it to another agent's MCP config and that agent gains a kaku tool whose calls share one conversation:
{"mcpServers": {"kaku": {"command": "kaku", "args": ["mcp", "-C", "/path/to/project", "--mode", "auto"]}}}
Both surfaces are headless, so ask-mode permission prompts degrade to deny; pass --mode auto (or allow rules in settings) to let tools run.
Go SDK
The engine is a plain Go package, and every surface above is a thin adapter over it:
reg := tool.NewRegistry(builtin.All(dir, nil, nil)...)
a := &engine.Agent{
Provider: anthropic.New(os.Getenv("ANTHROPIC_API_KEY"), ""),
Model: "claude-sonnet-5",
Tools: reg,
Perm: &perm.Engine{Mode: perm.ModeAsk, ReadOnly: reg.ReadOnly},
}
out, err := a.Run(ctx, "what does this package do?")
See the runnable example in pkg/engine for streaming events, permission rules, and continuing a conversation.
Configuration
Global config lives in ~/.kaku/config.json, per-project settings in .kaku/settings.json.
Project instructions are read from KAKU.md, and AGENTS.md or CLAUDE.md are picked up too, so kaku drops into existing repos.
License
MIT
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
kaku
command
kaku is a coding agent in one binary.
|
kaku is a coding agent in one binary. |
|
pkg
|
|
|
agentdef
Package agentdef turns markdown agent definitions into a tool the main loop can call to fan work out to subagents.
|
Package agentdef turns markdown agent definitions into a tool the main loop can call to fan work out to subagents. |
|
auth
Package auth stores one API key per provider in ~/.kaku/auth.json so a user can log in once instead of exporting an environment variable each session.
|
Package auth stores one API key per provider in ~/.kaku/auth.json so a user can log in once instead of exporting an environment variable each session. |
|
checkpoint
Package checkpoint snapshots the working tree into a hidden git ref so a turn that went wrong can be rewound.
|
Package checkpoint snapshots the working tree into a hidden git ref so a turn that went wrong can be rewound. |
|
compact
Package compact keeps conversation history inside the context budget by summarizing its older part.
|
Package compact keeps conversation history inside the context budget by summarizing its older part. |
|
config
Package config loads kaku settings: built-in defaults, then the user's ~/.kaku/config.json, then the project's .kaku/settings.json.
|
Package config loads kaku settings: built-in defaults, then the user's ~/.kaku/config.json, then the project's .kaku/settings.json. |
|
engine
Package engine runs the agent loop: model completions, tool dispatch, permission checks, and history maintenance.
|
Package engine runs the agent loop: model completions, tool dispatch, permission checks, and history maintenance. |
|
hook
Package hook runs user-configured lifecycle shell commands.
|
Package hook runs user-configured lifecycle shell commands. |
|
image
Package image loads a local image file into the base64 form the model providers expect, downscaling oversized PNG and JPEG images so a phone-sized screenshot does not blow the token budget.
|
Package image loads a local image file into the base64 form the model providers expect, downscaling oversized PNG and JPEG images so a phone-sized screenshot does not blow the token budget. |
|
lsp
Package lsp runs language servers on the side so the agent sees diagnostics for a file it just wrote without shelling out to a build.
|
Package lsp runs language servers on the side so the agent sees diagnostics for a file it just wrote without shelling out to a build. |
|
mcp
Package mcp implements a Model Context Protocol client over stdio and streamable HTTP transports, exposing remote tools to the tool registry.
|
Package mcp implements a Model Context Protocol client over stdio and streamable HTTP transports, exposing remote tools to the tool registry. |
|
memory
Package memory gathers project instructions for the system prompt.
|
Package memory gathers project instructions for the system prompt. |
|
mention
Package mention expands @file references in a prompt into the file's contents, so "explain @main.go" reaches the model with the file inlined.
|
Package mention expands @file references in a prompt into the file's contents, so "explain @main.go" reaches the model with the file inlined. |
|
perm
Package perm decides whether a tool call may run.
|
Package perm decides whether a tool call may run. |
|
provider
Package provider defines the model provider SPI and the message types shared across the agent.
|
Package provider defines the model provider SPI and the message types shared across the agent. |
|
provider/anthropic
Package anthropic implements provider.Provider over the Anthropic Messages API with streaming.
|
Package anthropic implements provider.Provider over the Anthropic Messages API with streaming. |
|
provider/openai
Package openai implements provider.Provider over the OpenAI chat completions API with streaming.
|
Package openai implements provider.Provider over the OpenAI chat completions API with streaming. |
|
provider/responses
Package responses implements provider.Provider over the OpenAI Responses API with streaming.
|
Package responses implements provider.Provider over the OpenAI Responses API with streaming. |
|
rpc
Package rpc exposes one agent conversation over a newline-delimited JSON protocol on stdin/stdout.
|
Package rpc exposes one agent conversation over a newline-delimited JSON protocol on stdin/stdout. |
|
serve
Package serve exposes one agent conversation over HTTP with SSE streaming.
|
Package serve exposes one agent conversation over HTTP with SSE streaming. |
|
session
Package session persists conversations as JSONL transcripts under ~/.kaku/sessions/<project>/<id>.jsonl.
|
Package session persists conversations as JSONL transcripts under ~/.kaku/sessions/<project>/<id>.jsonl. |
|
skill
Package skill loads markdown skill files, the bodies behind slash commands.
|
Package skill loads markdown skill files, the bodies behind slash commands. |
|
tool
Package tool defines the tool SPI and the registry the engine draws from.
|
Package tool defines the tool SPI and the registry the engine draws from. |
|
tool/builtin
Package builtin provides the standard toolset every kaku agent starts with.
|
Package builtin provides the standard toolset every kaku agent starts with. |
|
tui
Package tui is the interactive terminal interface over the engine.
|
Package tui is the interactive terminal interface over the engine. |