SteerDev Agent

Task runner for steerdev.com — orchestrates AI coding agents via subprocess execution while streaming events to the SteerDev platform.

Platform link

What It Does

SteerDev Agent connects your AI coding agent (Claude Code or pi; openai-codex is a stub) 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 .

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

# 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

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

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

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.

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.

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

steerdev tasks

Manage tasks from your SteerDev project.

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.

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.

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.

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

steerdev sessions

List and inspect agent execution sessions.

steerdev sessions list
steerdev sessions get SESSION_ID

steerdev runs

List and inspect agent execution runs.

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

steerdev activity

Self-report progress or query activity history.

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

steerdev context

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

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.

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

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:

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

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 (wired), pi (wired), openai-codex (stub)
  permission_mode: default
  allowed_tools: []
  disallowed_tools: []
  mcp_config: null

worktrees:
  enabled: false

Environment Variables

Note: Locally, CLI agents like Claude Code and pi can be logged in independently (claude login, or pi + /login) before running steerdev — no LLM API keys are strictly needed. In a sandbox, the bootstrap injects the per-provider credentials above; steerdev never fetches credentials itself.

Providers

Select the harness with --provider (or STEERDEV_PROVIDER). Defaults to claude:

steerdev run --provider claude --project-id YOUR_PROJECT_ID  # Claude Code
steerdev run --provider pi --project-id YOUR_PROJECT_ID       # pi.dev coding agent

claude (Claude Code) and pi (the pi.dev coding agent) are wired end-to-end. pi runs headless as pi --mode json "<prompt>" and streams its JSON events back to steerdev. openai-codex is a clearly-stubbed seam that fails fast with a "not yet supported" message, reserved for a future harness protocol.

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

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.