Quickstart
Get productive in under five minutes.
1. Point Ninja at a model
Any OpenAI-compatible chat endpoint works (llama.cpp, vLLM, LiteLLM, cloud APIs).
# Local (llama.cpp default port)
export OPENAI_BASE_URL="http://localhost:8080"
export OPENAI_MODEL="your-local-model"
# Cloud example
export OPENAI_BASE_URL="https://api.deepseek.com"
export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="deepseek-chat"Windows PowerShell
$env:OPENAI_BASE_URL="http://localhost:8080"
Default base URL if unset: http://localhost:8080.
2. Run in your project
cd your-project
ninjaOn first run Ninja writes an annotated config.example.json next to your config dir. Ninjaskills (builtin process skills) load from the binary embed — not from a seeded skills directory.
3. Optional hybrid routing
Use a strong model to plan and a fast local model to code:
export OPENAI_BASE_URL="https://api.deepseek.com"
export OPENAI_API_KEY="sk-planner"
export OPENAI_MODEL="deepseek-reasoner"
export NINJA_SUBAGENT_BASE_URL="http://localhost:8080"
export NINJA_SUBAGENT_MODEL="qwen3.6-35b-instruct"
# NINJA_SUBAGENT_API_KEY optional — falls back to OPENAI_API_KEY| Variable family | Role |
|---|---|
OPENAI_* |
Planner (orchestrator) |
NINJA_SUBAGENT_* |
Default for all subagents (coder, reviewer, final_review, researcher) |
subagent_roles.<role> in config |
Per-role override |
In the TUI, type /model to pick models for the session (optionally save to config). Type /exit (or /quit) to leave cleanly — same as Ctrl+D.
4. Give clear instructions
# Good
Add input validation to CreateUser in api/users.go.
Empty email/name → HTTP 400 JSON error.
# Bad
Make the code better.Ninja plans, may ask for tool approval, and edits under policy.
5. Common first commands
ninja doctor
ninja policy check "rm -rf build"
ninja session list
ninja -p "summarize README.md" --mode text