Help us improve
Share bugs, ideas, or general feedback.
From octo
Manages tasks using native Claude Code subagent tools (TaskCreate, TaskUpdate, TaskList, TaskGet). Tracks TODOs, checkpoints progress, and resumes work across sessions.
npx claudepluginhub nyldn/claude-octopus --plugin octoHow this skill is triggered — by the user, by Claude, or both
Slash command
/octo:skill-task-managementThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex.
Executes eligible tasks from session task list, syncs against codebase/PR state to surface stales, and generates handovers. Use /task-run [--all] [--sync [--dry-run]] [--handover [query]].
Share bugs, ideas, or general feedback.
Host: Codex CLI — This skill was designed for Claude Code and adapted for Codex. Cross-reference commands use installed skill names in Codex rather than
/octo:*slash commands. Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it. For host tool equivalents, seeskills/blocks/codex-host-adapter.md.
Systematic task orchestration for multi-step work, progress checkpointing, and seamless task resumption across sessions.
Core principle: Track → Checkpoint → Resume → Complete.
v7.23.0 Migration: This skill now uses native Claude Code host subagent tools:
TaskCreate - Create new tasksTaskUpdate - Update task status/detailsTaskList - View all tasksTaskGet - Get specific task detailsBenefits:
Use this skill when user wants to:
Do NOT use for:
When user says "add to the todo's" or similar:
**What would you like to add to the todo list?**
I'll help you capture this task. Please provide:
- Task description (what needs to be done)
- Any dependencies or prerequisites
- Priority (if applicable)
After getting details, use TaskCreate to add:
TaskCreate({
subject: "[Brief task description]",
description: "[Detailed description including dependencies and context]",
activeForm: "Working on [task description]"
})
Then confirm to user:
✅ Task created: [Task description]
View all tasks with TaskList or use /tasks command.
When user says "save progress" or "checkpoint this":
# Check git status
git status
# Check current branch
git branch --show-current
# Check uncommitted work
git diff --stat
Option A: Git-based checkpoint (if git repo)
# Create a work-in-progress commit
git add .
git commit -m "WIP: [description of current state]
Progress checkpoint - work in progress
Not ready for review or merge
Current state:
- [What's completed]
- [What's in progress]
- [What's next]
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
Option B: Task-based checkpoint (preferred for tracking)
Create checkpoint task with detailed state:
TaskCreate({
subject: "Checkpoint: [Brief description]",
description: `
📍 CHECKPOINT: ${new Date().toISOString()}
Completed:
✓ [Task 1]
✓ [Task 2]
In Progress:
⚙️ [Current task with details]
Next Steps:
- [ ] [Next task 1]
- [ ] [Next task 2]
- [ ] [Next task 3]
Context:
- Branch: ${branchName}
- Last commit: ${lastCommit}
- Files changed: ${filesChanged}
`,
activeForm: "Checkpoint saved"
})
Mark completed tasks as done:
// For each completed task
TaskUpdate({
taskId: "[task-id]",
status: "completed"
})
Mark current task as in_progress:
TaskUpdate({
taskId: "[current-task-id]",
status: "in_progress"
})
✅ Progress saved!
To resume this work:
1. Run: git checkout [branch-name]
2. View tasks: TaskList
3. Say: "resume tasks" or "pick up where we left off"
Current state:
- Branch: [branch-name]
- Tasks: [X completed, Y in progress, Z pending]
- Last checkpoint: [timestamp]
When user says "resume tasks" or "pick up where we left off":
// Get all tasks
const tasks = TaskList()
// Filter by status
const completed = tasks.filter(t => t.status === 'completed')
const inProgress = tasks.filter(t => t.status === 'in_progress')
const pending = tasks.filter(t => t.status === 'pending')
// Find checkpoint task (if exists)
const checkpoint = tasks.find(t => t.subject.startsWith('Checkpoint:'))
# Check for WIP commits
git log --oneline -10 | grep WIP
# Check current branch
git branch --show-current
# Check git status
git status
📋 **Resuming from last checkpoint**
**Branch:** [branch-name]
**Last checkpoint:** [timestamp from WIP commit or checkpoint task]
**Completed:** (${completed.length} tasks)
${completed.map(t => `✓ ${t.subject}`).join('\n')}
**In Progress:** (${inProgress.length} tasks)
${inProgress.map(t => `⚙️ ${t.subject}`).join('\n')}
**Next Steps:** (${pending.length} tasks)
${pending.map((t, i) => `${i + 1}. [ ] ${t.subject}`).join('\n')}
**Would you like me to:**
1. Continue with the next task?
2. Modify the plan?
3. See more details about current state?
If "continue with next task" → Get first pending task, mark as in_progress, and begin work:
const nextTask = pending[0]
TaskUpdate({ taskId: nextTask.id, status: 'in_progress' })
// Begin working on nextTask
If "modify the plan" → Use AskUserQuestion to understand changes, then update tasks
If "see more details" → Show git diff, file changes, recent commits, task descriptions
When user says "proceed to next steps":
const tasks = TaskList()
const currentTask = tasks.find(t => t.status === 'in_progress')
if (currentTask) {
console.log(`Current task: ${currentTask.subject}`)
console.log(`Status: ${currentTask.status}`)
}
// Mark current task as complete
if (currentTask) {
TaskUpdate({
taskId: currentTask.id,
status: 'completed'
})
console.log(`✓ ${currentTask.subject}`)
}
// Get next pending task
const nextTask = tasks.find(t => t.status === 'pending' && !t.blockedBy?.length)
if (nextTask) {
// Mark as in progress
TaskUpdate({
taskId: nextTask.id,
status: 'in_progress'
})
console.log(`\n⚙️ ${nextTask.subject}`)
console.log(`\nProceeding with: ${nextTask.description}`)
}
Begin working on the next task immediately after marking it as in_progress.
If you have existing .claude/todos.md or similar files:
# Run migration script
"${HOME}/.claude-octopus/plugin/scripts/migrate-todos.sh"
This will:
.claude/archived-todos/For each todo item in your .md file:
<!-- Old format in todos.md -->
- [ ] Implement user authentication
- [x] Set up database
- [ ] Create API endpoints
Convert to:
// New format using native tasks
TaskCreate({
subject: "Implement user authentication",
description: "Create auth system with JWT tokens",
activeForm: "Implementing authentication"
})
TaskCreate({
subject: "Set up database",
description: "Configure PostgreSQL and run migrations",
activeForm: "Setting up database"
})
// Mark as completed since it was [x]
TaskUpdate({ taskId: "...", status: "completed" })
TaskCreate({
subject: "Create API endpoints",
description: "Build REST API for user operations",
activeForm: "Creating API endpoints"
})
Opt-out for users who prefer old system:
Create .claude/claude-octopus.local.md with:
use_native_tasks: false
# Claude Octopus Local Configuration
This project uses legacy task plan tool tool instead of native Task management.
When use_native_tasks: false, skill falls back to task plan tool behavior.
User: "save progress and prepare for PR"
1. Use skill-task-management to checkpoint (create tasks for current state)
2. Then use skill-finish-branch to prepare PR
User: "add implementation of auth system to todos"
1. Use skill-task-management to add high-level task
2. Use flow-develop to break down and implement
3. Update tasks as work progresses
User: "checkpoint this, I found a bug"
1. Use skill-task-management to save current progress (checkpoint task)
2. Use skill-debug to investigate the bug
3. Return to saved checkpoint after fix
Good task:
TaskCreate({
subject: "Implement token refresh with 15-minute expiration",
description: `
Create token refresh endpoint that:
- Validates refresh token from secure HTTP-only cookie
- Issues new access token with 15min expiry
- Rotates refresh token for security
- Returns 401 if refresh token invalid/expired
Dependencies: OAuth provider setup must be complete
`,
activeForm: "Implementing token refresh logic"
})
Poor task:
TaskCreate({
subject: "Do auth stuff",
description: "Fix things",
activeForm: "Working"
})
For tasks with prerequisites:
// First task
TaskCreate({
subject: "Set up OAuth provider configuration",
description: "Configure Auth0 application settings",
activeForm: "Configuring OAuth provider"
})
// Dependent task
TaskCreate({
subject: "Implement token refresh endpoint",
description: "Create /auth/refresh endpoint",
activeForm: "Implementing refresh endpoint",
addBlockedBy: ["1"] // Blocked by task #1
})
When checkpointing, always include:
Example checkpoint task:
TaskCreate({
subject: "Checkpoint: Auth implementation 70% complete",
description: `
📍 CHECKPOINT: 2026-02-03T14:30:00Z
Completed:
✓ OAuth provider configuration (Auth0)
✓ Token exchange endpoint (/auth/login)
✓ User session middleware
In Progress:
⚙️ Token refresh logic (70% done)
- Validation complete
- Token rotation TODO
- Cookie handling TODO
Next:
- [ ] Complete token rotation logic
- [ ] Add logout endpoint
- [ ] Add session expiration handling
- [ ] Write integration tests
Branch: feature/auth-system
Last commit: abc123f "Add session middleware"
Decisions Made:
- Using Auth0 (rationale: enterprise-grade, handles complexity)
- 15-minute access token expiry (security vs UX balance)
- HTTP-only cookies for refresh tokens (XSS protection)
`,
activeForm: "Checkpoint saved"
})
User: "save progress, I'm done for today"
Action:
1. Create WIP commit with current state
2. Create checkpoint task with completed/pending breakdown
3. Mark in-progress tasks with current status
4. Provide resume instructions for tomorrow
User: "checkpoint this, need to work on something else"
Action:
1. Save current branch state (WIP commit)
2. Create checkpoint task with detailed context
3. Mark current task as pending (will resume later)
4. Ready for resume when user returns
User: "save progress for Claude to pick up"
Action:
1. Create comprehensive checkpoint task
2. Document all context and decisions
3. Mark in-progress tasks with current state
4. Ensure new session can load task state and resume seamlessly
| Action | Why It's Wrong |
|---|---|
| Checkpoint without documenting context | Next session won't know what was happening |
| Skip WIP commit for code changes | Lose work if something breaks |
| Generic "proceed to next" without checking TaskList | Might skip incomplete work |
| Vague task subjects/descriptions | Unclear what needs to be done |
| Resume without showing TaskList state | User doesn't know where they are |
| Create tasks without activeForm | No progress indication in UI |
| User Intent | Skill Action | Tool Used |
|---|---|---|
| "add to todos" | Gather details, create task | TaskCreate |
| "save progress" | Create checkpoint task + WIP commit | TaskCreate + git |
| "resume tasks" | Load task state, show status, ask direction | TaskList |
| "proceed to next" | Complete current, start next | TaskUpdate |
| "checkpoint this" | Create detailed checkpoint task | TaskCreate |
pending → in_progress → completed
↓
deleted (if no longer needed)
Best practices:
pending statein_progress when starting workcompleted only when fully donedeleted for cancelled/obsolete tasksTask management → Clear state + Easy resume + Native UI
Otherwise → Lost context + Duplicate work + No visibility
Track everything. Checkpoint frequently. Resume seamlessly. Use native tools.
// User: "add implementing auth to my todos"
// Step 1: Create main task
TaskCreate({
subject: "Implement user authentication system",
description: `
Build complete auth system with:
- OAuth 2.0 (Auth0 provider)
- JWT token management
- Refresh token rotation
- Session middleware
- Logout functionality
`,
activeForm: "Planning authentication implementation"
})
// User works on it...
// User: "save progress for tomorrow"
// Step 2: Create checkpoint
TaskCreate({
subject: "Checkpoint: Auth implementation in progress",
description: `
📍 Checkpoint: 2026-02-03T18:30:00Z
Completed:
✓ OAuth configuration
✓ Login endpoint
In Progress:
⚙️ Token refresh (50%)
Next:
- [ ] Complete refresh logic
- [ ] Add logout
- [ ] Write tests
Branch: feature/auth
Commit: abc123f
`,
activeForm: "Checkpoint saved"
})
// Step 3: Update main task status
TaskUpdate({
taskId: "1",
status: "in_progress"
})
// User: "resume tasks" (next day)
// Step 4: Load and present state
const tasks = TaskList()
// Present: "You have 1 in_progress task, last checkpoint 2026-02-03T18:30:00Z"
// Show details from checkpoint task
// User: "continue"
// Step 5: Resume work
const currentTask = tasks.find(t => t.status === 'in_progress')
// Begin working on token refresh where they left off