Autonomous Skill - Long-Running Task Execution
Execute complex, long-running tasks across multiple sessions using a dual-agent pattern (Initializer + Executor) with automatic session continuation via Codex non-interactive mode.
Quick Start
Use the run-session.sh script to manage autonomous tasks:
# Start a new autonomous task
~/.codex/skills/autonomous-skill/scripts/run-session.sh "Build a REST API for todo app"
# Continue an existing task
~/.codex/skills/autonomous-skill/scripts/run-session.sh --task-name build-rest-api-todo --continue
# List all tasks and their progress
~/.codex/skills/autonomous-skill/scripts/run-session.sh --list
# Show help
~/.codex/skills/autonomous-skill/scripts/run-session.sh --helpThe runner intentionally leaves --model unset so Codex uses the active config.toml or selected profile model by default.
Directory Structure
All task data is stored in .autonomous/<task-name>/ under the project root:
project-root/
└── .autonomous/
├── build-rest-api/
│ ├── task_list.md # Master task checklist
│ ├── progress.md # Session-by-session notes
│ ├── session.id # Last Codex session ID for resumption
│ └── session.log # Codex stdout/stderr transcript with JSON events
├── refactor-auth/
│ ├── task_list.md
│ ├── progress.md
│ └── session.id
└── ...This allows multiple autonomous tasks to run in parallel without conflicts.
Script Options
Usage:
run-session.sh "task description" Start new task (auto-generates name)
run-session.sh --task-name <name> --continue Continue specific task
run-session.sh --list List all tasks
run-session.sh --help Show help
Options:
--task-name <name> Specify task name explicitly
--continue, -c Continue existing task
--no-auto-continue Don't auto-continue after session
--max-sessions N Limit to N sessions
--list List all existing tasks
--resume-last Resume the most recent Codex session
--network Enable danger-full-access sandbox for tasks that need broader shell accessWorkflow Overview
User Request → Generate Task Name → Create .autonomous/<task-name>/ → Execute Codex Sessions
↓
┌───────────────┐
│ task_list.md │
│ exists? │
└───────┬───────┘
│
┌───────────────────────┴───────────────────────┐
│ NO YES │
▼ ▼
┌───────────────┐ ┌───────────────┐
│ INITIALIZER │ │ EXECUTOR │
│ - Analyze │ │ - Read state │
│ - Break down │ │ - Next task │
│ - Create │ │ - Implement │
│ task_list │ │ - Mark done │
└───────────────┘ └───────────────┘
│
▼
┌───────────────┐
│ All complete? │
└───────┬───────┘
│
┌───────────────┴───────────────┐
│ NO YES │
▼ ▼
Auto-continue Exit with success
(3 sec delay)Usage Examples
Example 1: Start New Task
~/.codex/skills/autonomous-skill/scripts/run-session.sh "Build a REST API for todo app"Output:
ℹ Generated task name: build-rest-api-todo
==========================================
SESSION 1 - build-rest-api-todo
==========================================
==========================================
INITIALIZER SESSION
==========================================
Task: Build a REST API for todo app
Task Name: build-rest-api-todo
Task Directory: .autonomous/build-rest-api-todo
[Codex creates task_list.md with 25 tasks...]
✓ Initializer session complete
ℹ Session ID saved: 550e8400-e29b-41d4-a716-446655440000
=== Progress: 0/25 ===
Continuing in 3 seconds... (Press Ctrl+C to pause)Example 2: Continue Existing Task
~/.codex/skills/autonomous-skill/scripts/run-session.sh --task-name build-rest-api-todo --continueExample 3: Resume with Session Context
# Resume the Codex session (preserves conversation context)
~/.codex/skills/autonomous-skill/scripts/run-session.sh --task-name build-rest-api-todo --continue --resume-lastExample 4: List All Tasks
~/.codex/skills/autonomous-skill/scripts/run-session.sh --listOutput:
==========================================
AUTONOMOUS TASKS
==========================================
✓ build-rest-api-todo (25/25 - 100% complete) [session: 550e8400...]
○ refactor-auth (12/30 - 40%) [session: 661f9511...]
? incomplete-task (no task_list.md)Example 5: With Network Access
# Enable network access for tasks that need API calls
~/.codex/skills/autonomous-skill/scripts/run-session.sh --network "Fetch data from GitHub API and analyze"Key Files
For each task in .autonomous/<task-name>/:
| File | Purpose | |------|---------| | task_list.md | Master task list with checkbox progress | | progress.md | Session-by-session progress notes | | session.id | Last Codex session ID for resumption | | session.log | JSON Lines output from Codex sessions |
Important Notes
- Task Isolation: Each task has its own directory, no conflicts
- Task Naming: Auto-generated from description (lowercase, hyphens, max 30 chars)
- Task List is Sacred: Never delete or modify task descriptions, only mark
[x] - One Task at a Time per Session: Focus on completing tasks thoroughly
- Auto-Continue: Sessions auto-continue with 3s delay; Ctrl+C to pause
- Session Resumption: Use
--resume-lastto preserve Codex conversation context - Configured Model: The runner does not pass
--model; it uses the active Codex config/profile model - Network Mode:
--networkswitches the sandbox override todanger-full-accesswhile keeping approval policy non-interactive - Git Hygiene: Consider adding
.autonomous/to.gitignoreto avoid committing logs
Codex CLI Reference
The script uses these Codex commands internally. It intentionally uses config overrides instead of --full-auto so unattended runs do not inherit on-request approvals from the current CLI: