buildwithnexus

Modes & Sessions

buildwithnexus runs in one of three modes and remembers every run as a session. Modes decide how much autonomy the agent has; sessions let you stop and pick up exactly where you left off. Pick a mode from a subcommand or switch inside the REPL.

Plan
Decompose & approve
Breaks the task into concrete steps you approve before any of them run.
Build
Agentic ReAct loop
Reasons and acts over a tool loop until the task is finished.
Brainstorm
Free-form chat
Conversation only — no tools, no file changes.

Plan Mode

Plan mode is for changes you want to see laid out before anything touches disk. buildwithnexus decomposes the task into an ordered list of concrete steps and shows it to you. Nothing runs until you approve. Once you do, it executes the steps — switching into the BUILD tool loop to carry each one out.

buildwithnexus plan "migrate the test suite to vitest"

Use it when the task is large or risky, when you want to vet the approach first, or when you'd rather review a plan than babysit each individual edit.

Build Mode

Build mode is the agentic core: a ReAct loop where the model alternates between reasoning and acting. Each turn it picks a tool, you see the call (and, for edits, an inline colored diff), the result feeds back into context, and the loop continues until the model calls finish. It's the default for buildwithnexus run.

buildwithnexus run "add a --verbose flag to the CLI"

The Tool Loop

read_file
Read a file's contents into context.
list_dir
List the entries of a directory.
write_file
Create or overwrite a file. Gated by permissions.
edit_file
Apply a targeted edit, shown as an inline diff. Gated.
run_command
Run a shell command. Gated by permissions.
finish
End the loop and return the result.

Reads are free to run; the mutating tools — write_file, edit_file, run_command — are gated by the active permission mode (ask / auto / readonly). Sensitive paths and catastrophic commands always prompt, even under auto, and file tools stay confined to the working directory.

Brainstorm Mode

Brainstorm mode is plain conversation with the model — no tools, no file access, nothing written. Use it to think through a design, draft an approach, or ask questions without any risk of side effects.

buildwithnexus brainstorm "how should I structure the plugin API?"

Subagents

A long or branching task can blow past a single context window. spawn_subagent delegates a self-contained sub-task to a fresh context window — the subagent works in isolation and reports a result back to the parent, keeping the main transcript focused.

spawn_subagent
Fresh context window
Hands a sub-task to a new agent context, then folds the result back into the parent run.
Optional
Git-worktree isolation
A subagent can run in its own git worktree, so its file changes never collide with the main checkout.

Sessions

Every run — whatever the mode — writes its full transcript to ~/.buildwithnexus/sessions. You can stop any time and resume later from the CLI or from inside the REPL.

continue
Resume the most recent session and keep going.
resume <id>
Restore a specific saved session by its id.
sessions
List saved transcripts in ~/.buildwithnexus/sessions.
/resume
Inside the REPL, pick a saved session to restore and continue.
buildwithnexus sessions          # list saved sessions
buildwithnexus continue          # resume the most recent
buildwithnexus resume <id>       # resume a specific session

Auto-Compaction

Long sessions don't hit a wall. As the transcript approaches the model's context window, buildwithnexus auto-compacts — condensing earlier turns so the conversation keeps going without losing the thread.

Context nears the window
Earlier turns are condensed automatically
The session continues — no manual reset, no lost progress