{"skill":{"slug":"autopilot","displayName":".Autopilot","summary":"tmux + launchd multi-project Codex CLI automation system. Watchdog-driven loop that monitors multiple Codex sessions in tmux, auto-nudges idle sessions, hand...","description":"---\nname: codex-autopilot\ndescription: |\n  tmux + launchd multi-project Codex CLI automation system. Watchdog-driven loop that monitors multiple Codex sessions in tmux, auto-nudges idle sessions, handles permissions, manages context compaction, runs incremental code reviews, and dispatches tasks from a queue.\n  Use when managing multiple concurrent Codex CLI coding sessions, automating development workflows, or orchestrating parallel AI-assisted coding across projects.\n  Triggers: autopilot, watchdog, codex automation, tmux codex, multi-project codex, auto-nudge codex, codex session management.\n---\n\n# Codex Autopilot\n\nAutomated multi-project Codex CLI orchestration via tmux + launchd on macOS.\n\n## Overview\n\nCodex Autopilot runs a watchdog loop that monitors multiple Codex CLI sessions in tmux windows. It detects idle sessions, auto-nudges them to continue, handles permission prompts, rotates logs, dispatches tasks from a queue, and sends notifications via Discord/Telegram.\n\n## Installation\n\n```bash\ngit clone https://github.com/imwyvern/AIWorkFlowSkill.git ~/.autopilot\ncd ~/.autopilot\ncp config.yaml.example config.yaml\n# Edit config.yaml with your project paths, Telegram bot token, and Discord channels\n```\n\n### Dependencies\n\n- **macOS** with launchd (for scheduled execution)\n- **tmux** — session multiplexer for Codex windows\n- **Codex CLI** (`codex`) — OpenAI's coding agent\n- **python3** — for state cleanup and PRD verification scripts\n- **yq** — YAML processor for config parsing\n- **jq** — JSON processor for state management\n- **bash 4+** — for associative arrays in scripts\n\nInstall dependencies via Homebrew:\n```bash\nbrew install tmux yq jq\n```\n\n### launchd Setup\n\nUse `install.sh` to register the launchd plist:\n```bash\n./install.sh\n```\n\nThis creates a LaunchAgent that runs the watchdog on a configurable interval.\n\n## Core Components\n\n### watchdog.sh\nMain loop engine. On each tick:\n1. Iterates through configured project tmux windows\n2. Captures current Codex output via `codex-status.sh`\n3. Determines if session is active, idle, or stuck\n4. Dispatches appropriate action (nudge, permission grant, task from queue)\n5. Enforces cooldowns, daily send limits, and loop detection\n\n### codex-status.sh\nCaptures and analyzes tmux pane content. Detects:\n- Codex activity state (working / idle / waiting for permission)\n- Permission prompts requiring approval\n- Context compaction signals\n- Error states and crashes\n\n### tmux-send.sh\nSends keystrokes or text to a specific tmux window. Handles:\n- Typing text into Codex prompt\n- Pressing Enter/keys for permission approval\n- Verification polling to confirm send succeeded\n\n### autopilot-lib.sh\nShared function library used by all scripts:\n- Telegram notification helpers\n- File locking primitives\n- Timeout and retry logic\n- Logging utilities\n- State file read/write\n\n### autopilot-constants.sh\nDefines status constants used across scripts (e.g., `STATUS_ACTIVE`, `STATUS_IDLE`, `STATUS_PERMISSION`).\n\n### task-queue.sh\nTask queue manager. Supports:\n- Enqueuing tasks for specific projects\n- Dequeueing next task based on priority\n- Task status tracking (pending/running/done/failed)\n\n### discord-notify.sh\nSends formatted notifications to Discord channels via webhook. Supports project-channel routing defined in `config.yaml`.\n\n### Other Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `auto-nudge.sh` | Nudge logic for idle Codex sessions |\n| `auto-check.sh` | Periodic health check across all projects |\n| `permission-guard.sh` | Auto-approve or flag permission prompts |\n| `incremental-review.sh` | Run code review on recent changes |\n| `monitor-all.sh` | Dashboard: show status of all monitored projects |\n| `status-sync.sh` | Sync state to status.json for external consumption |\n| `rotate-logs.sh` | Log rotation and cleanup |\n| `cleanup-state.py` | Remove stale entries from state.json |\n| `claude-fallback.sh` | Fallback handler when Codex is unavailable |\n| `prd-audit.sh` | Audit PRD completion status |\n| `prd-verify.sh` / `prd_verify_engine.py` | Verify PRD items against codebase |\n| `codex-token-daily.py` | Track daily token usage |\n\n## Configuration\n\nEdit `config.yaml` (copy from `config.yaml.example`). Key sections:\n\n### Timing Thresholds\n```yaml\nactive_threshold: 120    # seconds — Codex considered \"working\"\nidle_threshold: 360      # seconds — Codex considered \"idle\", triggers nudge\ncooldown: 120            # minimum seconds between sends to same project\n```\n\n### Safety Limits\n```yaml\nmax_daily_sends_total: 200   # global daily send cap\nmax_daily_sends: 50          # per-project daily cap\nmax_consecutive_failures: 5  # pause project after N failures\nloop_detection_threshold: 3  # detect repeated output loops\n```\n\n### Multi-Project Scheduler\n```yaml\nscheduler:\n  strategy: \"round-robin\"    # or \"priority\"\n  max_sends_per_tick: 1\n  inter_project_delay: 5     # seconds between project sends\n```\n\n### Project Directories\n```yaml\nproject_dirs:\n  - \"~/project-alpha\"\n  - \"~/project-beta\"\n```\n\n### Discord Channel Routing\n```yaml\ndiscord_channels:\n  my-project:\n    channel_id: \"123456789\"\n    tmux_window: \"my-project\"\n    project_dir: \"/path/to/project\"\n```\n\n### Telegram Notifications\n```yaml\ntelegram:\n  bot_token: \"YOUR_BOT_TOKEN\"\n  chat_id: \"YOUR_CHAT_ID\"\n  status_interval: 1800\n```\n\n## Usage\n\n### Adding a Project\n\n1. Start a Codex CLI session in a named tmux window:\n   ```bash\n   tmux new-window -t autopilot -n my-project\n   # In the new window, cd to project and run codex\n   ```\n\n2. Add the project path to `config.yaml` under `project_dirs`\n\n3. Optionally create `projects/my-project/tasks.yaml` for task queue:\n   ```yaml\n   project:\n     name: \"My Project\"\n     dir: \"~/my-project\"\n     enabled: true\n     priority: 1\n   tasks:\n     - id: \"feature-x\"\n       name: \"Implement feature X\"\n       prompt: |\n         Implement feature X per the spec in docs/feature-x.md\n   ```\n\n### Manual Operations\n\n```bash\n# Check status of all projects\n./scripts/monitor-all.sh\n\n# Manually nudge a specific project\n./scripts/auto-nudge.sh my-project\n\n# Send a command to a tmux window\n./scripts/tmux-send.sh my-project \"codex exec 'fix the tests'\"\n\n# Enqueue a task\n./scripts/task-queue.sh enqueue my-project \"Refactor auth module\"\n\n# Run the watchdog once (for testing)\n./scripts/watchdog.sh\n```\n\n### Python Autopilot (Alternative)\n\n`autopilot.py` provides a Python-based alternative with richer state management:\n```bash\npython3 autopilot.py --once        # single pass\npython3 autopilot.py --daemon      # continuous loop\n```\n\n## Directory Structure\n\n```\n~/.autopilot/\n├── SKILL.md                 # This file\n├── config.yaml              # Local config (not in git)\n├── config.yaml.example      # Config template\n├── scripts/                 # All automation scripts\n├── projects/                # Per-project task definitions\n├── docs/                    # Additional documentation\n├── code-review/             # Code review templates\n├── development/             # Development workflow templates\n├── doc-review/              # Doc review templates\n├── doc-writing/             # Doc writing templates\n├── requirement-discovery/   # Requirement discovery templates\n├── testing/                 # Testing templates\n├── tests/                   # Test suite\n├── state/                   # Runtime state (gitignored)\n├── logs/                    # Runtime logs (gitignored)\n├── task-queue/              # Task queue data (gitignored)\n└── archive/                 # Deprecated files\n```\n","topics":["Coding"],"tags":{"latest":"0.5.0"},"stats":{"comments":0,"downloads":375,"installsAllTime":14,"installsCurrent":1,"stars":0,"versions":1},"createdAt":1772593139285,"updatedAt":1779078676009},"latestVersion":{"version":"0.5.0","createdAt":1772593139285,"changelog":"codex-autopilot 0.5.0\n\n- Initial public release of Codex Autopilot: multi-project Codex CLI automation using tmux and launchd on macOS.\n- Automated watchdog loop detects idle or stuck Codex sessions, handles permission prompts, dispatches queued tasks, rotates logs, and sends notifications via Discord/Telegram.\n- Modular shell scripts for session monitoring, task management, notification routing, and log/state maintenance.\n- Supports per-project configuration, safety thresholds, cooldowns, multi-project scheduling, and direct task queue integration.\n- Includes example configuration, detailed dependency list, and manual/automated usage instructions.","license":null},"metadata":null,"owner":{"handle":"imwyvern","userId":"s17as2pe33fqm26ag8dqnwe0gx83gd3q","displayName":"wes","image":"https://avatars.githubusercontent.com/u/1765672?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780089751368}}