Getting Started

What you'll need

• Python 3.10 or later
• Git
• An API key for a planning provider — DeepSeek (default) or OpenAI, or any custom OpenAI-compatible endpoint
• Claude Code installed and authenticated — for execution

Install

brew install webrowse/street/romyq   # macOS / Linux
pip install romyq                    # any platform
romyq version   # confirm: romyq 0.11.0

New project

mkdir my-project
cd my-project
git init
romyq init

The wizard asks for your mission, complexity profile, and planning provider. Pick DeepSeek, OpenAI, or a custom OpenAI-compatible endpoint — type b at any prompt to go back and choose again. It writes .env, creates .romyq/, generates a mission.md, and shows a lifecycle preview before you confirm.

Existing project

cd my-existing-project
romyq attach

This attaches Romyq without running the wizard. It creates .romyq/ and a mission.md template. Edit mission.md to describe what you want built.

Set your API key

If you need to set or update the key manually:

echo "DEEPSEEK_API_KEY=sk-..." >> .env

To use OpenAI or a custom endpoint instead:

echo "ROMYQ_PLANNER_API_KEY=sk-..." >> .env
echo "ROMYQ_PLANNER_BASE_URL=https://api.openai.com/v1" >> .env
echo "ROMYQ_PLANNER_MODEL=gpt-4o-mini" >> .env

ROMYQ_PLANNER_API_KEY takes precedence over DEEPSEEK_API_KEY if both are set.

Check your environment

romyq doctor

This validates your API key, Claude Code installation, and git setup. Fix any reported issues before running.

Run

romyq run

Romyq reads mission.md, generates a task plan with DeepSeek, and executes each task with Claude Code. Every successful task is committed to git. The loop runs until you stop it or add --until-complete.

romyq run --until-complete   # stop automatically when done
romyq run --approval         # approve each task before it executes

Monitor

Open a second terminal while romyq run is active:

romyq status       # current task and loop state
romyq dashboard    # full lifecycle text overview
romyq health       # high-level health summary

Or launch the live Textual TUI (requires pip install 'romyq[ui]'):

romyq ui

Steer and control

romyq pause                              # pause after current task
romyq resume                             # resume
romyq stop                               # graceful shutdown
romyq steer "use PostgreSQL"             # inject instruction into next planning call
romyq note "focus on auth next"          # add a steering note
romyq rules add "Always write tests"     # add a governance rule

Next steps

• Quick Start — complete end-to-end walkthrough
• Commands — full CLI reference (40 commands)
• Complexity Profiles — Basic, Intermediate, Advanced
• Governance — rules and the decision log