Codex Autopilot

Multi-model AI coding automation system with intelligent task routing and built-in CI/CD. Watchdog-driven loop that orchestrates Codex (backend) and Gemini (...

Security Scan

The skill's code and runtime instructions broadly match an autopilot/orchestration purpose, but there are clear inconsistencies and missing declarations (credentials, install spec) and the scripts exercise broad system/network operations (git, launchd, tmux, auto-merge, webhooks) that merit careful review before installing.

Purpose & Capability

The name/description (Codex Autopilot: tmux orchestration, watchdog, CI/test-agent, auto-enqueue/auto-merge) align with the included scripts and Python modules: watchdog.sh, task-queue.sh, tmux-send.sh, branch-manager, test-agent, etc. However the registry metadata claims 'no required env vars' and 'instruction-only', which contradicts SKILL.md and the repository: SKILL.md instructs adding Telegram/Discord tokens and using Codex/Gemini CLIs, and many scripts depend on system tools (tmux, git, launchd). That mismatch between declared requirements and actual functionality is an integrity concern.

Instruction Scope

SKILL.md / README instruct running install.sh (registers a launchd LaunchAgent), starting watchdog as a daemon, creating tmux sessions and running Codex/Gemini CLIs, and configuring Telegram/Discord webhooks. The code and scripts also perform repository branch creation/auto-merge, tmux keystrokes (tmux-send.sh), reading/writing state under ~/.autopilot, parsing logs ($HOME/.autopilot/logs/test-agent-run-*.log), and calling external services. These instructions include filesystem and VCS modifications and network transmissions beyond a read-only monitoring tool — scope is broad and requires explicit consent and protection, but the skill's metadata does not enumerate these requirements.

Install Mechanism

There is no formal install spec in the registry (instruction-only), yet the package contains an install.sh that registers a launchd agent and numerous scripts that will be executed. Absence of an explicit install mechanism in metadata reduces transparency: user-facing instructions do a git clone from a third-party GitHub URL and run install.sh, which will persist a watchdog in system scheduling. That is functionally equivalent to installing software and should be treated as higher-risk than a pure SKILL.md.

Credentials

SKILL.md asks the user to populate config.yaml with Telegram bot token, Discord channel/webhook info, project paths and to run Codex/Gemini CLIs, but the skill's registry metadata lists zero required environment variables and 'no primary credential'. In practice the system will need credentials for messaging (Telegram/Discord), VCS (git push/pull if auto-merge/push runs), and model CLIs (Codex/Gemini tokens). The missing declaration of these credentials is an inconsistency and means potential secret access/exfiltration vectors are not documented.

Persistence & Privilege

Although always:false and autonomous invocation is default, the skill contains an install.sh that writes a LaunchAgent (launchd) to persist a watchdog loop, and scripts that perform long-running daemon behavior, branch creation/auto-merge, and push-like operations. Installing/registering the LaunchAgent has system persistence and elevated effect (sustained background execution modifying repositories). The skill would thus obtain long-lived capacity to act on the host; this is expected for an autopilot but should have explicit metadata and clearer consent.

What to consider before installing

This package contains a full autopilot engine (watchdog, tmux automation, task queue, branch-manager and an auto test-agent) that will: create a LaunchAgent (install.sh), run background scripts, control tmux sessions (send keystrokes), manipulate git branches (create, auto-merge, possibly push), and call external endpoints (Telegram/Discord/webhooks). Before installing: - Do not run install.sh or run the watchdog on production repositories without auditing the scripts first. Review watchdog.sh, tmux-send.sh, branch-manager.sh, task-queue.sh and test-agent.sh for the exact git operations, push/merge behavior, and any curl/wget/remote execution. - Expect to provide credentials/config (Telegram bot token, Discord webhooks, Codex/Gemini CLI auth, and likely git push rights) even though the registry metadata lists none; avoid giving high-privilege tokens. Prefer scoped, low-privilege tokens and webhook-only notification channels where possible. - If you want to try it safely: clone into an isolated VM or disposable user account, disable auto-merge/auto-push, run with test projects (non-production repos), and run the scripts manually with tracing to observe behavior before enabling launchd or background execution. - Ask the maintainer (or inspect the repo) for an explicit manifest listing required environment variables/credentials, an install checklist, and a clear safety-mode toggle (e.g., disable auto-merge, disable auto-enqueue, disable network notifications) — having those would reduce the flagged concerns and could change this assessment to benign. Bottom line: the code largely matches its claimed purpose, but the lack of declared credentials/install spec and the broad system privileges the scripts require make this suspicious until you audit and constrain what it can do.

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

Role	Model	Strengths
Backend coding	Codex (GPT-5.4)	API, database, deployment, refactoring
Frontend development	Gemini CLI	UI, components, pages, styles, 1M context
Orchestration	Claude / OpenClaw	Task routing, code review, project management

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

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.

test-agent.sh

Built-in CI/CD that runs on every commit. Evaluates test suites, tracks coverage, and auto-enqueues bugfix tasks when tests fail.

commit → watchdog detects → test-agent evaluate
  ├─ all pass → review clean → enqueue coverage tasks for low-coverage files
  └─ failures → parse log → auto-enqueue "fix(test): ..." bugfix task
       └─ 1h cooldown per file (prevents retry loops)

Triggers:

• on_commit_evaluate — every new commit
• on_review_clean — after code review passes
• nightly — scheduled full evaluation (default 02:30)

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

Other Scripts

Script	Purpose
auto-nudge.sh	Nudge logic for idle Codex sessions
auto-check.sh	Periodic health check across all projects
permission-guard.sh	Auto-approve or flag permission prompts
incremental-review.sh	Run code review on recent changes
monitor-all.sh	Dashboard: show status of all monitored projects
status-sync.sh	Sync state to status.json for external consumption
rotate-logs.sh	Log rotation and cleanup
cleanup-state.py	Remove stale entries from state.json
claude-fallback.sh	Fallback handler when Codex is unavailable
prd-audit.sh	Audit PRD completion status
prd-verify.sh / prd_verify_engine.py	Verify PRD items against codebase
codex-token-daily.py	Track daily token usage
coverage-collect.sh	Collect and merge coverage reports

Configuration

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

Timing Thresholds

active_threshold: 120    # seconds — Codex considered "working"
idle_threshold: 360      # seconds — Codex considered "idle", triggers nudge
cooldown: 120            # minimum seconds between sends to same project

Safety Limits

max_daily_sends_total: 200   # global daily send cap
max_daily_sends: 50          # per-project daily cap
max_consecutive_failures: 5  # pause project after N failures
loop_detection_threshold: 3  # detect repeated output loops

Multi-Project Scheduler

scheduler:
  strategy: "round-robin"    # or "priority"
  max_sends_per_tick: 1
  inter_project_delay: 5     # seconds between project sends

Project Directories

project_dirs:
  - "~/project-alpha"
  - "~/project-beta"

Gemini Frontend Routing

gemini:
  default_window: "gemini-h5"        # Default tmux window for frontend tasks
  project_windows:
    youxin: "gemini-youxin"          # Per-project Gemini window overrides

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

Discord Channel Routing

discord_channels:
  my-project:
    channel_id: "123456789"
    tmux_window: "my-project"
    project_dir: "/path/to/project"

Telegram Notifications

telegram:
  bot_token: "YOUR_BOT_TOKEN"
  chat_id: "YOUR_CHAT_ID"
  status_interval: 1800

Usage

Adding a Project

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

   tmux new-window -t autopilot -n my-project
   # In the new window, cd to project and run codex
   

2. Add the project path to config.yaml under project_dirs

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

   project:
     name: "My Project"
     dir: "~/my-project"
     enabled: true
     priority: 1
   tasks:
     - id: "feature-x"
       name: "Implement feature X"
       prompt: |
         Implement feature X per the spec in docs/feature-x.md
   

Manual Operations

# Check status of all projects
./scripts/monitor-all.sh

# Manually nudge a specific project
./scripts/auto-nudge.sh my-project

# Send a command to a tmux window
./scripts/tmux-send.sh my-project "codex exec 'fix the tests'"

# Enqueue a backend task (routes to Codex)
./scripts/task-queue.sh add my-project "Refactor auth module"

# Enqueue a frontend task (routes to Gemini)
./scripts/task-queue.sh add my-project "重构登录页面组件" normal --type frontend

# Run the watchdog once (for testing)
./scripts/watchdog.sh

Python Autopilot (Alternative)

autopilot.py provides a Python-based alternative with richer state management:

python3 autopilot.py --once        # single pass
python3 autopilot.py --daemon      # continuous loop

Directory Structure

~/.autopilot/
├── SKILL.md                 # This file
├── config.yaml              # Local config (not in git)
├── config.yaml.example      # Config template
├── scripts/                 # All automation scripts
├── projects/                # Per-project task definitions
├── docs/                    # Additional documentation
├── code-review/             # Code review templates
├── development/             # Development workflow templates
├── doc-review/              # Doc review templates
├── doc-writing/             # Doc writing templates
├── requirement-discovery/   # Requirement discovery templates
├── testing/                 # Testing templates
├── tests/                   # Test suite
├── state/                   # Runtime state (gitignored)
├── logs/                    # Runtime logs (gitignored)
├── task-queue/              # Task queue data (gitignored)
└── archive/                 # Deprecated files