Steroids

Spec-driven, autonomous software development — with a built-in coder/reviewer loop.

Steroids is an AI-powered task orchestration system that automates software development through a strict implement → review → fix workflow. You define work in markdown specification files, group them into sections (features/phases), and Steroids runs the loop until tasks are done — or a dispute is raised.

A developer command center for managing multiple software projects with confidence.

Why Steroids

Most AI coding tools optimize for speed. Steroids optimizes for repeatable delivery:

Specs are the source of truth — not chat vibes.
Coder and reviewer are separated by design.
Nothing progresses without review approval.
Endless loops are prevented via coordinator intervention and dispute escalation.
Built for hands-off runs — overnight or while you focus elsewhere.

Steroids is for power developers who refuse to let their projects become unmaintainable slop.

Who It's For

Steroids is for software teams and solo developers who want to delegate routine development work to AI while maintaining quality control.

It's especially useful for:

Breaking down large projects into small, spec-driven tasks that AI can execute reliably
Enforcing consistent code review standards through an automated reviewer
Running development work in the background while you focus on higher-level decisions

The coder/reviewer separation ensures work is checked before being accepted, and the dispute mechanism escalates genuinely hard problems to humans rather than spinning endlessly.

How It Works

Steroids runs an autonomous loop per task:

You write specs in markdown files (tasks grouped into sections/phases).
A coder AI implements the task strictly according to the spec.
A reviewer AI evaluates: does it match the spec? Do builds/tests pass? Is the code secure?
If rejected, feedback is appended and the task goes back to the coder.
If approved, Steroids commits, pushes, and moves to the next task.
A coordinator AI intervenes at rejection thresholds (2, 5, 9) to break deadlocks.
After 15 rejections, Steroids raises a dispute (human attention required).

pending → in_progress → review → completed
              ↑           │
              │           ↓ (rejected)
              └───────────┘
                    │
                    ↓ (15 rejections)
                disputed/failed

External Setup: Some tasks require human action (Cloud SQL, account creation, etc.). When the spec says SKIP or MANUAL, the coder can mark it as skipped (fully external) or partial (some coded, rest external). The runner moves on, and you'll see what needs manual action in steroids llm --context.

Feedback Tasks: Both coder and reviewer can create feedback tasks for advisory items (pre-existing concerns, minor disputes, things needing human review). These go to a special skipped section called "Needs User Input" and never block the pipeline.

Key Features

Markdown specs as the contract (task definitions, acceptance criteria, constraints)
Sections/phases to organize features with priorities and dependencies
Coder/Reviewer loop with strict approval gating
Coordinator intervention at rejection thresholds to break deadlocks
Dispute escalation after 15 rejections to avoid infinite churn
Security review built into the reviewer (injection, shell safety, secrets, permissions)
File anchoring — pin tasks to specific file:line locations with auto-captured commit SHA
Feedback tasks — advisory items in a skipped section for human review
Multi-provider support — Claude, Codex (OpenAI), Gemini
CLI-first workflow for power users and automation
Background runner daemon to process tasks without babysitting
Bug intake pipeline for polling external reports, triaging them, and driving triage/reproduction/fix work
Event hooks — trigger scripts/webhooks on task completion, project events
Multi-project support with global project registry
Web dashboard for monitoring progress across projects
Shell completion for bash, zsh, and fish
Backup & restore for Steroids data
Health checks with weighted scoring for project fitness
(Planned) Mac menu bar companion for real-time status at a glance

Project Structure

A typical repo using Steroids:

my-project/
├── .steroids/
│   ├── steroids.db        # Task state, sections, audit logs
│   └── config.yaml        # Project configuration
├── specs/
│   ├── auth.md            # Specification files
│   ├── billing.md
│   └── dashboard.md
├── AGENTS.md              # Guidelines for AI agents
└── src/                   # Your code

Specs are stable, state is generated. The .steroids/ directory contains the SQLite database tracking all task state.

Quickstart

1. Install

# Option A: Install from npm
npm install -g steroids-cli

# Option B: Install from source
git clone https://github.com/UnlikeOtherAI/steroids-cli.git
cd steroids-cli
npm install && npm run build && npm link

2. Initialize in a project

cd ~/Projects/my-app
steroids init

This creates .steroids/ with the database and default config.

3. Create sections and tasks

# Add a section (feature/phase)
steroids sections add "Phase 1: User Authentication"

# Add a section targeting a feature branch (auto-creates branch if missing)
steroids sections add "Auth System" --branch feature/auth

# Add a section with auto-PR creation when all tasks complete
steroids sections add "Auth System" --branch feature/auth --auto-pr

# Add tasks with specs
steroids tasks add "Implement login endpoint" \
  --section <section-id> \
  --source specs/auth.md

# Anchor a task to a specific file and line
steroids tasks add "Fix null check in utils" \
  --section <section-id> \
  --source specs/fix.md \
  --file src/utils.ts --line 42

# Create a feedback task for human review
steroids tasks feedback "Should we use Redis or in-memory cache?"

4. Run the loop

# Interactive loop (foreground)
steroids loop

# Or start background daemon
steroids runners start --detach

Steroids processes tasks in order, looping coder/reviewer until completion or dispute.

Web Dashboard

Steroids ships with a full web dashboard for monitoring tasks, runners, and project health.

On first run, steroids web clones the dashboard repository to ~/.steroids/webui/ and installs everything automatically. On subsequent runs, it pulls the latest version before launching — so you're always up to date.

# Launch the dashboard (first run clones the repo, subsequent runs auto-update)
steroids web

That's it. Open your browser at:

Web UI: http://localhost:3500
API: http://localhost:3501

Managing the Dashboard

Command	Description
`steroids web`	Launch the dashboard (auto-clones on first run, auto-updates on every run)
`steroids web stop`	Stop the dashboard
`steroids web status`	Check if the dashboard is running

What You Get

Multi-project view — See all registered projects at a glance
Task queues — Pending, in-progress, review, completed
Runner status — Active daemons with heartbeat monitoring
Audit trails — Full history of every task state change
Configuration — Edit project settings from the browser
Model Usage analytics — Per-model token totals, Ollama timing throughput (tok/s), and live VRAM/auto-unload runtime status

CLI Commands

Core Commands

Command	Description
`steroids init`	Initialize Steroids in current directory
`steroids llm`	Quick reference for LLM agents (project setup, commands, task flow)
`steroids llm --context`	Include current project context (active tasks, runners)
`steroids about`	Alias for `steroids llm`
`steroids loop`	Run the coder/reviewer loop interactively
`steroids loop --once`	Run one iteration only

Task Management

Command	Description
`steroids tasks stats`	Show task counts by status
`steroids tasks list`	List pending tasks
`steroids tasks list --status all`	List all tasks with status
`steroids tasks list --status active`	Show in_progress + review tasks
`steroids tasks show <id>`	Show task details with invocation logs
`steroids tasks add <title> --section <id> --source <file>`	Add a new task
`steroids tasks add <title> ... --file <path> --line <n>`	Add task anchored to a committed file
`steroids tasks feedback <title>`	Add feedback task (skipped section, no --section/--source needed)
`steroids tasks update <id> --status review`	Submit task for review
`steroids tasks approve <id> --model <model>`	Approve a task
`steroids tasks reject <id> --model <model> --notes "..."`	Reject with feedback
`steroids tasks skip <id> --notes "..."`	Skip external setup task
`steroids tasks skip <id> --partial --notes "..."`	Partial skip (coded some, rest external)
`steroids tasks audit <id>`	View task audit trail

Section Management

Command	Description
`steroids sections list`	List all sections
`steroids sections add <name>`	Create a new section
`steroids sections add <name> --branch <branch>`	Create section targeting a git branch
`steroids sections add <name> --branch <branch> --auto-pr`	Create section with auto-PR on completion
`steroids sections update <id> --branch <branch>`	Set or change target branch
`steroids sections update <id> --auto-pr`	Enable auto-PR for an existing section
`steroids sections update <id> --no-auto-pr`	Disable auto-PR
`steroids sections reset-pr <id>`	Clear PR number to re-trigger auto-PR
`steroids sections skip <id>`	Exclude section from runner
`steroids sections unskip <id>`	Include section in runner
`steroids sections priority <id> <value>`	Set section priority (0-100 or high/medium/low)
`steroids sections depends-on <id> <dep-id>`	Add section dependency
`steroids sections no-depends-on <id> <dep-id>`	Remove section dependency
`steroids sections graph`	Show dependency graph (ASCII, `--mermaid`, or `--output png`)

Runner Management

Command	Description
`steroids runners list`	List active runners
`steroids runners start`	Start runner in foreground
`steroids runners start --detach`	Start runner in background
`steroids runners start --section <name>`	Focus on a specific section
`steroids runners stop --all`	Stop all runners
`steroids runners status`	Current runner state
`steroids runners logs [pid]`	View daemon output (`--tail`, `--follow`)
`steroids runners wakeup`	Check and start runners for projects with pending work
`steroids runners cron install`	Install cron job for auto-wakeup
`steroids runners cron uninstall`	Remove cron job

Dispute Management

Command	Description
`steroids dispute list`	List open disputes
`steroids dispute show <id>`	Show dispute details
`steroids dispute create <task-id> --reason "..." --type <type>`	Create a dispute (types: major, minor, coder, reviewer)
`steroids dispute resolve <id> --decision <coder\|reviewer\|custom>`	Resolve a dispute
`steroids dispute log <task-id> --notes "..."`	Log minor disagreement without blocking

AI Providers

Command	Description
`steroids ai providers`	List detected AI providers
`steroids ai models <provider>`	List available models for a provider
`steroids ai test`	Test AI configuration (coder/reviewer connectivity)
`steroids ai setup`	Interactive provider setup

Project Registry

Command	Description
`steroids projects list`	List registered projects
`steroids projects add <path>`	Register a project
`steroids projects remove <path>`	Unregister a project
`steroids projects prune`	Remove stale project entries

Configuration

Command	Description
`steroids config show [key]`	Display configuration (supports nested paths like `quality.tests`)
`steroids config set <key> <value>`	Set configuration value (supports nested paths)
`steroids config init`	Initialize config with defaults
`steroids config validate`	Validate configuration syntax
`steroids config edit`	Open config in $EDITOR

Maintenance & Utilities

Command	Description
`steroids health`	Project health check with weighted scoring
`steroids scan`	Scan directory for projects (auto-detects language/framework)
`steroids backup create`	Backup Steroids data
`steroids backup restore <file>`	Restore from backup
`steroids gc`	Garbage collection (orphaned IDs, stale runners, DB optimization)
`steroids purge tasks --older-than 30d`	Purge old data
`steroids locks list`	View active task/section locks
`steroids locks release <id>`	Release a stuck lock
`steroids stats`	Global activity statistics
`steroids stats 7d`	Activity stats for last 7 days
`steroids git status`	Git status with task context
`steroids git push`	Push with retry logic
`steroids logs list`	List invocation log files
`steroids completion bash`	Generate shell completion script
`steroids completion install`	Auto-install completion for your shell
`steroids hooks list`	List configured event hooks
`steroids hooks add`	Add an event hook
`steroids hooks test <event>`	Test a hook

Runner Daemon

Steroids includes a runner daemon for background processing:

# Start in background
steroids runners start --detach

# Check status
steroids runners list

# View logs
steroids runners logs <pid> --follow

# Stop all runners
steroids runners stop --all

# Auto-restart via cron
steroids runners cron install

The daemon:

Picks up pending tasks automatically
Updates heartbeat for health monitoring
Pushes approved work to git
Continues until all tasks complete or shutdown signal received
Skips sections marked as skipped (e.g., "Needs User Input")

Bug Intake

Steroids can ingest external bug reports, normalize them into the project database, and move them through a deterministic triage -> reproduction -> fix workflow.

Intake connectors poll during steroids runners wakeup, honoring each connector's poll interval and persisted cursor state.
GitHub intake can also accept signed inbound webhooks at POST /webhooks/intake/:connector.
New reports can open a GitHub approval issue, then create internal intake tasks only after the gate is approved.
Intake tasks stay phase-specific: triage decides close | reproduce | fix, reproduction decides close | retry | fix, and approved tasks advance the report without ad hoc state transitions.
The dashboard and API expose intake reports, summary stats, and connector health so you can monitor the pipeline without digging through the database.

This is intended for bug-report funnels such as GitHub Issues or Sentry where you want external reports to become tightly scoped internal work instead of free-form backlog noise.

Coordinator System

When the coder and reviewer get stuck in a rejection loop, the coordinator intervenes automatically at rejection thresholds (2, 5, and 9 rejections):

The coordinator analyzes the rejection history and makes one of three decisions:

Decision	Effect
guide_coder	Reviewer feedback is valid — gives the coder clearer direction
override_reviewer	Some reviewer demands are out of scope — tells the reviewer to stop raising them
narrow_scope	Reduces the task scope to an achievable subset

The coordinator's guidance flows to both the coder and the reviewer on subsequent iterations, ensuring alignment. This prevents death spirals where the coder and reviewer talk past each other.

Configure the coordinator in .steroids/config.yaml:

ai:
  orchestrator:
    provider: claude
    model: claude-sonnet-4

Disputes

When a task hits 15 rejections, or when a coder/reviewer raises one manually, Steroids creates a dispute:

# View open disputes
steroids dispute list

# Resolve a dispute
steroids dispute resolve <id> --decision coder --notes "Coder's approach is correct"

Dispute types:

major — Fundamental disagreement blocking progress
minor — Logged for record, doesn't block
coder — Raised by the coder against reviewer feedback
reviewer — Raised by the reviewer against coder's implementation

Hooks

Steroids supports event hooks that trigger shell commands or webhooks:

# List configured hooks
steroids hooks list

# Add a hook
steroids hooks add

# Test a hook
steroids hooks test task.completed

Events: task.created, task.completed, task.failed, section.completed, project.completed

Configure hooks in .steroids/config.yaml or manage via CLI.

Configuration

Project Config (`.steroids/config.yaml`)

ai:
  coder:
    provider: claude          # claude, codex, gemini
    model: claude-sonnet-4
  reviewer:
    provider: claude
    model: claude-sonnet-4
    customInstructions: |
      Prioritize API contract compatibility and migration safety.
  reviewers:                  # Optional multi-review mode
    - provider: claude
      model: claude-sonnet-4
      customInstructions: "Focus on architecture and maintainability."
    - provider: codex
      model: gpt-5
      customInstructions: "Focus on correctness, tests, and edge cases."
  orchestrator:               # Coordinator for breaking rejection loops
    provider: claude
    model: claude-sonnet-4

git:
  remote: origin
  branch: main
  prAssignees:               # Optional GitHub assignees for auto-created section PRs
    - "@me"
  prReviewers:               # Optional GitHub reviewers or teams for auto-created section PRs
    - octocat
    - my-org/platform-team

output:
  format: table
  colors: true

quality:
  tests:
    required: true
    minCoverage: 80           # Per-task modified files, not global

sections:
  batchMode: false            # Process all section tasks at once
  maxBatchSize: 10            # Max tasks per batch

disputes:
  timeoutDays: 7
  autoCreateOnMaxRejections: true

runners:
  heartbeatInterval: 30s
  staleTimeout: 5m
  maxConcurrent: 1

locking:
  taskTimeout: 60m
  sectionTimeout: 120m

database:
  autoMigrate: true
  backupBeforeMigrate: true

build:
  timeout: 5m

test:
  timeout: 10m

logs:
  retention: 30d
  level: info                 # debug, info, warn, error

backup:
  enabled: true
  retention: 7d

intake:
  enabled: false
  pollIntervalMinutes: 15
  maxReportsPerPoll: 50
  connectors:
    sentry:
      enabled: false
      baseUrl: https://sentry.io
      organization: ""
      project: ""
      authTokenEnvVar: SENTRY_AUTH_TOKEN
      webhookSecretEnvVar: SENTRY_WEBHOOK_SECRET
    github:
      enabled: false
      apiBaseUrl: https://api.github.com
      owner: ""
      repo: ""
      tokenEnvVar: GITHUB_TOKEN
      webhookSecretEnvVar: GITHUB_WEBHOOK_SECRET
      labels: []

intake defines shared bug-intake connector settings. Validation rejects intake.enabled: true unless at least one connector is enabled and its required identifiers are configured.

The GitHub Issues connector uses the installed gh CLI for pull and push operations. The token named by intake.connectors.github.tokenEnvVar must be present in the environment when intake runs. Inbound signed webhooks use POST /webhooks/intake/:connector and validate HMAC-SHA256 signatures against the connector secret named by webhookSecretEnvVar. Enabled intake connectors are polled during the regular steroids runners wakeup cycle, honoring pollIntervalMinutes and persisting normalized reports plus per-connector cursor state in the project database.

Global Config (`~/.steroids/config.yaml`)

Same schema — acts as default, overridden by project config.

Environment Variables

STEROIDS_ANTHROPIC=...                # For Claude models
STEROIDS_OPENAI=...                   # For Codex (OpenAI's development CLI)
STEROIDS_GOOGLE=...                   # For Gemini models

STEROIDS_JSON=1              # Output as JSON
STEROIDS_QUIET=1             # Minimal output
STEROIDS_VERBOSE=1           # Detailed output
STEROIDS_NO_COLOR=1          # Disable colors

Quality & Safety

Steroids is built for developers who believe in:

Testable code over "it works on my machine"
Clean architecture over vibe coding
Maintainable structures over quick hacks
Developer experience over feature bloat

The coder is required to:

Run build before submitting for review
Run tests before submitting for review
Fix errors until both pass
Use secure patterns (array-based shell APIs, parameterized queries)
Create feedback tasks for pre-existing concerns

The reviewer verifies:

Implementation matches the spec
Build and tests pass
Code follows project conventions
Security review of new/changed code (injection, shell safety, secrets, permissions, unsafe execution)
Test coverage for modified files (when configured)
Creates feedback tasks for advisory items that don't block approval

The Suite

Steroids CLI

The main task orchestration CLI. Manages tasks, sections, runners, and the coder/reviewer loop.

Monitor (Planned)

Mac menu bar companion app for real-time status at a glance across multiple projects.

Pump (Planned)

Data gathering CLI using Google APIs (Gemini, Search). Grounds LLM responses with real-time data.

Iron (Planned)

Documentation scaffolding wizard. Interactive CLI for setting up CLAUDE.md, AGENTS.md, and architecture docs.

Roadmap

Contributing

We welcome contributions that improve code quality and developer experience.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

License

MIT License — see LICENSE for details.

Credits

Created by UnlikeOther.ai

Author: Ondrej Rafaj (@rafiki270)

Made with love in Scotland.

Name		Name	Last commit message	Last commit date
Latest commit History 1,156 Commits
.gemini		.gemini
API		API
Assets		Assets
Monitor		Monitor
WebUI		WebUI
docs		docs
migrations		migrations
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
GEMINI.md		GEMINI.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.jest.json		tsconfig.jest.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Steroids

Table of Contents

Why Steroids

Who It's For

How It Works

Key Features

Project Structure

Quickstart

1. Install

2. Initialize in a project

3. Create sections and tasks

4. Run the loop

Web Dashboard

Managing the Dashboard

What You Get

CLI Commands

Core Commands

Task Management

Section Management

Runner Management

Dispute Management

AI Providers

Project Registry

Configuration

Maintenance & Utilities

Runner Daemon

Bug Intake

Coordinator System

Disputes

Hooks

Configuration

Project Config (.steroids/config.yaml)

Global Config (~/.steroids/config.yaml)

Environment Variables

Quality & Safety

The Suite

Steroids CLI

Monitor (Planned)

Pump (Planned)

Iron (Planned)

Roadmap

Contributing

License

Credits

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 207

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Project Config (`.steroids/config.yaml`)

Global Config (`~/.steroids/config.yaml`)

Packages