Metadata-Version: 2.4
Name: squadron-ai
Version: 0.2.7
Summary: Multi-agent squadron framework
Project-URL: Repository, https://github.com/ecorkran/squadron
Project-URL: Documentation, https://github.com/ecorkran/squadron/blob/main/README.md
Project-URL: Issues, https://github.com/ecorkran/squadron/issues
License: MIT License
        
        Copyright (c) 2026 Erik Corkran
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: anthropic>=0.40.0
Requires-Dist: claude-agent-sdk>=0.1.38
Requires-Dist: fastapi>=0.115.0
Requires-Dist: google-adk>=0.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer[all]>=0.12.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: dev
Requires-Dist: pyright>=1.1.390; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.7.0; extra == 'dev'
Description-Content-Type: text/markdown

# Squadron

Repeatable, template-driven code reviews powered by Claude — from the terminal.

Point `sq` at a diff, an architecture doc, or a task plan and get back a structured verdict with specific findings. No more freeform "hey Claude, review this" — each review runs against a purpose-built prompt template that tells the agent exactly what to evaluate and how to report what it finds.

```bash
sq review slice 120 -v
```
![Review output from current squadron branch](assets/review-image.png)

## Why this exists

Code review with LLMs is powerful but inconsistent. The same prompt gets different levels of scrutiny depending on how you phrase it, what context you include, and whether you remembered to mention your project's conventions.

Squadron makes reviews **repeatable**. A review template defines the system prompt, the tools the agent can use, and the inputs it expects. Run the same template on Monday and Friday and you get structurally consistent output — a verdict (PASS, CONCERNS, or FAIL) and a list of findings with severity levels.

Three built-in templates cover the most common review patterns:

| Template | What it reviews |
|----------|----------------|
| `slice` | A design document against an architecture reference |
| `tasks` | A task breakdown against its parent slice design |
| `code` | Source code, optionally scoped to a diff or glob |

The template system is extensible — each template is a YAML file, and adding new review types means writing a new YAML definition and optionally a prompt builder function. See [docs/TEMPLATES.md](docs/TEMPLATES.md) for details.

## Install

### Global install (recommended)

```bash
# Using pipx (recommended)
pipx install squadron-ai

# Or using uv
uv tool install squadron-ai
```

After install, `sq` is available on PATH:

```bash
sq --version
sq install-commands   # Install Claude Code slash commands
```

### Development install

```bash
git clone https://github.com/manta/squadron.git
cd squadron
uv sync --dev
```

## Quickstart

### 1. Configure credentials

Squadron uses the Claude Agent SDK, which supports two authentication methods:

**Claude Max subscription** (recommended): If you're already signed into Claude Code, you're set — the SDK uses your existing session. No API key needed.
```bash
# Verify you're authenticated
claude --version
```

**API key**: Alternatively, set an Anthropic API key:
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```

### 2. Review a design before writing code

Everyone reviews code. Almost nobody reviews the spec before writing the code. Start there:

```bash
# Does this slice design align with the architecture?
sq review slice 120 -v
```

The CLI resolves file paths automatically when you pass a slice number (requires [Context Forge](https://github.com/context-forge/context-forge)). Or pass paths directly:

```bash
sq review slice design.md --against architecture.md -v
```

You should see Rich-formatted output with a verdict and findings within about 30 seconds.

### 3. Review the task breakdown, then the code

```bash
# Does this task plan cover everything in the design?
sq review tasks 118 -v

# Review code changes
sq review code --diff main -v
```

## Using different models

Use `--model` with a built-in alias to run reviews through any supported provider:

```bash
# Claude (default — uses SDK)
sq review slice 120 -v

# OpenAI
sq review code --diff main --model gpt54-nano -v

# Google Gemini
sq review slice 120 --model flash3 -v

# OpenRouter
sq review tasks 118 --model kimi25 -v
```

Non-SDK models automatically get file contents and diffs injected into the prompt, so they can review actual code without tool access.

Run `sq models` to see all available aliases:

```
$ sq models
┌────────────┬────────────┬────────────────────────────────────────┬────────┐
│ Alias      │ Profile    │ Model ID                               │ Source │
├────────────┼────────────┼────────────────────────────────────────┼────────┤
│ codex      │ openai     │ gpt-5.3-codex                          │        │
│ flash3     │ gemini     │ gemini-3-flash-preview                 │        │
│ gemini     │ gemini     │ gemini-3.1-pro-preview-customtools     │        │
│ glm5       │ openrouter │ z-ai/glm-5                             │        │
│ gpt54      │ openai     │ gpt-5.4                                │        │
│ gpt54-mini │ openai     │ gpt-5.4-mini                           │        │
│ gpt54-nano │ openai     │ gpt-5.4-nano                           │        │
│ haiku      │ sdk        │ claude-haiku-4-5-20251001              │        │
│ kimi25     │ openrouter │ moonshotai/kimi-k2.5                   │        │
│ minimax    │ openrouter │ minimax/minimax-m2.7                   │        │
│ opus       │ sdk        │ claude-opus-4-6                        │        │
│ sonnet     │ sdk        │ claude-sonnet-4-6                      │        │
└────────────┴────────────┴────────────────────────────────────────┴────────┘
```

Add your own aliases in `~/.config/squadron/models.toml`:

```toml
[aliases]
deepseek = { profile = "openrouter", model = "deepseek/deepseek-r2" }
```

## Reviews in depth

### Scoping code reviews

Code reviews can be scoped by diff, file pattern, or both:

```bash
# Everything in the project
sq review code

# Only changes since main
sq review code --diff main

# Only Python files
sq review code --files "src/**/*.py"

# Changes to Python files since main
sq review code --diff main --files "src/**/*.py"
```

### Adding project-specific rules

Point reviews at a rules file to include project conventions in the agent's system prompt:

```bash
sq review code --diff main --rules ./rules/python.md
```

Your project's `CLAUDE.md` is loaded automatically via the SDK's `setting_sources` mechanism — the `--rules` flag is for additional guidance on top of that.

### Verbosity

Default output is compact — just the verdict and finding headings. Turn up verbosity when you want details:

| Flag | Shows |
|------|-------|
| *(default)* | Verdict + finding headings |
| `-v` | Above + full finding descriptions |
| `-vv` | Above + raw agent tool usage |

### Output formats

```bash
# Rich terminal output (default)
sq review code --diff main

# JSON to stdout (for piping / scripting)
sq review code --diff main --output json

# JSON to file
sq review code --diff main --output file --output-path result.json
```

## Configuration

Avoid repeating flags with persistent config. Two levels with clear precedence:

```bash
# Set your default working directory (user-level)
sq config set cwd ~/projects/myapp

# Set project-specific rules (project-level)
sq config set default_rules ./rules/python.md --project

# Check where a value is coming from
sq config get cwd

# See everything
sq config list
```

**Precedence** (highest wins): CLI flag → project config (`.squadron.toml`) → user config (`~/.config/squadron/config.toml`) → built-in default.

Available keys: `cwd`, `verbosity`, `default_rules`. See [docs/COMMANDS.md](docs/COMMANDS.md) for full details.

## Agent management

Squadron also exposes lower-level agent lifecycle commands. These are the building blocks for the review system and are available for direct use:

```bash
sq spawn --name my-agent
sq task my-agent "Analyze the error handling in src/core/"
sq list
sq shutdown my-agent
```

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | Success (PASS or CONCERNS verdict) |
| 1 | Error (invalid arguments, missing files, runtime error) |
| 2 | Review verdict is FAIL |

CONCERNS returns exit code 0 — it's informational, not a failure. This makes `sq` usable in CI pipelines where you want to gate on FAIL but not on warnings.

## Documentation

- **[docs/COMMANDS.md](docs/COMMANDS.md)** — Full command reference with all options and arguments
- **[docs/TEMPLATES.md](docs/TEMPLATES.md)** — How review templates work and how to create new ones

## Development

```bash
uv sync                # Install with dev dependencies
uv run pytest          # Tests
uv run pyright         # Type checking
uv run ruff check      # Linting
uv run ruff format     # Formatting
```

## License

MIT
