Agent skill

autonomous-skill

Use when work must continue across multiple Codex sessions with `.autonomous/` tracking, resumable execution, or autonomous handoff. Use for long-running, multi-session, or resume-later tasks.

View SKILL.md on GitHub Repository
Stars 168
Forks 27

Install this agent skill to your Project

npx add-skill https://github.com/feiskyer/codex-settings/tree/main/skills/autonomous-skill

SKILL.md

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:

bash
# 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 --help

The 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:

text
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

text
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 access

Workflow Overview

text
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

bash
~/.codex/skills/autonomous-skill/scripts/run-session.sh "Build a REST API for todo app"

Output:

text
ℹ 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

bash
~/.codex/skills/autonomous-skill/scripts/run-session.sh --task-name build-rest-api-todo --continue

Example 3: Resume with Session Context

bash
# Resume the Codex session (preserves conversation context)
~/.codex/skills/autonomous-skill/scripts/run-session.sh --task-name build-rest-api-todo --continue --resume-last

Example 4: List All Tasks

bash
~/.codex/skills/autonomous-skill/scripts/run-session.sh --list

Output:

text
==========================================
  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

bash
# 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

  1. Task Isolation: Each task has its own directory, no conflicts
  2. Task Naming: Auto-generated from description (lowercase, hyphens, max 30 chars)
  3. Task List is Sacred: Never delete or modify task descriptions, only mark [x]
  4. One Task at a Time per Session: Focus on completing tasks thoroughly
  5. Auto-Continue: Sessions auto-continue with 3s delay; Ctrl+C to pause
  6. Session Resumption: Use --resume-last to preserve Codex conversation context
  7. Configured Model: The runner does not pass --model; it uses the active Codex config/profile model
  8. Network Mode: --network switches the sandbox override to danger-full-access while keeping approval policy non-interactive
  9. Git Hygiene: Consider adding .autonomous/ to .gitignore to 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:

bash
# Non-interactive execution with file edits (fully autonomous)
# Uses the configured model from the active Codex config/profile
codex exec \
  -c 'approval_policy="never"' \
  -c 'sandbox_mode="workspace-write"' \
  --skip-git-repo-check \
  --json \
  "prompt"

# Resume previous session
codex exec resume \
  -c 'approval_policy="never"' \
  -c 'sandbox_mode="workspace-write"' \
  --skip-git-repo-check \
  --json \
  <SESSION_ID> \
  "prompt"

# Full access (file edits + shell network / unrestricted filesystem) - use with caution!
codex exec \
  -c 'approval_policy="never"' \
  -c 'sandbox_mode="danger-full-access"' \
  --skip-git-repo-check \
  --json \
  "prompt"

Troubleshooting

Issue Solution
Task not found Run --list to see existing tasks
Multiple tasks Specify task name with --task-name
Session stuck Check session.log in task directory
Need to restart Delete task directory and start fresh
Resume failed Remove session.id to start fresh session
Run paused for approval Ensure the updated runner is using -c approval_policy="never" overrides
Codex not found Install Codex CLI: npm install -g @openai/codex

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

feiskyer/codex-settings

kiro-skill

Interactive feature development workflow from idea to implementation. Creates requirements (EARS format), design documents, and implementation task lists. Use when creating feature specs, requirements documents, design documents, or implementation plans. Triggered by "kiro" or references to .kiro/specs/ directory.

168 27
Explore
feiskyer/codex-settings

deep-research

深度调研的多实例（多 Agent）编排工作流：把一个调研目标拆成可并行子目标，用 Codex CLI（`codex exec`）在默认 `workspace-write` 沙箱内运行子进程；联网与采集优先使用已安装的 skills，其次使用 MCP 工具；用脚本聚合子结果并分章精修，最终交付“成品报告文件路径 + 关键结论/建议摘要”。用于：系统性网页/资料调研、竞品/行业分析、批量链接/数据集分片检索、长文写作与证据整合，或用户提及“深度调研/Deep Research/Wide Research/多 Agent 并行调研/多进程调研”等场景。

168 27
Explore
feiskyer/codex-settings

spec-kit-skill

GitHub Spec-Kit integration for constitution-based spec-driven development. 7-phase workflow (constitution, specify, clarify, plan, tasks, analyze, implement). Use when working with spec-kit CLI, .specify/ directories, or creating specifications with constitution-driven development. Triggered by "spec-kit", "speckit", "constitution", "specify", references to .specify/ directory, or spec-kit commands.

168 27
Explore
feiskyer/codex-settings

youtube-transcribe-skill

Extract subtitles/transcripts from a YouTube video URL and save as a local file. Use when you need to extract subtitles from a YouTube video.

168 27
Explore
feiskyer/codex-settings

nanobanana-skill

Generate, remix, or edit images with Nanobanana / Nano Banana 2 through the bundled Gemini CLI wrapper. Use this whenever the user wants AI image generation or editing, especially for reference-image composition, character consistency, grounded visuals that may need live web search, style transfer, marketing graphics, product mockups, social assets, or when they explicitly mention Nanobanana, Gemini image models, Google image generation, AI drawing, 图片生成, AI绘图, 图片编辑, or 生成图片.

168 27
Explore
feiskyer/codex-settings

claude-skill

Use when work should be delegated to Claude Code CLI, especially headless `claude -p` runs, automation scripts, CI jobs, resumable sessions, or requests to use Claude/Claude Code for a task.

168 27
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results