I just wanted to build my coffee shop website easily using Bonsai models. So I built this.
n0x-cli is a fast, local-first terminal coding agent designed specifically to run on Bonsai models. It skips the cloud API keys and limits so you can just spin up a local model and get straight to building your projects. It's an autonomous ReAct agent that loops through thoughts, acts on your codebase, and gets the job done.
Repository: github.com/ixchio/n0x-cli
Because it should be easy to build apps locally:
- Local compute: Runs on
llama-serverwithprism-ml/Bonsaimodels. Fast as hell. - Smart Context: It doesn't blindly stuff your whole repo into the context window. It surgically picks relevant files, uses
.n0xignore, and tracks its own token budget. - Trust via
n0x undo: The #1 reason people hate agents is they destroy files.n0xautomatically backs up files to~/.n0x/backupsbefore any edit, write, or patch. Plus,--interactivemode lets you confirm every diff. - Killer workflow features: One-shot explanations (
n0x explain), git-aware commit generation (n0x commit), and interactive REPLs (n0x chat).
| Feature | What it actually does |
|---|---|
| Agent Loop | Think → Act (use a tool) → Observe → Repeat until DONE. |
| File Ops | Read, Write, Edit (fuzzy + AST-safe), Delete, Rename. |
| Terminal | Bash execution with a safety denylist (no fork bombs) + Docker sandbox. |
| Search | Superfast ripgrep + glob under the hood. |
| MCP | Plug in @modelcontextprotocol servers for GitHub, DBs, etc. |
| Tavily Web | SDK built-in for deep web searches when the agent gets stuck. |
n0x run "refactor the auth flow" # The main agent loop (max 20 steps)
n0x run "fix login" -i # Interactive mode: confirm every single diff before it saves
n0x commit # Reads staged files, writes a conventional commit, prompts to apply
n0x explain src/utils.ts # Fast, single-shot breakdown of what a file does
n0x fix "error text" # Auto-patch based on a stack trace
n0x chat # Interactive REPL session
n0x doctor # Pings your local LLM server and checks your environment
n0x map # Generates a tree-map of your repo structureBonsai models punch way above their weight. Here's what we recommend:
| Task | Model to use |
|---|---|
| Fast edits | prism-ml/Bonsai-1.7B-gguf:Bonsai-1.7B.gguf |
| Daily Driver (Default) | prism-ml/Bonsai-4B-gguf:Bonsai-4B.gguf |
| Complex Refactors | prism-ml/Bonsai-8B-gguf:Bonsai-8B.gguf |
| Apple Silicon (Macs) | prism-ml/Bonsai-8B-mlx-1bit |
Pro-tip: Run n0x models in your terminal for a full breakdown.
We recommend llama-server. Just let it run in the background.
llama-server -hf prism-ml/Bonsai-4B-gguf --hf-file Bonsai-4B.gguf(Runs on http://localhost:8080/v1)
npm install -g n0x-cliGo to any codebase you want to work on:
cd ~/my-project
n0x init # Builds symbol index, sets up .n0xignore
n0x doctor # Confirms LLM is reachable and models are loadedn0x run "analyze this project and list entry points"Your global config lives in ~/.n0x/config.toml. It looks something like this:
default_model = "bonsai-4b"
base_url = "http://localhost:8080/v1"
api_key = "none"
max_steps = 20
bash_timeout_ms = 120000
llm_timeout_ms = 120000
# Tavily (Keyless mode by default, or bring your own API key)
tavily_enabled = true
tavily_search_depth = "advanced"Check out the docs/ folder for deeper dives:
- workflow.md: How to actually use n0x effectively in your daily dev loop.
- development.md: How to hack on n0x itself.
- changelog.md: What's new.
- Confined Paths: Tools cannot escape the workspace via
../. - Bash Denylist: Hardcoded rules block
rm -rf /, fork bombs, etc. - Docker Sandbox: Optional containerized execution (
sandbox_docker = true). - Secret Redaction: API keys are scrubbed from the agent logs.
- Backups: Every file edit automatically backs up the old version to
~/.n0x/backups/.
License: MIT