katana-cli 0.2.0

Claude Code-style CLI harness for the ninja subnet agent

katana

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

Subnet 66 harnesses are now multi-file bundles: an agent.py entrypoint plus a stdlib-only agent/ package (up to 32 *.py files), with tau_agent_files.json listing every file. katana bundles the latest such snapshot at build time, loads it exactly the way the validator does (the bundle root goes on sys.path so the entrypoint's from agent.* import ... resolves), and calls its validator-compatible contract:

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

Single-file agents (just agent.py) remain fully supported.

Install

Prerequisites

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

From PyPI (recommended)

pip install katana-cli

Verify the installation:

katana --version

From source

Clone the repository and install in editable mode:

git clone https://github.com/ninja-subnet/katana-cli.git
cd katana-cli
python -m pip install -e .

Verify the installation:

katana --version

Configure

katana config

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

Environment variables override stored config:

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

Use

Open an interactive session in the current git repo:

katana

Run a one-shot task:

katana "fix the failing parser test"

Run explicitly:

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

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

Agent Sources

Show bundled metadata:

katana agent info

Cache and use a specific ninja-subnet/ninja ref. The whole bundle (every file in tau_agent_files.json) is fetched, not just agent.py:

katana agent update --ref 486999c820ff92184deea0d2fc6723880be3e84e
katana run --agent-ref 486999c820ff92184deea0d2fc6723880be3e84e "fix the issue"

Use your own compatible local agent. --agent-path accepts either a single agent.py or a bundle directory containing agent.py (and, optionally, an agent/ package and a tau_agent_files.json manifest):

katana run --agent-path ./agent.py "fix the issue"
katana run --agent-path ./my_bundle "fix the issue"
katana --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}

For a multi-file bundle, agent.py is the entrypoint and may import its supporting modules (from agent.foo import bar); list every file, including agent.py, in tau_agent_files.json.

Models

katana 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