steerdev 1.0.26

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.

Platform link

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 .

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

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