Romyq

Autonomous AI software project manager.

Give Romyq a software goal. It plans, codes, commits, audits, and keeps improving until you stop it.

Run romyq ui to launch the live dashboard while romyq run is active.

Install

brew install webrowse/street/romyq   # macOS / Linux (Homebrew)
pip install romyq                    # any platform with Python 3.10+

60-Second Quick Start

mkdir my-project
cd my-project
git init

romyq init
# The wizard asks for your mission, complexity profile,
# and DeepSeek API key, then writes .env and mission.md.

romyq doctor
romyq run

Attaching to an existing repository instead:

cd my-existing-project
romyq attach                             # creates .romyq/ and a mission.md template
echo "DEEPSEEK_API_KEY=sk-..." >> .env   # set your key
# Edit mission.md — describe what you want built

romyq doctor
romyq run

That's it. Romyq takes over from here.

What Happens Next

• Romyq reads mission.md
• DeepSeek generates a task plan
• Claude Code implements each task
• Every successful task creates a git commit
• Romyq audits progress and keeps improving the project

Commands

Setup

Running

Observability

Lifecycle

Governance & Visibility

Intelligence & Diagnostics

Meta

Configuration

Romyq reads a .env file from your project directory (romyq init writes it for you):

DEEPSEEK_API_KEY=sk-...      # required — planning provider
ROMYQ_CLAUDE_TIMEOUT=1800    # optional — per-task Claude timeout in seconds

The planner defaults to DeepSeek but any OpenAI-compatible endpoint works — romyq init lets you pick DeepSeek, OpenAI, or a custom endpoint, or set it manually:

ROMYQ_PLANNER_API_KEY=sk-...                      # overrides DEEPSEEK_API_KEY
ROMYQ_PLANNER_BASE_URL=https://api.deepseek.com   # optional
ROMYQ_PLANNER_MODEL=deepseek-chat                 # optional
ROMYQ_PLANNER_TIMEOUT=600                         # optional, seconds per request

Advanced Usage

Run against an existing repository:

romyq attach /path/to/repo
romyq run /path/to/repo

Set workspace via environment variable:

ROMYQ_WORKSPACE=/path/to/repo romyq run

Requirements

• Python 3.10+
• Claude Code installed and authenticated
• DeepSeek API key
• Git initialized in your project directory

Dashboard

romyq ui opens a live Textual dashboard that reads state files while romyq run is active in another terminal.

┌─ romyq  /path/to/project  ● running  tasks:12  hb:30s  commit:abc1234 ─┐
│                                                                          │
│  Current Task                 │  Claude Output                          │
│  ─────────────────────────    │  ──────────────────────────────────     │
│  Implement JWT authentication │  Created auth/jwt.py                    │
│  for the admin API. Add       │  Added TokenMiddleware to app.py        │
│  middleware to validate all   │  All 24 tests passing                   │
│  protected routes.            │  Committed: feat: add JWT auth          │
│  ─────────────────────────    │                                         │
│  Task History                 │  ──────────────────────────────────     │
│  ─────────────────────────    │  Findings          │  Notes             │
│  ✓ 15:42 impl  Add OAuth...   │  ─────────────────────────────────     │
│  ✗ 15:40 impl  Add tests...   │  [HIGH]  Repeated failure: progress    │
│  ✓ 15:38 audi  Fix vulns...   │  [MEDI]  Missing input validation      │
│  ✓ 15:35 impl  Add models...  │                                         │
│                               │                                         │
└──────────────────────────────────────────────────────────────────────────┘
│  q quit  r refresh                                                       │

Install the dashboard:

pip install 'romyq[ui]'

Launch alongside a running loop:

# Terminal 1
romyq run

# Terminal 2
romyq ui

The dashboard polls state files every 2 seconds. No changes to the running loop are required.

Rate Limit Handling

When Claude hits a session or usage limit, Romyq detects it automatically instead of treating it as a task failure:

• Parses the reset time from Claude's output (e.g. resets 5:50am (Asia/Calcutta))
• Logs the reset time and timezone
• Sets status: rate_limited in state (visible in romyq ui and romyq status)
• Sleeps until the reset time plus a 5-minute safety buffer
• Retries the same task — no new DeepSeek call is wasted
• Falls back to a 30-minute sleep if the reset time cannot be parsed

The loop can be stopped early during a rate-limit sleep with romyq stop.

Loop Control

Run these from any terminal while romyq run is active in another:

romyq pause    # idle after current task (loop keeps running)
romyq resume   # resume a paused loop
romyq stop     # exit gracefully after current task (or wake from rate-limit sleep)

These commands write flags to .romyq/state.json. The loop reads them between tasks.

Changelog

See CHANGELOG.md.

License

MIT