single binary · local or remote models · full-screen terminal UI

# An open-source AI coding agent for your terminal.

Use Claude, GPT, Gemini or a local model to plan, edit and test code in your repo. You set how much it does without asking: ask, accept-edits, auto or readonly. One Rust binary, MIT licensed. `bwn` is the short name for `buildwithnexus`.

[Install in one command](https://buildwithnexus.dev/docs/install) [How permissions work](https://buildwithnexus.dev/docs/hooks)

As of 18 Nov 2026, not counting this project's own CI installs, npm shows 22,463 downloads since the February 2026 release, and crates.io shows 810 for `buildwithnexus` and 570 for the `bwn` alias.

If `~/.local/bin` is not on `PATH`, the script prints the line to add.

```
curl -fsSL https://buildwithnexus.dev/install.sh | sh
```

[![bwn 0.21.0 in kitty drawing a pasted screenshot of the buildwithnexus home page. The transcript labels the file site.png, 732 by 500, and the picture shows the headline An open-source AI coding agent for your terminal.](https://buildwithnexus.dev/screenshots/bwn-inline.png)](https://buildwithnexus.dev/screenshots/bwn-inline.png)

bwn 0.21.0 in kitty 0.32.2 on Linux. The picture is a screenshot of this site's home page. Pasting its path drew it inline with the kitty graphics protocol before the message was sent. A local server at `127.0.0.1:8765` answered the startup probe, so the terminal shows no provider warning. No prompt was sent. This file is the kitty window cropped around the image. Tap it to open it full size.

[![bwn 0.21.0 after typing a slash. The popup lists /plan, /build, /brainstorm, /mode, /permissions, /sandbox, /model and /effort, and says 1 of 87.](https://buildwithnexus.dev/screenshots/bwn-commands.png)](https://buildwithnexus.dev/screenshots/bwn-commands.png)

The same binary after typing `/`. The popup is the real command list. It starts at `/plan` and says 1/87. ↑ and ↓ move through it, Tab or Enter accepts, and Esc dismisses. Tap the image to open it full size.

## New in 0.21

- **The shell sandbox is on by default.** `"sandbox": "auto"` confines commands when a backend works. Linux uses bubblewrap, and Landlock plus seccomp when bubblewrap is missing, including in WSL when the kernel allows it. `"sandbox": "off"` or `--sandbox off` runs commands unsandboxed.
- **Sandboxed git writes are blocked.** A sandboxed shell command cannot write `.git`. `git fetch`, `git pull` and `git commit` from the shell fail, and the tool result says why and names `--sandbox off`. Landlock cannot keep `.git` read-only.
- **File edits are committed.** In a git repository, file-tool edits are committed with a `bwn:` subject, outside the sandbox, and git hooks are not run. `"auto_commit": false` or `--no-auto-commit` leaves them uncommitted. `/commit` still asks.
- **`repo_map` is a tool.** The model can ask for a map of files and top-level symbols. The map is not inserted into the prompt. `"repo_map": false` or `--no-repo-map` hides it.
- **A bare `gemini…` name selects the Gemini preset.** `"route_gemini": "openrouter"` or `--route-gemini openrouter` restores the OpenRouter `google/<name>` route.

[What's new in 0.21 →](https://buildwithnexus.dev/docs/whats-new) · [Full changelog →](https://buildwithnexus.dev/docs/changelog)

## On main, after 0.21

Merged and not yet in a release. The registry builds are still 0.21.0.

- **Debug panel and IDE view.** `F12` opens the debug panel; `F2`, `F3` and `F4` open the file tree, the diff and the fuzzy finder. See [Debug and IDE](https://buildwithnexus.dev/docs/debug-and-ide).
- **`/system-prompt`** shows every layer a turn sends, with its source and an estimated token count, and edits or suggests the override.
- **MCP resources and prompts** are read-only tools, `mcp_resources` and `mcp_prompts`, offered only when a server publishes them.
- **Markdown is drawn in the terminal:** headings, lists, tables, quotes, links and fenced code, instead of the raw markers.
- **Bundled workflow commands.** `/test`, `/handoff`, `/changelog`, `/design-pass` and `/deslop`, plus the `distinctive-design` and `deslop` skills, come from [nexus-workflows](https://github.com/Garretts-Apps/nexus-workflows). See [Workflow kit](https://buildwithnexus.dev/docs/workflow-kit) for all 48 commands, the skills, and how a bare `/test` finds its own scope.

[Unreleased changes →](https://buildwithnexus.dev/docs/changelog#unreleased)

[![bwn 0.21.0 idle in the full-screen terminal. The composer is in BRAINSTORM mode, and a warning says nothing is answering at the local Ollama server on localhost port 11434.](https://buildwithnexus.dev/screenshots/bwn-composer.png)](https://buildwithnexus.dev/screenshots/bwn-composer.png)

bwn 0.21.0, idle. This capture points at a local Ollama server that is not running, so the composer is on screen and bwn says nothing is answering at `localhost:11434`. No model was called. Tap the image to open it full size.

[![bwn 0.21.0 after typing /help, showing keys, approval answers, and the composer still on screen.](https://buildwithnexus.dev/screenshots/bwn-help.png)](https://buildwithnexus.dev/screenshots/bwn-help.png)

The same session after `/help`. The window shows the end of the real help text: keys, how an approval is answered, and the composer.

[![bwn doctor 0.21.0. Settings name Ollama and qwen2.5-coder. The provider check fails because no server is answering at localhost port 11434.](https://buildwithnexus.dev/screenshots/bwn-doctor.png)](https://buildwithnexus.dev/screenshots/bwn-doctor.png)

`bwn doctor` on 0.21.0. Settings name Ollama, and the provider check fails because no server is answering.

### Inline images

Screenshots and video frames appear inside the transcript as soon as you paste them or drop them onto the terminal. bwn uses the kitty graphics protocol on kitty, Ghostty and WezTerm (with placeholder support), and Sixel on terminals that support it, such as Windows Terminal 1.22 or later, WezTerm, foot and mlterm. Other truecolor terminals get half-block art. Sixel and half-block previews need ffmpeg. On kitty and Ghostty, a PNG draws without ffmpeg, but other images and video frames need it.

### Code rendering

Syntax highlighting covers 20+ languages, and Markdown tables stay aligned. Diffs highlight the changed part of each line, and file paths are clickable. The terminal UI re-wraps only the transcript line that changed and draws each frame in one synchronized update, and it has live autocomplete for slash commands.

### Plan, build, brainstorm

Shift+Tab cycles through three modes. PLAN breaks the task into steps for you to approve, BUILD runs the agentic ReAct loop, and BRAINSTORM is a chat in which the agent can use read-only tools and never writes.

### Local models

bwn talks to a server on your machine: Ollama's native API, llama.cpp, LM Studio, or any OpenAI-compatible endpoint. It reads each model's context window and recovers tool calls that small coder models write as tagged text.

### Permissions and checkpoints

Permission gates run in ask (the default), accept-edits, auto or readonly mode. In auto, bwn edits files and runs commands without asking. Dangerous commands, sensitive paths such as `.env` and `~/.ssh`, and calls an ask rule covers still prompt, unless one of your own hooks allows them. These gates prevent mistakes. They are not a sandbox, so run untrusted work in a container or VM. Shell commands are confined by default (`"sandbox": "auto"`), with Landlock and seccomp on Linux when bubblewrap is missing. `"sandbox": "off"` or `--sandbox off` turns that off. Checkpoints let you undo what the agent's write, edit, move and delete tools changed in text files up to 2 MiB. They do not cover changes made by shell commands, `apply_patch` or `str_replace_editor`.

### MCP, skills, AGENTS.md

bwn is a full MCP client over stdio and HTTP. It loads Agent Skills folders and reads the same AGENTS.md and CLAUDE.md instruction files as other agents. The terminal UI asks before it uses a repository's own instruction files, and a repository's skills load only after you trust the folder.

### Hooks

Hooks run your own commands at the same lifecycle points as Claude Code. A project hook can deny a tool but never grant one.

### Sessions and workflows

Resume any session, queue background workflows with /schedule and /loop, and add a note to your next message with /btw.

### One binary

A release binary needs no language runtime. The 0.21.0 Linux x86_64 build is 6.2 MB. Startup time, memory and the other platforms are in [BENCHMARKS.md](https://github.com/Garretts-Apps/buildwithnexus/blob/main/BENCHMARKS.md). The Linux binaries need glibc 2.34 or later. The installer copies that checksum-checked binary onto your PATH. The npm alternative downloads it on the first run, checks the SHA-256, and the next `bwn` is the native file. Without a terminal, as in CI, pass `--bootstrap` or set `BWN_ALLOW_BOOTSTRAP=1` to allow that download. Each release binary carries a build-provenance attestation.

## Questions

### What is buildwithnexus?

buildwithnexus (`bwn` for short) is an open-source AI coding agent for the terminal. It uses Claude, GPT or a local model to plan, edit and test code in your repository. It is one Rust binary, MIT licensed.

### Is it free?

Yes. buildwithnexus is open source under the MIT license, with no account, no telemetry and no analytics. You use your own API key, so a remote provider's pricing applies; a local model has no API cost.

### How do I install it?

Install the native binary with the command for your system on [Install](https://buildwithnexus.dev/docs/install), then run `bwn`. `cargo install buildwithnexus --locked` and `npm install -g buildwithnexus` are the alternatives. npm's first run downloads the binary and checks its SHA-256; the next `bwn` is that file.

### Which models does it work with?

Anthropic (Claude), OpenAI, OpenRouter, Groq, Hugging Face, Gemini, xAI, Mistral and DeepSeek with an API key; local models through Ollama, a llama.cpp server or LM Studio; and any OpenAI-compatible endpoint. A name that starts with `gemini` selects the Gemini preset. `/model` switches the model and the provider mid-session. See [Models & providers](https://buildwithnexus.dev/docs/models).

### Can it run entirely on my machine?

Yes. With Ollama, llama.cpp, LM Studio or another server on your machine or your network, the prompts, code and command output go to that server and nowhere else. You can turn off the little other traffic there is, such as the daily update check. See [Data & privacy](https://buildwithnexus.dev/docs/data).

### Does it change files without asking?

Not by default. In ask mode, the default, it asks before each change. accept-edits applies file edits inside the workspace without asking but still asks before commands and deletions. auto edits files and runs commands without asking, except for dangerous commands and sensitive paths. readonly refuses every change. In a git repository, file-tool edits are then committed on their own. `"auto_commit": false` or `--no-auto-commit` leaves them uncommitted, and `/commit` still asks. `/undo` reverts the edits its file tools made in the last turn. See [Permissions & hooks](https://buildwithnexus.dev/docs/hooks).

### What does it send to the model provider?

Each request carries the conversation so far: what you type and attach, the files the agent reads, the output of the commands it runs, and its system prompt. It sends no machine identifier, usage statistics or crash reports. See [Data & privacy](https://buildwithnexus.dev/docs/data).

### Which platforms does it run on?

Linux on x86_64 and aarch64 with glibc 2.34 or later, macOS on Intel and Apple Silicon, and Windows on x86_64. The same Linux binary runs in WSL2. The prebuilt binaries do not run on musl or Alpine.

### Can I run it in CI?

Yes. `bwn run "<task>"` runs without the terminal UI, using the provider from `--provider` or the first API key in the environment. Pass `--permission-mode auto` to let it make changes. On an npm install, the first run without a terminal also needs `--bootstrap` or `BWN_ALLOW_BOOTSTRAP=1`. See [Quickstart](https://buildwithnexus.dev/docs/quickstart#headless).

MIT licensed · Made by [Garrett Eaglin](https://garretteaglin.com/)
