Metadata-Version: 2.4
Name: steerdev
Version: 0.5.5
Summary: Backend task runner for steerdev.com - orchestrates CLI coding agents with activity reporting
Project-URL: Homepage, https://github.com/pentoai/steerdev-agent
Project-URL: Repository, https://github.com/pentoai/steerdev-agent
Project-URL: Documentation, https://github.com/pentoai/steerdev-agent#readme
Author-email: Leonardo Piñeyro <leopiney@gmail.com>
License: MIT
Keywords: agent,ai,automation,cli,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Terminals
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: basedpyright>=1.21.0; extra == 'dev'
Requires-Dist: ipdb>=0.13.13; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# SteerDev Agent

Task runner for [steerdev.com](https://steerdev.com) — orchestrates AI coding agents via subprocess execution while streaming events to the SteerDev platform.

## What It Does

SteerDev Agent connects your AI coding agent (Claude Code, Codex, Aider) to the steerdev.com platform:

1. **Fetches tasks** from your SteerDev project
2. **Builds prompts** with project context, task details, and workflow instructions
3. **Launches the agent** as a subprocess with JSON streaming
4. **Streams events** back to the API for real-time monitoring
5. **Manages sessions** for tracking and resuming conversations

## Installation

```bash
# Install with uv (recommended)
uv tool install steerdev

# Or from source
git clone https://github.com/pentoai/steerdev.git
cd steerdev
uv tool install .
```

## Quick Start

### 1. Set Up Your Project

```bash
# Configure the agent for your project
steerdev setup --project-id YOUR_PROJECT_ID --api-key YOUR_API_KEY
```

### 2. Set Environment Variables

```bash
export STEERDEV_API_KEY="your-api-key"

# Ensure your CLI agent is logged in (e.g., `claude login` for Claude Code)
```

### 3. Run the Agent

```bash
# Run the next task in your project
steerdev run --project-id YOUR_PROJECT_ID

# Run a specific task
steerdev run --project-id YOUR_PROJECT_ID --task-id TASK_ID

# Resume an existing session
steerdev resume --session-id SESSION_ID --message "Continue working..."
```

## CLI Commands

### `steerdev run`

Run the agent against a project or specific task.

```bash
steerdev run --project-id PROJECT_ID
steerdev run --project-id PROJECT_ID --task-id TASK_ID
steerdev run -c agent.yaml --prompt "Fix the failing tests"
```

### `steerdev tasks`

Manage tasks from your SteerDev project.

```bash
steerdev tasks next          # Get the next task to work on
steerdev tasks list          # List all tasks
steerdev tasks get TASK_ID   # Get task details
steerdev tasks update TASK_ID --status in-progress
```

### `steerdev setup`

Configure your project for use with the agent.

```bash
steerdev setup --project-id YOUR_PROJECT_ID --api-key YOUR_API_KEY
```

### `steerdev config`

Manage YAML configuration files.

```bash
steerdev config init --output agent.yaml   # Generate config
steerdev config validate agent.yaml         # Validate config
steerdev config show agent.yaml             # Show config
```

## Configuration

### YAML Config File

```yaml
agent:
  model: null                # Model override
  max_turns: null            # Max agent turns per task
  timeout_seconds: 3600      # Max execution time
  workflow_id: null           # Workflow ID for multi-phase execution

api:
  api_endpoint: "https://steerdev.com/api/v1"
  api_key_env: STEERDEV_API_KEY
  project_id_env: STEERDEV_PROJECT_ID

executor:
  type: claude               # claude, codex, aider
  permission_mode: default
  allowed_tools: []
  disallowed_tools: []
  mcp_config: null

worktrees:
  enabled: false
```

### Environment Variables

| Variable | Description |
| --- | --- |
| `STEERDEV_API_KEY` | API key for steerdev.com |
| `STEERDEV_PROJECT_ID` | Default project ID |

> **Note:** CLI agents (Claude Code, Codex, etc.) must be logged in independently before running steerdev. No LLM API keys are needed here.

## Architecture

```
steerdev run
  │
  ├── Fetch task from steerdev.com API
  ├── Build prompt (project context + task + workflow)
  ├── Create session
  ├── Launch agent subprocess (Claude Code)
  │     └── Stream JSON events
  │           ├── Parse (assistant, tool_use, tool_result)
  │           └── Batch & send to steerdev.com API
  └── Complete session
```

### Key Modules

| Module | Purpose |
| --- | --- |
| `cli.py` | Typer CLI entry point |
| `runner.py` | Main orchestrator |
| `executor/` | Agent subprocess management |
| `api/` | SteerDev API clients |
| `prompt/` | Prompt building and templates |
| `workflow/` | Multi-phase workflow execution |
| `config/` | Configuration models and settings |
| `setup/` | Project setup utilities |

## Development

```bash
# Install dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Lint & format
uv run ruff check .
uv run ruff format .

# Type check
uv run basedpyright
```

## Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) package manager
- An AI coding agent CLI (e.g., `claude` for Claude Code)
- SteerDev API key

## License

MIT — see [LICENSE](LICENSE) for details.
