romyq 0.5.0

Autonomous AI software project manager

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

pip install romyq

---

60-Second Quick Start

mkdir my-project
cd my-project
git init

cp .env.example .env
# Open .env and add your DEEPSEEK_API_KEY

romyq attach
# 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

Command	Description
romyq attach	Attach Romyq to an existing git repository
romyq init	Create a new managed workspace in the current directory
romyq doctor	Validate environment and configuration

Running

Command	Description
romyq run	Start the autonomous development loop
romyq note "message"	Inject a steering note into the next task
romyq pause	Pause the loop after the current task finishes
romyq resume	Resume a paused loop
romyq stop	Request graceful shutdown after the current task

Observability

Command	Description
romyq health	High-level health summary: tasks, failures, findings, heartbeat
romyq report	Full project report: mission, progress, commits, notes, findings
romyq status	Raw state: current task, last commit, heartbeat timestamp
romyq logs	Per-task history with success/failure and validation reason
romyq info	Detected language, frameworks, test suite, and build commands

Meta

Command	Description
romyq version	Show version, install type, and Python version
romyq ui	Launch the Textual TUI dashboard (coming soon)

---

Configuration

Copy the example file and fill in your keys:

cp .env.example .env

.env.example:

DEEPSEEK_API_KEY=
ROMYQ_CLAUDE_TIMEOUT=1800

---

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