Local-first coding agent · macOS, Linux and Windows · MIT

Reads, edits and runs in your project only with your permission.

Kiwi is an agent for the terminal. It runs on your machine, saves every session in local SQLite and works with the model provider you choose. It does not make a single change you have not approved.

curl -fsSL https://raw.githubusercontent.com/oscar1223/kiwi/main/install.sh | sh
See how it works Also on Windows · Homebrew · Scoop · Go
  • 3permission modes
  • 19providers ready
  • 0telemetry by default
  • 1binary, no runtime

01 · Permission modes

Three modes. One active. shift+tab to switch.

The mode decides what the agent can do without asking you. Try it here: click a mode, or focus the window and press shift+tab.

kiwi — ~/code/kiwi
  1. ›add a --json flag to kiwi ask
  2. ⏺read_file cmd/kiwi/ask.go
  3. I'll add the flag and serialize the final answer.
  4. ⏺edit_file cmd/kiwi/ask.go
  5. +jsonOut := flag.Bool("json", false, "JSON output")
  6. ?Apply this edit? [y] yes [n] no [a] always
ask│sonnet│ctx 12%

02 · Tools

What the agent can touch.

All of them go through the active mode, native ones and those an MCP server brings.

  • read_file

    Reads any file in the project, and grep and glob find them. You can also attach one yourself by typing @path/to/file.

  • edit_file

    Edits in place and shows you the diff before touching anything. write_file creates new files.

  • bash

    Runs commands. Long ones go to the background with bash_background, bash_output and kill_shell.

  • lsp

    Talks to your language server: real definitions, references and diagnostics instead of guessing.

  • remember

    Saves a durable fact. It goes through the same permission as a write: blocked in plan.

  • web_search

    Searches the web with zero setup, and web_fetch reads the page. With an Exa or Jina key, better results.

  • ask_questions

    Asks you multiple-choice questions before settling on a plan. Better to ask once than to assume.

  • mcp

    Tools from any configured MCP server are added automatically, behind the same permission.

03 · Skills and subagents

It knows how to do more. And it splits the work.

Skills give it instructions for a specific task and only take up context when loaded. Subagents take a big search into their own conversation and only hand you back the summary.

Skills

Markdown files with instructions. Kiwi ships seven, and each one is also a command. Yours are written the same way, and a skill you have edited is never overwritten on update.

  • /code-reviewbugs and simplifications, with file:line
  • /security-reviewinjection, secrets, SSRF, path traversal…
  • /commita message from what is staged
  • /testruns the tests and fixes what fails
  • /plana PLAN-*.md with reasoned decisions
  • /initwrites KIWI.md / AGENTS.md after reading the project
  • /reachresearches beyond the repo: web, GitHub, YouTube

~/.config/kiwi/skills/ — outside the repo

Subagents

With the task tool the agent hands a job to another one that starts from scratch. Your conversation does not fill up with every file it read: only its summary comes back.

exploreread-only

Searches, reads and runs read-only commands. It is read-only by construction, not by mode: not even in work can it write, so it never interrupts you for permission.

generalwith permissions

Everything the main agent can do, except delegate in turn. It edits and runs behind the same mode as you.

the agent decides — you do not have to ask

04 · Memory and context

Two things that often get confused.

The conversation

Large, specific to the session, and compacted automatically. The threshold comes from the active model's real window — half of it — so a 200k model is not compacted on the same terms as a 32k one. When it triggers, old messages are replaced by a summary and recent ones stay as they are.

/compactctx 58%

Saved notes

A handful of lines that outlive the session and travel with every prompt. global scope about you, or project about this directory. When full, the oldest drop off, and Kiwi tells you instead of forgetting silently.

~/.config/kiwi/memory/global.md

~/.config/kiwi/memory/projects/kiwi.md

outside the repo — never shows up in your git status

For shared, versioned instructions there is KIWI.md / AGENTS.md, which Kiwi reads and never writes.

05 · Providers

Bring your own key.

Twenty built-in profiles on five native integrations — Anthropic, OpenAI, Azure OpenAI, Vertex and Bedrock. Any other chat-completions API plugs in by changing base_url and the key variable, and the key is never stored in the config: only the name of its environment variable.

  • anthropic
  • openai
  • ollama
  • openrouter
  • groq
  • deepseek
  • mistral
  • xai
  • cerebras
  • perplexity
  • together
  • fireworks
  • deepinfra
  • moonshot
  • zhipu
  • gemini
  • azure
  • vertex
  • bedrock

06 · Get started

Three steps.

  1. 01

    Install

    One binary, no Go, no runtime, no daemon behind it. It verifies its SHA256 before installing.

    curl -fsSL https://raw.githubusercontent.com/oscar1223/kiwi/main/install.sh | sh
  2. 02

    Start

    From the root of the project you want to work on.

    kiwi
  3. 03

    Pick a provider

    The first time, onboarding asks for provider, model and API key. Adjust it later with /model.

    /model

Install on your system

curl -fsSL https://raw.githubusercontent.com/oscar1223/kiwi/main/install.sh | sh

You can also download the binary by hand from Releases.

For a single non-interactive turn: git diff | kiwi ask "review this patch" -. Everything else is in the docs.

07 · FAQ

Frequently asked questions.

Does Kiwi send my code anywhere?

Only to the model provider you configure. There is no telemetry by default and every session is saved in local SQLite, on your machine.

Where is my API key stored?

Nowhere in Kiwi. The config only stores the name of the environment variable that holds the key.

What do I need to install it?

Nothing but the binary: no Go, no runtime, no daemon. On Windows, the bash tool needs Git Bash or WSL on the PATH.

Can I use it without the interactive interface?

Yes. kiwi ask runs a single turn and accepts piped input, for example git diff | kiwi ask "review this patch" -.

What license is it under?

MIT. The code is at github.com/oscar1223/kiwi.

Try it on your next project.

One line to install it. You decide what it can touch.

INSTALLVIEW ON GITHUB