oki-task

Batch Task Execution with Surgical Precision for AI Coding Assistants

Transform your AI assistant into a methodical task executor with git safety nets, context sharing, and persistent clarifications.

Installation · Quick Start · Features · Task Formats · MCP Tools

Why oki-task?

Just drop a list of tasks and let your AI handle it.

No babysitting. No copy-pasting one task at a time. Write your tasks, point your AI assistant at them, and walk away.

But AI coding assistants struggle with multi-step projects:

• Context loss across conversations resets progress
• No rollback when tasks fail mid-execution
• Ambiguous tasks lead to incorrect implementations
• No progress visibility on large task lists

oki-task solves all of this — letting AI work autonomously through your entire task list.

Features

Intelligent Task Grouping

Automatically detects related tasks and shares context between them. When you complete "Create UserAuth component", the next task "Add UserAuth validation" already knows what was built.

Git Checkpoints

Creates rollback points before each task. If something goes wrong, surgically undo just that task's changes—not your entire session.

Persistent Clarifications

AI asks questions when tasks are unclear. Your answers are saved and survive context resets, so you never repeat yourself.

Progress Tracking

Real-time status showing task N of M, completion stats, and what's blocking progress.

Comprehensive Summaries

Final reports showing what was accomplished, what failed, and actionable next steps.

Installation

npx oki-task install

Interactive mode guides you through setup. Or use flags:

# Install for specific platforms
npx oki-task install --claude     # Claude Code only
npx oki-task install --opencode   # opencode only

# Installation scope
npx oki-task install --global     # User-level config
npx oki-task install --local      # Project-level config

Manual Installation

Add to ~/.claude.json:

{
  "mcpServers": {
    "oki-task": {
      "command": "npx",
      "args": ["-y", "oki-task@latest", "mcp"]
    }
  }
}

Add to your opencode configuration:

{
  "mcp": {
    "oki-task": {
      "command": "npx",
      "args": ["-y", "oki-task@latest", "mcp"]
    }
  }
}

Quick Start

1. Create a task file (tasks.md):

- [ ] Create user authentication module with JWT
- [ ] Add password reset flow with email verification
- [ ] Implement rate limiting on auth endpoints

2. Ask your AI assistant:

"Load tasks from tasks.md and execute them"

3. Watch it work: The AI parses tasks, creates git checkpoints, and executes sequentially with full context sharing.

Task Formats

Markdown (Recommended)

GitHub-style checkboxes:

- [ ] Create user model with email validation
- [ ] Implement login endpoint
- [x] Already completed task

Plain lists work too:

- Create user model with email validation
- Implement login endpoint
- Add session management

Numbered lists:

1. Create user model
2. Implement login endpoint
3. Add session management

YAML

tasks:
  - title: Create user model
    description: Include email validation and password hashing
  - title: Implement login endpoint
  - title: Add session management

JSON

{
  "tasks": [
    { "title": "Create user model", "description": "Include validation" },
    { "title": "Implement login endpoint" },
    { "title": "Add session management" }
  ]
}

MCP Tools Reference

| Tool | Description | |------|-------------| | list_tasks | Parse task file, detect groups, initialize state | | get_status | Current execution status and progress | | start_task | Begin task with git checkpoint | | complete_task | Mark complete, update shared context | | fail_task | Mark failed with optional git rollback | | skip_task | Skip task with reason | | request_clarification | AI asks user for clarification | | provide_answer | User answers clarification | | get_clarifications | Retrieve Q&A history (persists across sessions) | | get_summary | Comprehensive execution report | | test | Verify MCP connection |

list_tasks

Parses a task file and initializes execution state.

Parameters:

• filePath (string, required): Path to task file
• stateDir (string, optional): State directory (default: .oki-task)

Returns: Task list with grouping analysis

start_task

Begins execution of a specific task. Creates a git checkpoint for rollback capability.

Parameters:

• taskId (string, required): Task identifier
• stateDir (string, optional): State directory

Returns: Task details, checkpoint info, shared context from related tasks

complete_task

Marks a task as successfully completed.

Parameters:

• taskId (string, required): Task identifier
• summary (string, optional): What was accomplished
• stateDir (string, optional): State directory

Returns: Next task info, progress update

fail_task

Marks a task as failed with optional rollback.

Parameters:

• taskId (string, required): Task identifier
• error (string, required): What went wrong
• retriable (boolean, optional): Can be retried (default: true)
• rollback (boolean, optional): Rollback git changes (default: true)
• stateDir (string, optional): State directory

skip_task

Skips a task with a reason.

Parameters:

• taskId (string, required): Task identifier
• reason (string, required): Why it's being skipped
• stateDir (string, optional): State directory

request_clarification

AI requests clarification from the user.

Parameters:

• taskId (string, required): Related task
• question (string, required): The question to ask
• options (string[], optional): Suggested answers
• stateDir (string, optional): State directory

provide_answer

User provides an answer to a clarification.

Parameters:

• clarificationId (string, required): Clarification to answer
• answer (string, required): The answer
• stateDir (string, optional): State directory

get_clarifications

Retrieves clarification history.

Parameters:

• taskId (string, optional): Filter by task
• includeAnswered (boolean, optional): Include answered (default: true)
• stateDir (string, optional): State directory

get_summary

Gets comprehensive execution summary.

Parameters:

• stateDir (string, optional): State directory

Returns: Execution status, per-task outcomes, next steps

get_status

Gets current execution status.

Parameters:

• stateDir (string, optional): State directory

test

Verifies MCP connection is working.

Returns: Status and version info

How It Works

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Task File     │────▶│    oki-task      │────▶│  AI Assistant   │
│  (md/yaml/json) │     │   MCP Server     │     │ (Claude/opencode)│
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                    ┌──────────────────────┐
                    │  - Git checkpoints   │
                    │  - Context sharing   │
                    │  - Clarification Q&A │
                    │  - Progress state    │
                    └──────────────────────┘

Execution Flow:

1. list_tasks parses your task file and groups related tasks
2. start_task creates a git checkpoint and begins execution
3. AI works on the task, can use request_clarification if needed
4. complete_task or fail_task records the outcome
5. If failed with rollback: true, changes are reverted
6. Repeat for remaining tasks
7. get_summary shows final report

State Persistence

Execution state is stored in .oki-task/ in your project:

.oki-task/
└── state.json    # Task progress, clarifications, groups

Add to .gitignore:

.oki-task/

Troubleshooting

Run the test tool:

Ask your AI: "Use the oki-task test tool"

Should return:

{
  "status": "ok",
  "version": "0.1.0",
  "message": "oki-task is working correctly"
}

Ensure you're in a git repository with at least one commit:

git init
git add .
git commit -m "Initial commit"

Check your task format. Supported patterns:

• - [ ] Task (checkbox)
• - Task (plain list)
• * Task (asterisk)
• 1. Task (numbered)

Supported Platforms

| Platform | Status | |----------|--------| | Claude Code | Fully supported | | opencode | Fully supported |

Contributing

Contributions welcome! Please open an issue or submit a pull request.

License

MIT - Stefano De Cillis

Back to top

Built for the Model Context Protocol ecosystem