Quickstart

Launch bwn in a repo and describe a task. The agent reads files, edits them, and runs commands. The permission gate checks every edit and command first. If the agent changed files and tries to finish without running check_work, bwn runs it once. check_work runs your project's build, tests and linter, and a failure goes back to the model for one more round.

The first run sets up a provider and model. If you have not done that yet, see First run on the Install page, or Models & providers for keys and local models. Data & privacy lists what bwn sends to the provider and what stays on your machine.

Interactive session

bwn                         # full-screen TUI
> fix the failing pagination test

Headless

bwn run "fix the failing test"       # agentic BUILD loop, no TUI
bwn plan "migrate the config loader" # decompose, approve, then execute
bwn plan -y "…"                      # auto-approve (required without a TTY)
bwn --json --yes plan "…"            # emits a {"type":"plan"} event, then executes
bwn brainstorm "how should auth work?"
bwn --json run "…"                   # machine-readable event stream

A headless run asks you to approve a change only when stdin is a terminal and you did not pass --json. Otherwise nobody can answer. In the default ask permission mode, bwn then blocks edits, commands and network access. In accept-edits, it makes file edits inside the project and blocks the rest, such as commands, deletions and network access. The run says so before it starts, and it exits with code 3 if it blocked anything. Pass --permission-mode auto to let it make changes, or --permission-mode readonly to only read. Even under auto, some calls need a person, such as a call that reads or changes a sensitive path, a dangerous command, or a call an ask rule covers. A run with no terminal blocks them unless one of your own hooks allows the call. In CI, an API key in the environment is enough, and there is no setup step. On an npm install with no terminal, the first run also needs --bootstrap or BWN_ALLOW_BOOTSTRAP=1 so the npm launcher downloads the binary. Output that is piped or redirected is plain text; set FORCE_COLOR=1 to keep colour. Headless runs never show the trust prompt. They ignore project settings you have not trusted, such as a repo's base_url or hooks, and print a warning that names them. Pass --trust-project <digest> to trust them for one run. When they set base_url, or a permission looser than readonly, also name those keys with --trust-project-allow.

With --json, the last event names the outcome. --legacy-exit-codes turns codes 4 to 8 back into 0, as in 0.14. It does the same for a 3 from a hook, a deny rule or read-only mode, and for a 1 from a call that could not run or from a model that returned no output. A run that ends in an error, a usage error, a blocking review and changes blocked for lack of approval keep their codes.

Options

Options can go before or after the command. In mcp add, every word after the server name belongs to the server's command line, so bwn reads no options there. Every option that takes a value rejects a missing or empty value with exit code 2. -- ends option parsing, so a task can contain literal option names.

Values that start with a dash use the inline form, for example --prompt=--help. bwn --help prints the same list.

Modes

Shift+Tab cycles modes without losing what you have typed. The active mode shows as a colored badge in the banner.

Project instructions

bwn reads the same instruction files other agents use. From the git root down to your current directory, it loads AGENTS.md, or CLAUDE.md where no AGENTS.md exists. It also loads ~/.buildwithnexus/AGENTS.md for global rules. It adds these files to the system prompt in every mode, helper agent, and headless run. In the TUI, the repository's own files need a yes first. The TUI names them, for example instructions from this repo: AGENTS.md, src/AGENTS.md, and asks use them? y yes · n no · r review [N]. Only y adds them, and bwn asks again when one of them changes. Enter, n or Esc leaves them out for that session, and bwn asks again at the next launch. When the folder also has project settings, commands, skills or agents to trust, the trust prompt lists these files too, and its answer covers them, so the use them? question does not appear. A headless run adds them and prints a not reviewed line on stderr until someone accepts them in the TUI. bwn caps each file at 32 KiB and all files together at 96 KiB, and leaves a visible marker wherever it cuts one.

{ "instruction_files": ["AGENTS.md", "CLAUDE.md", "GEMINI.md"] }   // in settings.json; set it to [] to load no instruction files

/init runs setup again, then offers to write an AGENTS.md from the repository's build and test files, or to improve the one already there. It shows the change as a diff you approve. It offers nothing when the folder has a CLAUDE.md and no AGENTS.md. bwn init --agents-md runs the same task as a headless run, under that run's permission mode. With no terminal, the default ask permission mode blocks the write, so pass --permission-mode accept-edits.

Skills

Skills follow the open Agent Skills format: a folder with a SKILL.md whose frontmatter has name and description. bwn finds them in .buildwithnexus/skills/, .claude/skills/, and .agents/skills/, in both the project and your home directory, so skills written for other agents work unchanged. The project's skills load only after you trust the folder. A project skill with the same name as a bundled skill or one of yours loads as /project:<name>. When your own settings set "project_skills_override": true, the project's skill takes the plain name instead. Flat name.md files still work. Only the name and description go into context. The body loads when you run /name or the model calls load_skill. Add more skill directories with "skill_dirs": ["~/my-skills"].

While the agent works

• You can keep typing. Messages queue and send automatically on the next turn.
• Esc interrupts the agent and keeps your draft in the composer.
• Ctrl+Q edits the next message in the queue, and Ctrl+X removes it.

Next: The TUI →