Skip to content

Reorient Fireteam from library-first to CLI-first #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
edgarpavlovsky merged 1 commit into from
Jan 22, 2026
Merged

Reorient Fireteam from library-first to CLI-first #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
265 changes: 117 additions & 148 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,208 +1,177 @@
# Fireteam

Adaptive task execution using Claude Code CLI with complexity-based routing and loop-until-complete behavior.

## Overview

Fireteam estimates task complexity and routes to the appropriate execution strategy:

| Complexity | Mode | Behavior |
|------------|------|----------|
| TRIVIAL | SINGLE_TURN | Direct execution, single pass |
| SIMPLE | SINGLE_TURN | Direct execution, single pass |
| MODERATE | MODERATE | Execute -> review loop until >95% complete |
| COMPLEX | FULL | Plan once, then execute -> 3 parallel reviews loop until 2/3 say >95% |
Autonomous task execution with Claude. Give it a goal, let it run until complete.

## Installation

```bash
uv add fireteam
# Install as a CLI tool
pipx install fireteam
# or
uv tool install fireteam
```

Requires Python 3.12+ and Claude Code CLI installed.
Requires Python 3.12+ and [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed.

## Usage
## Quick Start

### Basic Usage
1. Create a `PROMPT.md` file in your project:

```python
from fireteam import execute
```markdown
# Task

result = await execute(
project_dir="/path/to/project",
goal="Fix the bug in auth.py",
context="Error logs: NullPointerException at line 42",
)
Fix the authentication bug where users can't log in after password reset.

if result.success:
print(f"Completed in {result.iterations} iterations")
print(f"Completion: {result.completion_percentage}%")
else:
print(f"Failed: {result.error}")
## Context

@src/auth.py
@tests/test_auth.py
```

### Specify Execution Mode
2. Run Fireteam:

```python
from fireteam import execute, ExecutionMode
```bash
# Start a background session (tmux)
fireteam start

# Force full mode with planning and parallel reviews
# Loops infinitely until complete (default)
result = await execute(
project_dir="/path/to/project",
goal="Refactor the authentication module",
mode=ExecutionMode.FULL,
)
# Or run in foreground
fireteam run
```

# Or limit iterations if needed
result = await execute(
project_dir="/path/to/project",
goal="Refactor the authentication module",
mode=ExecutionMode.FULL,
max_iterations=10, # Stop after 10 iterations if not complete
)
3. Monitor progress:

```bash
# List running sessions
fireteam list

# Attach to watch live
fireteam attach fireteam-myproject

# View logs
fireteam logs fireteam-myproject
```

### Complexity Estimation
## How It Works

```python
from fireteam import estimate_complexity, ComplexityLevel
Fireteam estimates task complexity and routes to the appropriate execution strategy:

# Quick estimation (no codebase access)
complexity = await estimate_complexity(
goal="Add logging to the auth module",
context="Existing logging in other modules uses Python logging",
)
| Complexity | Mode | Behavior |
|------------|------|----------|
| TRIVIAL | SINGLE_TURN | Direct execution, single pass |
| SIMPLE | SINGLE_TURN | Direct execution, single pass |
| MODERATE | MODERATE | Execute → review loop until ≥95% complete |
| COMPLEX | FULL | Plan once, then execute → 3 parallel reviews until 2/3 say ≥95% |

# Accurate estimation with codebase exploration
# Claude uses Glob, Grep, Read to understand the project
complexity = await estimate_complexity(
goal="Refactor the authentication system",
project_dir="/path/to/project",
)
It loops until the task is complete—no babysitting required.

print(f"Estimated complexity: {complexity}")
# ComplexityLevel.MODERATE -> routes to MODERATE mode
```
## CLI Reference

## Execution Modes
### `fireteam start`

### SINGLE_TURN
For trivial and simple tasks. Single CLI call, no review loop.
Start a background session in tmux:

### MODERATE
For moderate tasks requiring validation:
```
while not complete:
execute()
completion = review()
if completion >= 95%:
complete = True
```bash
fireteam start # Use PROMPT.md in current directory
fireteam start -p /path/to/project # Specify project directory
fireteam start -f task.md # Use specific goal file
fireteam start -g "Fix the bug" # Pass goal as string
fireteam start -m full # Force execution mode
fireteam start --max-iterations 10 # Limit iterations
```
Loops **indefinitely** until a single reviewer says >95% complete. Set `max_iterations` to limit.

### FULL
For complex tasks requiring planning and consensus:
```
plan() # Once at start
while not complete:
execute()
reviews = run_3_parallel_reviewers()
if 2 of 3 say >= 95%:
complete = True
### `fireteam run`

Run in foreground (blocking):

```bash
fireteam run # Use PROMPT.md in current directory
fireteam run -p /path/to/project # Specify project directory
```
Plans once, then loops **indefinitely** until majority (2/3) consensus. Set `max_iterations` to limit.

## API Reference
### `fireteam list`

### `execute()`
List all running Fireteam sessions.

```python
async def execute(
project_dir: str | Path,
goal: str,
context: str = "",
mode: ExecutionMode | None = None, # Auto-detect if None
max_iterations: int | None = None, # None = infinite (default)
) -> ExecutionResult
```
### `fireteam attach <session>`

### `ExecutionResult`
Attach to a running session to watch progress. Detach with `Ctrl+B D`.

```python
@dataclass
class ExecutionResult:
success: bool
mode: ExecutionMode
output: str | None = None
error: str | None = None
completion_percentage: int = 0
iterations: int = 0
metadata: dict = field(default_factory=dict)
### `fireteam logs <session>`

View session logs:

```bash
fireteam logs fireteam-myproject # Last 50 lines
fireteam logs fireteam-myproject -n 200 # Last 200 lines
```

### `estimate_complexity()`
### `fireteam kill <session>`

```python
async def estimate_complexity(
goal: str,
context: str = "",
project_dir: str | Path | None = None, # Enables codebase exploration
) -> ComplexityLevel
Terminate a running session.

## PROMPT.md Format

Fireteam auto-detects `PROMPT.md` (or `fireteam.prompt.md`, `prompt.md`) in your project directory. Use `@` syntax to include files:

```markdown
# Task

Refactor the authentication system to use JWT tokens.

## Current Implementation

@src/auth/
@src/middleware/auth.py

## Requirements

- Replace session-based auth with JWT
- Add refresh token support
- Update all tests

## Additional Context

@docs/auth-spec.md
```

Include patterns:
- `@path/to/file.py` - Single file
- `@path/to/directory/` - All files in directory
- `@src/**/*.py` - Glob pattern

## Configuration

Environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `FIRETEAM_MAX_ITERATIONS` | (none) | Max loop iterations. Unset = infinite. |
| `FIRETEAM_MAX_ITERATIONS` | unlimited | Max loop iterations |
| `FIRETEAM_LOG_LEVEL` | INFO | Logging verbosity |

## Project Structure
## Library Usage

```
fireteam/
├── .claude-plugin/
│ └── plugin.json # Claude Code plugin manifest
├── commands/
│ └── fireteam.md # /fireteam command definition
├── hooks/
│ └── hooks.json # Claude Code hooks configuration
├── src/
│ ├── __init__.py # Public API exports
│ ├── api.py # Core execute() function
│ ├── models.py # Data models (ExecutionMode, ExecutionResult, etc.)
│ ├── loops.py # Loop implementations (moderate_loop, full_loop)
│ ├── claude_cli.py # Claude Code CLI wrapper
│ ├── complexity.py # Complexity estimation
│ ├── circuit_breaker.py # Stuck loop detection
│ ├── rate_limiter.py # API call budget management
│ ├── runner.py # tmux-based autonomous execution
│ ├── prompt.py # PROMPT.md parsing with file includes
│ ├── config.py # Configuration
│ ├── claude_hooks/ # Claude Code hook handlers
│ └── prompts/
│ ├── __init__.py # Prompt loader
│ ├── builder.py # Prompt building with feedback injection
│ ├── executor.md # Executor agent prompt
│ ├── reviewer.md # Reviewer agent prompt
│ ├── planner.md # Planner agent prompt
│ └── complexity.md # Complexity estimation prompt
├── tests/
└── pyproject.toml
Fireteam can also be used as a Python library:

```python
from fireteam import execute

result = await execute(
project_dir="/path/to/project",
goal="Fix the authentication bug",
)

if result.success:
print(f"Completed in {result.iterations} iterations")
```

See [docs/](./docs/) for full API documentation.

## Development

```bash
# Clone and install dev dependencies
git clone https://github.com/darkresearch/fireteam
cd fireteam
uv sync --extra dev

# Run tests
uv run pytest tests/ -v
```

Expand Down
25 changes: 12 additions & 13 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,31 @@
# Fireteam Documentation

Fireteam is a Python library for adaptive task execution using Claude. It automatically estimates task complexity and selects the appropriate execution strategy.
Fireteam is a CLI tool for autonomous task execution using Claude. Give it a goal, let it run until complete.

## Contents

- [Introduction](./introduction.md) - Overview and key concepts
- [Quickstart](./quickstart.md) - Get started in 5 minutes
- [CLI Reference](./cli-runner.md) - Command-line interface
- [Concepts](./concepts/) - Deep dives into core concepts
- [Complexity Estimation](./concepts/complexity.md)
- [Execution Modes](./concepts/execution-modes.md)
- [API Reference](./api/) - Full API documentation
- [API Reference](./api/) - Python library documentation
- [execute()](./api/execute.md)
- [estimate_complexity()](./api/estimate-complexity.md)
- [Types](./api/types.md)
- [CLI Runner](./cli-runner.md) - tmux-based autonomous execution

## Quick Example

```python
from fireteam import execute
```bash
# Create a PROMPT.md with your task
fireteam start
```

result = await execute(
project_dir="/path/to/project",
goal="Fix the authentication bug",
)
Or run in foreground:

if result.success:
print(f"Completed: {result.completion_percentage}%")
```bash
fireteam run
```

## Execution Modes
Expand All @@ -35,5 +34,5 @@ if result.success:
|------------|------|----------|
| TRIVIAL | SINGLE_TURN | Direct execution, single pass |
| SIMPLE | SINGLE_TURN | Direct execution, single pass |
| MODERATE | MODERATE | Execute → review loop until >95% complete |
| COMPLEX | FULL | Plan once, then execute → 3 parallel reviews until 2/3 say >95% |
| MODERATE | MODERATE | Execute → review loop until ≥95% complete |
| COMPLEX | FULL | Plan once, then execute → 3 parallel reviews until 2/3 say ≥95% |
Loading