steerdev 0.4.27

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-agent

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

Quick Start

1. Set Up Your Project

# Configure the agent for your project
steerdev-agent 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-agent run --project-id YOUR_PROJECT_ID

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

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

CLI Commands

steerdev-agent run

Run the agent against a project or specific task.

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

steerdev-agent tasks

Manage tasks from your SteerDev project.

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

steerdev-agent setup

Configure your project for use with the agent.

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

steerdev-agent config

Manage YAML configuration files.

steerdev-agent config init --output agent.yaml   # Generate config
steerdev-agent config validate agent.yaml         # Validate config
steerdev-agent 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-agent. No LLM API keys are needed here.

Architecture

steerdev-agent 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.