config.json

Persist models, tools, and options without exporting env vars every session.

File locations

OS	Path
Linux	`~/.config/ninja/config.json`
macOS	`~/Library/Application Support/ninja/config.json`
Windows	`%APPDATA%\ninja\config.json`

On first run Ninja also writes **config.example.json** in the same directory (annotated template with REPLACE_* placeholders). It is not overwritten once present and never replaces your live config.json.

Setting precedence

Non-empty environment variables
**config.json**
Built-in defaults (planner base defaults to http://localhost:8080 if unset)

Minimal example

{
  "openai_base_url": "http://localhost:8080",
  "openai_api_key": "",
  "openai_model": "your-model-name"
}

Hybrid routing example

{
  "openai_base_url": "https://api.example.com/v1",
  "openai_api_key": "REPLACE_PLANNER_KEY",
  "openai_model": "planner-model",

  "ninja_subagent_base_url": "http://localhost:8080",
  "ninja_subagent_api_key": "sk-local",
  "ninja_subagent_model": "coder-model",

  "subagent_roles": {
    "reviewer": {
      "base_url": "https://api.example.com/v1",
      "api_key": "REPLACE_REVIEWER_KEY",
      "model": "review-model"
    }
  },

  "enabled_tools": {
    "bash": true,
    "web_search": true,
    "read_url": true,
    "deep_research": true
  },

  "plan_panel": [
    {
      "name": "risk-lens",
      "base_url": "https://api.example.com/v1",
      "api_key": "REPLACE_PANEL_KEY_1",
      "model": "strong-reasoner-model",
      "lens": "risk-first"
    },
    {
      "name": "simple-lens",
      "base_url": "https://api.example.com/v1",
      "api_key": "REPLACE_PANEL_KEY_2",
      "model": "another-strong-model",
      "lens": "simplicity-first"
    }
  ]
}

plan_panel is optional. Use it with the plan-debate skill (see Configure models). More knobs also appear in config.example.json after first run.

Common keys

Key	Purpose
`openai_base_url` / `openai_api_key` / `openai_model`	Planner (orchestrator)
`ninja_subagent_*`	Default for subagents
`subagent_roles`	Per-role overrides (`coder`, `reviewer`, `final_review`, …)
`plan_panel`	Models for multi-model planning (plan-debate skill)
`enabled_tools`	Turn built-in tools on/off
`cache`	Context management toggles (see example file)

Project-local files

Path	Purpose
`.ninja/mcp_config.json`	Project MCP servers
`.ninja/skills/`	Project skills
`.ninja/allowed_commands.json`	Project-scoped command trust