Codex Autopilot

Multi-model AI coding orchestration via tmux + launchd on macOS.

Overview

Codex Autopilot runs a watchdog loop that orchestrates multiple AI coding sessions in tmux. It features intelligent task routing — frontend tasks (UI, components, H5) are routed to Gemini CLI (1M context window, superior design aesthetics), while backend tasks (API, database, deployment) go to Codex CLI. The watchdog detects idle sessions, auto-nudges them, handles permission prompts, dispatches tasks from a priority queue, and sends notifications via Discord/Telegram.

Multi-Model Architecture

Tasks are automatically classified by keywords and routed to the appropriate model. Frontend tasks fall back to Codex if Gemini is unavailable.

Installation

CODEBLOCK0

Dependencies

• - macOS with launchd (for scheduled execution)
• tmux — session multiplexer for Codex windows
• Codex CLI (codex) — OpenAI's coding agent
• python3 — for state cleanup and PRD verification scripts
• yq — YAML processor for config parsing
• jq — JSON processor for state management
• bash 4+ — for associative arrays in scripts

Install dependencies via Homebrew:
CODEBLOCK1

launchd Setup

Use install.sh to register the launchd plist:
CODEBLOCK2

This creates a LaunchAgent that runs the watchdog on a configurable interval.

Core Components

watchdog.sh

1. 1. Iterates through configured project tmux windows
2. Captures current Codex output via INLINECODE2
3. Determines if session is active, idle, or stuck
4. Dispatches appropriate action (nudge, permission grant, task from queue)
5. Enforces cooldowns, daily send limits, and loop detection

codex-status.sh

• - Codex activity state (working / idle / waiting for permission)
• Permission prompts requiring approval
• Context compaction signals
• Error states and crashes

tmux-send.sh

• - Typing text into Codex prompt
• Pressing Enter/keys for permission approval
• Verification polling to confirm send succeeded

autopilot-lib.sh

• - Telegram notification helpers
• File locking primitives
• Timeout and retry logic
• Logging utilities
• State file read/write

autopilot-constants.sh

task-queue.sh

• - Enqueuing tasks for specific projects
• Dequeueing next task based on priority
• Task status tracking (pending/running/done/failed)

discord-notify.sh

test-agent.sh

CODEBLOCK3

Triggers:

• - on_commit_evaluate — every new commit
• INLINECODE8 — after code review passes
• INLINECODE9 — scheduled full evaluation (default 02:30)

Coverage ratchet: global coverage must not regress; weekly +1% target, capped at 90%.

Other Scripts

Configuration

Edit config.yaml (copy from config.yaml.example). Key sections:

Timing Thresholds

Safety Limits

Multi-Project Scheduler

Project Directories

Gemini Frontend Routing

Frontend task detection keywords: 页面, 组件, 样式, UI, 前端, H5, 小程序, 界面, frontend, component, style, page, INLINECODE38

Discord Channel Routing

Telegram Notifications

Usage

Adding a Project

1. 1. Start a Codex CLI session in a named tmux window:

1. 2. Add the project path to config.yaml under INLINECODE40

1. 3. Optionally create projects/my-project/tasks.yaml for task queue:

Manual Operations

CODEBLOCK13

Python Autopilot (Alternative)

INLINECODE42 provides a Python-based alternative with richer state management:
CODEBLOCK14

Directory Structure

CODEBLOCK15