autonomous-skill - Claude MCP Skill

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