xninja 0.2.0

Claude Code-style CLI harness for the Subnet 66 ninja agent

xninja

xninja is a small PyPI-ready CLI package that runs the public unarbos/ninja agent like a local coding assistant.

It bundles the latest ninja agent.py snapshot at package build time and calls its validator-compatible contract:

solve(repo_path, issue, model, api_base, api_key)

Install

Prerequisites

• Python 3.11 or newer
• pip (bundled with Python)
• An OpenRouter API key

From PyPI (recommended)

pip install xninja

Verify the installation:

xninja --version

From source

Clone the repository and install in editable mode:

git clone https://github.com/unarbos/xninja.git
cd xninja
python -m pip install -e .

Verify the installation:

xninja --version

Configure

xninja config

This stores your OpenRouter API key and default model in the OS user config directory, such as ~/.config/xninja/config.json on Linux. The file is written with user-only permissions.

Environment variables override stored config:

OPENROUTER_API_KEY=...
XNINJA_MODEL=anthropic/claude-sonnet-4.6

Use

Open an interactive session in the current git repo:

xninja

Run a one-shot task:

xninja "fix the failing parser test"

Run explicitly:

xninja run --repo . --model anthropic/claude-sonnet-4.6 "add validation for empty input"

By default, xninja previews the returned patch and asks before applying it. Use --apply to request application after the run.

Agent Sources

Show bundled metadata:

xninja agent info

Cache and use a specific unarbos/ninja ref:

xninja agent update --ref cec561e45192042687c053237c1db503cd7d3ae0
xninja run --agent-ref cec561e45192042687c053237c1db503cd7d3ae0 "fix the issue"

Use your own compatible local agent.py:

xninja run --agent-path ./agent.py "fix the issue"
xninja --agent-path ~/agents/my_agent.py "fix the issue"

Custom agents must expose the same callable contract as the bundled agent:

def solve(repo_path, issue, model, api_base, api_key):
    return {"patch": "", "logs": "", "steps": 0, "cost": None, "success": True}

Models

xninja models

Recommended defaults are intentionally simple. You can pass any OpenRouter model id with --model.

Development

python -m pip install -e '.[dev]'
pytest
python -m build