Codex Autopilot

Automated multi-project Codex CLI orchestration via tmux + launchd on macOS.

Overview

Codex 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.

Installation

git clone https://github.com/imwyvern/AIWorkFlowSkill.git ~/.autopilot
cd ~/.autopilot
cp config.yaml.example config.yaml
# Edit config.yaml with your project paths, Telegram bot token, and Discord channels

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:

brew install tmux yq jq

launchd Setup

Use install.sh to register the launchd plist:

./install.sh

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

Core Components

watchdog.sh

Main loop engine. On each tick:

1. Iterates through configured project tmux windows
2. Captures current Codex output via codex-status.sh
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

Captures and analyzes tmux pane content. Detects:

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

tmux-send.sh

Sends keystrokes or text to a specific tmux window. Handles:

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

autopilot-lib.sh

Shared function library used by all scripts:

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

autopilot-constants.sh

Defines status constants used across scripts (e.g., STATUS_ACTIVE, STATUS_IDLE, STATUS_PERMISSION).

task-queue.sh

Task queue manager. Supports:

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

discord-notify.sh

Sends formatted notifications to Discord channels via webhook. Supports project-channel routing defined in config.yaml.

Other Scripts