Use Cases & Walkthroughs

Five end-to-end walkthroughs of buildwithnexus on the command line — fixing a bug, building a small feature, running fully local with Ollama, driving it headless in CI, and resuming a previous session. Each one is a real terminal flow you can copy.

npm install -g buildwithnexus
cd my-project
buildwithnexus            # or: bwn

On first run a short setup wizard configures a model. Pick a remote provider with an API key, or let buildwithnexus auto-detect a local model already on your machine (it probes the Ollama API and scans your GGUF folder). Keys are written to ~/.buildwithnexus/.env.keys at mode 0600.

1. Fix a bug

Start the REPL and describe the bug. BUILD mode runs the agentic loop: it reads files, lists directories, runs your test command, and proposes an edit.

buildwithnexus

› Tests fail with "Invalid time value" in the orders module.
  Find the cause and fix it.

[build] list_dir  src/orders/
[build] read_file src/orders/format.ts
[build] run_command  npm test -- orders
        ✗ 1 failing — formatDueDate() throws on null dueAt

It localizes the bug and shows an inline colored diff. Mutating tools are gated, so nothing is written until you approve.

edit_file src/orders/format.ts

  function formatDueDate(order) {
-   return new Date(order.dueAt).toISOString()
+   if (!order.dueAt) return null
+   return new Date(order.dueAt).toISOString()
  }

Apply this edit? [y]es / [n]o / [a]lways
› y

[build] run_command  npm test -- orders
        ✓ all passing
[build] finish  Guarded the null case in formatDueDate; tests green.

2. Build a small feature

Use PLAN mode — run buildwithnexus plan directly, or let the interactive prompt suggest it for design-shaped requests. It decomposes the work into discrete steps you approve before any tool runs.

buildwithnexus plan

› Add a GET /healthz endpoint that returns { status: "ok" },
  wired into the router, with a unit test.

Plan
  1. Add healthz handler in src/routes/health.ts
  2. Register the route in src/router.ts
  3. Add a test in src/routes/health.test.ts
  4. Run the test suite

Approve plan? [y]es / [e]dit / [n]o
› y

Once approved, execution drops into the agentic loop and streams tokens as it goes. Edits are shown as inline diffs and gated the same way.

[plan 1/4] write_file src/routes/health.ts        ✓
[plan 2/4] edit_file  src/router.ts               ✓
[plan 3/4] write_file src/routes/health.test.ts   ✓
[plan 4/4] run_command npm test -- health         ✓ 1 passing
finish  /healthz added, registered, and covered by a passing test.

For a larger feature you can delegate an isolated piece with spawn_subagent — it runs the sub-task in a fresh context window, optionally inside its own git worktree, then reports back without polluting your main session.

3. Run fully local with Ollama

Pull a model and start Ollama, then launch buildwithnexus. The setup wizard probes the Ollama API and offers the model it finds — no key required.

ollama pull qwen2.5-coder
ollama serve

buildwithnexus

Detecting local models…
  ✓ Ollama        qwen2.5-coder      (http://localhost:11434)
  ✓ GGUF folder   2 models found

Use a local model? [y]es / [n]o
› y
  Selected: qwen2.5-coder via Ollama

From here the experience is identical — the same PLAN / BUILD / BRAINSTORM modes and the same tools — but every request stays on your machine.

All three local backends speak the OpenAI chat-completions protocol, the same one used for the remote OpenAI-compatible providers.

4. Drive it headless with --json in CI

Use the run subcommand for non-interactive execution. Add --json to get newline-delimited structured events you can pipe into jq or any log processor.

buildwithnexus run "update the CHANGELOG for the next release" --json

{"type":"tool_call","name":"read_file","input":{"path":"CHANGELOG.md"}}
{"type":"tool_result","name":"read_file","content":"# Changelog…","is_error":false}
{"type":"tool_call","name":"edit_file","input":{"path":"CHANGELOG.md"}}
{"type":"tool_result","name":"edit_file","content":"edited CHANGELOG.md","is_error":false}
{"type":"assistant","text":"Added the unreleased section to CHANGELOG.md."}
{"type":"finish","summary":"Added the unreleased section to CHANGELOG.md"}

In a non-interactive environment, set the permission level ahead of time so the run never blocks on a prompt — keep it readonly when you only want analysis. The level lives in ~/.buildwithnexus/config.json (written by init), so seed it once in CI:

# .github/workflows/triage.yml
- name: Summarize the diff
  run: |
    mkdir -p ~/.buildwithnexus
    cat > ~/.buildwithnexus/config.json <<'JSON'
    { "provider": "anthropic", "model": "claude-sonnet-4-6", "permission": "readonly" }
    JSON
    buildwithnexus run "summarize what this PR changes" --json > result.ndjson
    jq -r 'select(.type=="finish") | .summary' result.ndjson

The run form also accepts plan, brainstorm, continue, and resume, so you can script any mode the REPL offers.

5. Resume a previous session

List your saved sessions, then continue the most recent one or resume a specific id:

buildwithnexus sessions

ID        WHEN              MODE   SUMMARY
a1b2c3d4  2 hours ago       build  Added /healthz endpoint + test
9f8e7d6c  yesterday 18:40   plan   Refactor the orders module

buildwithnexus continue          # reopen the most recent session
buildwithnexus resume 9f8e7d6c   # reopen a specific session by id

Inside the REPL you can do the same with /resume. The full transcript is reloaded so the agent keeps your prior context — and because context auto-compacts as it nears the model's window, long-running sessions stay within budget without losing the thread.

Where to go next