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.
- Installs
- 121
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/feiskyer/codex-settings --skill autonomous-skill- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads autonomous-skill automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 --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:
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 access
Workflow 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 --continue
Example 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-last
Example 4: List All Tasks
~/.codex/skills/autonomous-skill/scripts/run-session.sh --list
Output:
==========================================
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:
# 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 |
FAQ
What does the autonomous-skill skill do?
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.
How do I install autonomous-skill?
Run npx skills add https://github.com/feiskyer/codex-settings --skill autonomous-skill in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/autonomous-skill/ (personal) or .claude/skills/autonomous-skill/ (project).
Which AI agents can use autonomous-skill?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is autonomous-skill safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains autonomous-skill?
It is published by feiskyer in feiskyer/codex-settings. It has 121 recorded installs.
More from feiskyer/codex-settings
deep-research
feiskyer/codex-settings
Open the skill to read its SKILL.md instructions.
nanobanana-skill
feiskyer/codex-settings
Open the skill to read its SKILL.md instructions.
youtube-transcribe-skill
feiskyer/codex-settings
Open the skill to read its SKILL.md instructions.
spec-kit-skill
feiskyer/codex-settings
Open the skill to read its SKILL.md instructions.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.