--- name: autonomous-dev description: | Dispatch autonomous coding work to Codex CLI + OMX (oh-my-codex) with clawhip Discord notifications. Supports fire-and-forget task execution, monitored tmux sessions, parallel team workers, and persistent completion loops — all without human supervision. Works on any project directory. compatibility: Created for Zo Computer metadata: author: rob.zo.computer --- # Autonomous Dev — Unsupervised Coding with Codex + OMX + Clawhip Dispatch autonomous development work using Codex CLI, OMX orchestration, and clawhip Discord notifications. The agent runs in a tmux session with full autonomy — you walk away, it keeps working, and Discord pings you when something happens. ## Critical Dispatch Rule: the outer agent must never write code When this skill is used from Zo, the calling agent is a **dispatcher and monitor only**. That outer agent must: - launch the delegated coding process - monitor whether it started, is making progress, stalled, or failed - inspect logs, tmux sessions, worktree activity, commits, and test output as evidence - report status back to the user That outer agent must **never**: - edit source files itself - write replacement code itself - "help" by making manual code changes if the delegated process is slow, stuck, or failing - mix its own implementation work with the delegated coding session Why: this skill delegates to a separate coding system. If the dispatching agent also starts writing code, it creates conflicts with the delegated worker, corrupts ownership of the work, and makes progress harder to verify. If the delegated process fails, stalls, or makes no progress, the correct behavior is still: 1. do **not** write code in the outer agent 2. gather evidence about what happened 3. report the current status, blocker, or failure mode to the user 4. optionally relaunch or switch delegation strategy, but still without the outer agent coding directly ## Installed Tools | Tool | Purpose | |---|---| | **codex** (OpenAI Codex CLI) | Execution engine — runs code, edits files, executes shell commands | | **omx** (oh-my-codex) | Orchestration layer — agents, skills, plans, team mode, ralph loops | | **omc** (oh-my-claudecode) | Claude Code wrapper (alternative engine) | | **opencode** + oh-my-openagent | OpenCode with multi-agent orchestration (Sisyphus, Prometheus, etc.) | | **clawhip** | Event daemon — monitors tmux sessions, routes notifications to Discord | | **comment-checker** | Hook that catches leftover comments in code | ## Default Configuration - **Model**: `gpt-5.4` at `xhigh` reasoning effort - **Engine**: Codex CLI via OMX (preferred) - **Autonomy**: Full (`--madmax` = bypass all approvals and sandbox restrictions) - **Notifications**: clawhip → Discord channel `1490099048756023318` ## Execution Modes There are three main ways to dispatch work. They serve different purposes and compose together. ### 1. Single task (`exec`) One-shot execution. The agent works the task, finishes, and exits. ```bash cd /path/to/project omx exec --madmax --xhigh "YOUR TASK DESCRIPTION" ``` Best for: bounded tasks with clear completion criteria. Refactors, bug fixes, adding a feature with tests. ### 2. Team (`$team`) — parallel workers Spawns N Codex/Claude sessions in tmux panes, each claiming tasks from a shared queue. Workers operate independently with shared state coordination through `.omx/state/team/` files. ```bash cd /path/to/project omx team 3:executor --madmax "implement auth, database, and API layers" ``` **How team works:** - OMX splits the task into subtasks, creates a task list in `.omx/state/team//tasks/` - Each worker claims a task, executes it, commits, marks it done, claims the next - Workers communicate through mailbox files and the `omx team api` CLI - A leader monitors progress and can reassign failed tasks - One worker lane should focus on verification (tests, regression) before shutdown - Workers commit incrementally: `git add -A && git commit -m "task: "` **Team lifecycle:** ```bash omx team status # check task counts, worker health omx team resume # reconnect to live session omx team shutdown # graceful shutdown (only when pending=0, in_progress=0, failed=0) ``` **Team does NOT loop.** When all tasks are complete and verification passes, it's done. If something is left incomplete, you escalate to ralph. ### 3. Ralph (`$ralph`) — persistent completion loop A single-agent loop that keeps iterating until the task is genuinely complete and architect-verified. This is the "don't stop until it's done" mode. ```bash cd /path/to/project omx ralph --madmax --xhigh "refactor the auth module and ensure all tests pass" ``` **How ralph works:** 1. Assembles a context snapshot (`.omx/context/{slug}-{timestamp}.md`) 2. Reviews progress / picks up where it left off 3. Delegates subtasks to specialist agents at appropriate tiers (parallel when independent) 4. Runs long operations (builds, tests) in background 5. Verifies completion with fresh evidence — actually runs the tests and reads the output 6. Submits to architect verification (STANDARD tier minimum) 7. Runs a deslop pass (removes AI-generated code smell) 8. Re-verifies after deslop to catch regressions 9. If anything fails at any step → loops back and fixes it 10. Only exits when ALL of: tests pass, build succeeds, 0 diagnostics errors, architect approves **Ralph's completion checklist (all must be true):** - All requirements from original task met (no scope reduction) - Zero pending/in_progress TODO items - Fresh test output shows all pass - Fresh build output shows success - lsp_diagnostics = 0 errors on affected files - Architect verification passed - Post-deslop regression green **Ralph will not declare done without evidence.** "Should work" or "looks good" is not evidence. It needs actual command output showing success. ### Combining team + ralph The recommended pattern for large tasks: ```bash # Phase 1: parallel execution omx team 3:executor --madmax "build all three modules with tests" # Phase 2: persistent cleanup/verification omx ralph --madmax --xhigh "verify everything integrates, fix any issues, ensure full test coverage" ``` Team gets breadth (parallel workers). Ralph gets depth (won't quit). Team may leave loose ends — ralph closes them. ## The Canonical OMX Workflow Inside any codex/omx session, these skills compose into a full pipeline: ``` $deep-interview → $ralplan → $team or $ralph ``` | Step | Skill | What it does | |---|---|---| | 1 | `$deep-interview "..."` | Clarify scope, requirements, non-goals. Use when the task is fuzzy. | | 2 | `$ralplan "..."` | Generate an implementation plan with planner/architect/critic consensus. Outputs staffing recommendations. | | 3a | `$team N:role "..."` | Execute the plan with N parallel workers. | | 3b | `$ralph "..."` | Execute with a persistent loop until verified complete. | **Shortcut:** include `ultrawork` or `ulw` in any prompt and the agent auto-orchestrates the full pipeline without you specifying skills. Other useful skills inside a session: | Skill | Purpose | |---|---| | `$autopilot "..."` | Full autonomous pipeline when you skip the standard workflow | | `$ultrawork "..."` | Max parallel execution | | `$ultraqa "..."` | Test → verify → fix loop | | `$tdd "..."` | Test-driven development | | `$code-review "..."` | Review current branch | | `$security-review "..."` | Security-focused review | | `$visual-verdict "..."` | Screenshot-based visual QA | | `$doctor` | Check OMX health | ## Launching with Discord Monitoring Wrap any launch in clawhip's tmux integration to get Discord notifications on keyword matches (errors, completion, etc.): ```bash # Interactive session (detach with Ctrl-b d, agent keeps running): clawhip tmux new -s TASK_NAME \ --channel 1490099048756023318 \ --keywords "tests passed,tests failed,build failed,exit code,ralph complete,architect approved,✅,❌" \ -- "cd /path/to/project && omx --madmax --xhigh" # Fire-and-forget: clawhip tmux new -s TASK_NAME \ --channel 1490099048756023318 \ --keywords "tests passed,tests failed,build failed,exit code,ralph complete,✅,❌" \ -- "cd /path/to/project && omx exec --madmax --xhigh 'YOUR TASK'" ``` **Keyword selection matters.** Generic words like "complete", "done", "error" will match constantly in normal prose and plan text, producing a wall of noise. Use specific phrases that only appear in actual terminal output: test results, exit codes, emoji markers, and OMX lifecycle events. ## Using the Dispatch Script `scripts/dispatch.sh` wraps all the patterns above. **Important:** when you use this dispatch script from Zo, the caller is only the dispatcher. The caller should launch work, monitor it, and summarize status. The caller should **never** patch files or write code itself, even if the delegated coding run is failing or not making progress. ```bash # Single task with Discord monitoring: bash Skills/autonomous-dev/scripts/dispatch.sh \ --dir /path/to/project \ --task "implement user registration flow" \ --name reg-task # Team mode (3 parallel workers): bash Skills/autonomous-dev/scripts/dispatch.sh \ --dir /path/to/project \ --task "implement auth, db, and api layers" \ --name auth-build \ --team 3 ``` For long-running team jobs, prefer routing the combined log to a path **outside** the repo and keep the repo clean before launch. ```bash mkdir -p /tmp/autonomous-dev bash Skills/autonomous-dev/scripts/dispatch.sh \ --dir /path/to/project \ --task "implement auth, db, and api layers" \ --name auth-build \ --team 3 >> /tmp/autonomous-dev/auth-build.log 2>&1 ``` ```bash # Ralph (persistent loop until done): bash Skills/autonomous-dev/scripts/dispatch.sh \ --dir /path/to/project \ --task "fix all failing tests and ensure 100% pass rate" \ --name fix-tests \ --ralph # Team → ralph combo: bash Skills/autonomous-dev/scripts/dispatch.sh \ --dir /path/to/project \ --task "build all three modules" \ --name build-phase \ --team 3 # Then after team completes: bash Skills/autonomous-dev/scripts/dispatch.sh \ --dir /path/to/project \ --task "verify integration, fix issues, full test coverage" \ --name verify-phase \ --ralph # Alternative engines: bash Skills/autonomous-dev/scripts/dispatch.sh \ --dir /path/to/project \ --task "refactor the API layer" \ --name api-refactor \ --engine opencode # Uses Claude Opus 4.6 via oh-my-openagent/Sisyphus bash Skills/autonomous-dev/scripts/dispatch.sh \ --dir /path/to/project \ --task "add test coverage" \ --name add-tests \ --engine omc # Uses Claude Code directly ``` ## Checking on Sessions ```bash tmux ls # List active sessions tmux attach -t TASK_NAME # Watch a session live clawhip status # Clawhip daemon health clawhip send --message "..." # Manual Discord notification omx team status # Team task/worker status (if using team mode) ``` If `omx team status ` looks wrong but the tmux session and worker processes exist, trust the live tmux panes, worktree activity, and external log path first. In practice, those signals can be more reliable for in-flight debugging. ## Engine Comparison | Engine | Model | Best for | |---|---|---| | `codex` + OMX (default) | GPT-5.4 xhigh | General coding, plan→execute, parallel team, ralph loops | | `opencode` + oh-my-openagent | Claude Opus 4.6 max20 | Claude-optimized deep work, Sisyphus multi-agent orchestration | | `omc` (oh-my-claudecode) | Claude via Claude Code | Claude-native, when you want Claude's style directly | ## Project Setup For best results, ensure the target project has an `AGENTS.md` at its root describing the codebase, conventions, and architecture. OMX reads this as its orchestration context. Bootstrap one with: ```bash cd /path/to/project && omx agents-init ``` ## Preflight for team runs Before launching `omx team`, make sure the leader workspace is clean. Why: OMX team uses git worktrees for workers, and it will refuse to launch if the leader repo has uncommitted files that would interfere with worktree setup. Check this first: ```bash cd /path/to/project git status --short ``` If the repo is dirty: - commit the setup/context files you want the workers to inherit, or stash them first - do **not** leave temporary log files, pid files, or other runtime artifacts inside the repo root before starting the team - if you want one combined log for a long autonomous run, write it **outside** the repo (for example in a conversation scratch directory) so the repo stays clean - add runtime folders such as `.omx/`, `.pytest_cache/`, virtualenvs, and build artifacts to `.gitignore` before the run so the repo stays clean while workers execute Good pattern: ```bash LOG_FILE="/some/path/outside/the/repo/task.log" cd /path/to/project omx team 5:executor --madmax "YOUR TASK" >> "$LOG_FILE" 2>&1 ``` This avoids the `leader_workspace_dirty_for_worktrees` failure mode. ## If OMX team looks alive but is not actually working A tmux session and worker panes are **not** enough evidence that the team is productively running. Failure mode seen in practice: - tmux session exists - worker panes exist - `omx team status` may be misleading or incomplete - workers are sitting at Codex UI prompts instead of executing tasks - task JSON files remain `pending` - no real repo artifacts are being created Check for real progress: - inspect the worker panes, not just the leader pane - verify worker processes are actually running non-interactively - inspect task files / worktree files / recent commits - prefer evidence like changing files, fresh commits, and passing tests over the OMX HUD If workers are stuck at trust prompts, idle UI, or tasks remain pending for too long, do **not** keep waiting. The fallback is to change delegation strategy, not to start coding in the outer agent. Keep the outer agent in dispatcher/observer mode: inspect evidence, restart with a better launch pattern, or report the failure clearly to the user. ## Practical fallback: manual parallel workers If OMX team stalls, use a manual fallback that is more deterministic: 1. create N clean git worktrees 2. launch one non-interactive `codex exec` worker in each worktree 3. give each worker a scoped sub-mission 4. write all stdout/stderr to a single log file **outside** the repo 5. compare the resulting branches/worktrees and merge the best result manually Recommended pattern: ```bash git worktree add /tmp/project-worker-1 HEAD git worktree add /tmp/project-worker-2 HEAD # ... codex exec --dangerously-bypass-approvals-and-sandbox -m gpt-5.4 "TASK FOR WORKER 1" \ >> /some/path/outside/the/repo/team.log 2>&1 & ``` Why this fallback works better: - avoids interactive tmux trust/setup prompts - easier to verify with normal process checks - each worker is plainly non-interactive - easier to consolidate logs into one file - easier to inspect commits and diffs per worker ## Recommended launch preference for long unattended runs For long unattended coding runs, prefer this order: 1. OMX team when you want native shared-task orchestration **and** you have verified it is actually executing 2. manual parallel worktrees with `codex exec` when reliability matters more than OMX niceties 3. ralph after breadth work is done, for final cleanup / verification / completion loops When using any of these modes, always make sure: - logs live outside the repo - runtime state is gitignored - progress is verified by files/commits/tests, not by UI alone - the final repo gets a human-visible implementation summary and test evidence ## Clawhip Config Config: `~/.clawhip/config.toml`. The daemon runs on port 25294 and routes all events to Discord. To permanently monitor specific tmux sessions: ```toml [monitors.tmux] sessions = ["TASK_NAME"] ```