steerdev 0.5.1

Backend task runner for steerdev.com - orchestrates CLI coding agents with activity reporting

SteerDev Agent

Task runner for 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

# 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

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

2. Set Environment Variables

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

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

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.

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.

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

steerdev config

Manage YAML configuration files.

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

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

# 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 package manager
• An AI coding agent CLI (e.g., claude for Claude Code)
• SteerDev API key

License

MIT — see LICENSE for details.