Metadata-Version: 2.4
Name: steerdev
Version: 1.0.58
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: tenacity>=9.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.

[Platform link](https://platform.steerdev.com)

## 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 .
```

### Updating

The CLI automatically checks for new versions. When an update is available you'll see:

```
Update available: 0.5.5 → 0.5.6
Run uv tool install steerdev to upgrade
```

## Quick Start

### 1. Set Up Your Project

```bash
# Configure the agent for your project
# This installs lean task lifecycle guidance plus focused merge skills
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

# Run with git worktree isolation
steerdev run --project-id YOUR_PROJECT_ID --worktrees

# Run with a multi-phase workflow
steerdev run --project-id YOUR_PROJECT_ID --workflow-id WORKFLOW_ID

# Force single-task scheduling
steerdev run --project-id YOUR_PROJECT_ID --no-waves

# Enable canal merge flow selection for workflow phases
steerdev run --project-id YOUR_PROJECT_ID --workflow-id WORKFLOW_ID --canals

# 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.

Wave-aware scheduling is enabled by default. Use `--no-waves` to force single-task scheduling.
Use `--canals` to expose canal merge flow selection to workflow phases.

```bash
steerdev run --project-id PROJECT_ID
steerdev run --project-id PROJECT_ID --task-id TASK_ID
steerdev run --project-id PROJECT_ID --no-waves
steerdev run --project-id PROJECT_ID --workflow-id WORKFLOW_ID --canals
steerdev run --project-id PROJECT_ID --worktrees
steerdev run --project-id PROJECT_ID --workflow-id WORKFLOW_ID
steerdev run --project-id PROJECT_ID --agent-name my-dev-agent
steerdev run --project-id PROJECT_ID --max-tasks 5    # process multiple tasks
steerdev run --project-id PROJECT_ID --dry             # preview without executing
```

### `steerdev agent`

Run the agent in persistent mode — polls for commands from the dashboard/API and falls back to the task queue.

Wave-aware scheduling is enabled by default. Use `--no-waves` to force single-task scheduling.
Use `--canals` to expose canal merge flow selection to workflow phases.

```bash
steerdev agent --project-id PROJECT_ID --agent-name my-agent
steerdev agent --project-id PROJECT_ID --agent-name my-agent --no-waves
steerdev agent --project-id PROJECT_ID --agent-name my-agent --workflow-id WORKFLOW_ID --canals
steerdev agent --project-id PROJECT_ID --agent-name my-agent --poll-interval 10
```

### `steerdev resume`

Resume an existing session with a new message.

```bash
steerdev resume --session-id SESSION_ID --message "Continue working..."
```

### `steerdev tasks`

Manage tasks from your SteerDev project.

```bash
steerdev tasks next                              # Get the next task to work on
steerdev tasks next --no-waves                  # Force single-task scheduling
steerdev tasks list                              # List all tasks
steerdev tasks get TASK_ID                       # Get task details
steerdev tasks update TASK_ID --status in-progress
steerdev tasks create --title "..." --prompt "..."
```

### `steerdev specs`

Manage specification documents.

```bash
steerdev specs list                              # List specifications
steerdev specs get SPEC_ID                       # Get spec details
steerdev specs create --title "..."              # Create a new spec
steerdev specs update SPEC_ID --status approved  # Update a spec
```

### `steerdev setup`

Configure a project for use with the agent. Sets up `.claude/settings.json`, lean task lifecycle guidance in `CLAUDE.md`, focused merge skills, and `.env`.

```bash
steerdev setup --project-id YOUR_PROJECT_ID --api-key YOUR_API_KEY
steerdev setup --install-target user             # Install to ~/.claude/ instead of .claude/
steerdev setup --agent-name my-agent             # Set a custom agent name
```

### `steerdev sync`

Sync shared agent settings (system prompts, skills, MCP servers, env variables) from the platform.

```bash
steerdev sync --project-id PROJECT_ID
steerdev sync --project-id PROJECT_ID --install-target user
```

### `steerdev sessions`

List and inspect agent execution sessions.

```bash
steerdev sessions list
steerdev sessions get SESSION_ID
```

### `steerdev runs`

List and inspect agent execution runs.

```bash
steerdev runs list
steerdev runs get RUN_ID
steerdev runs active                             # List currently active runs
```

### `steerdev activity`

Self-report progress or query activity history.

```bash
steerdev activity report --message "Completed auth module"
steerdev activity query
```

### `steerdev context`

Manage project context (tech stack, patterns, structure).

```bash
steerdev context get
steerdev context refresh                         # Force refresh cached context
steerdev context search -p "pdf processing"      # Semantic code search
steerdev context search -p "how do we handle auth middleware"  # Natural-language query
```

### `steerdev git`

Git workflow commands with steerdev conventions.

```bash
steerdev git branch TASK_ID                      # Create a task branch
steerdev git pr                                  # Create a PR with conventions
steerdev git status                              # Show branch and task context
```

### `steerdev hooks`

Claude Code lifecycle hooks for activity reporting (used internally by the Claude Code integration).

```bash
steerdev hooks session-start
steerdev hooks session-end
steerdev hooks agent-stop
steerdev hooks subagent-stop
```

### Workflow Phase Prompt Variables

Workflow phases can select the merge workflow by referencing runtime prompt variables.

- `${merge_skill}`: `single-task-merge`, `wave-tasks-merge`, or `merge-into-canal`
- `${merge_mode}`: `single_task`, `wave`, or `canal`
- `${waves_enabled}`, `${canals_enabled}`, `${has_wave_context}`
- `${wave_number}`, `${total_waves}`, `${wave_description}`, `${wave_tasks_summary}`, `${completed_waves_summary}` when wave context is available

Workflow prompt templates use standard-library `string.Template` syntax: `$var` or `${var}`.

Example phase prompt snippet:

```text
Complete the merge phase for this task.

Use the `${merge_skill}` skill.
Current merge mode: `${merge_mode}`.
Wave context present: `${has_wave_context}`.
```

## 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 |
| `STEERDEV_AGENT_NAME` | Agent name for session tracking |

> **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 |
| `agent_loop.py` | Persistent agent mode |
| `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 |
| `git/` | Git workflow 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.
