Configuration & Hooks

buildwithnexus keeps everything it needs in a single directory: ~/.buildwithnexus/. Your config, your API keys, your session history, your downloaded local models, and your hook settings all live there. This page covers that layout, how providers and models are chosen, the permission modes that gate mutating tools, and the Claude-Code-compatible lifecycle hooks.

The ~/.buildwithnexus/ Directory

Created on first run. No daemon, no database, no server — just files.

A project can also carry its own .buildwithnexus/settings.json checked into the repo. Project settings apply only after you trust the folder.

Providers & Models

buildwithnexus talks to models over two wire protocols and ships 8 built-in providers — five remote (you supply an API key) and three local (running on your own machine). Local providers are auto-detected at setup by probing the Ollama API and scanning the models/ folder for GGUF files.

Two wire protocols

Every provider speaks one of two protocols. Anthropic Messages is its own format; the OpenAI chat-completions format covers everything else — so one OpenAI-compatible client reaches OpenAI, OpenRouter, Groq, Hugging Face, Ollama, llama.cpp, and LM Studio.

The default provider and model live in config.json; the setup wizard writes them for you, and you can switch at any time from the REPL or per-run on the command line.

// ~/.buildwithnexus/config.json
{
  "provider": "anthropic",
  "model": "claude-sonnet-4-5",
  "permissionMode": "ask"
}

API keys are never sent to a non-HTTPS endpoint, and key-like tokens are redacted from any error surfaced to the screen.

Permission Modes

Reads run freely. The mutating tools — write_file, edit_file, run_command — are gated by the active permission mode. Set it in config.json, or switch it for a single run.

Some things always prompt, even under auto:

Hooks

buildwithnexus supports Claude-Code-compatible lifecycle hooks: shell commands that fire at specific points in a run. Configure them in settings.json — user-level at ~/.buildwithnexus/settings.json, project-level at .buildwithnexus/settings.json in the repo.

The six events

// ~/.buildwithnexus/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "edit_file|write_file",
        "hooks": [
          { "type": "command", "command": "cargo fmt" }
        ]
      }
    ]
  }
}

User vs. project settings

The per-folder trust model

Project hooks ship inside repositories, so they don't run until you explicitly trust the folder. Trusted folders are recorded in ~/.buildwithnexus/trusted.json. Until then, a cloned repo's hooks are inert — pulling someone else's project can't execute commands on your machine.

Project hooks can deny, never grant

A trusted project hook on PreToolUse can block a tool call, but it can never authorize one — the permission gate is the only thing that grants. A hook denies a call in one of two ways:

// PreToolUse hook output — block this tool call
{ "permissionDecision": "deny", "reason": "writes to generated/ are not allowed" }

Sensible defaults mean most people never touch config.json or settings.json — the setup wizard handles providers and models, ask keeps you in control, and hooks are entirely opt-in.