---

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

$3

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.

$3

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

$3

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

$3

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

$3

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

---

Installation

``bash
npx oki-task install
`

Interactive mode guides you through setup. Or use flags:

`bash


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
`

$3

Claude Code

Add to ~/.claude.json:

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

opencode

Add to your opencode configuration:

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

---

Quick Start

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

`markdown
- [ ] 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

$3

GitHub-style checkboxes:
`markdown
- [ ] Create user model with email validation
- [ ] Implement login endpoint
- [x] Already completed task
`

Plain lists work too:
`markdown
- Create user model with email validation
- Implement login endpoint
- Add session management
`

Numbered lists:
`markdown
1. Create user model
2. Implement login endpoint
3. Add session management
`

$3

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

$3

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

Detailed Tool Documentation

$3

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

---

$3

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

---

$3

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

---

$3

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

---

$3

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

---

$3

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

---

$3

User provides an answer to a clarification.

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

---

$3

Retrieves clarification history.

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

---

$3

Gets comprehensive execution summary.

Parameters:
- stateDir (string, optional): State directory

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

---

$3

Gets current execution status.

Parameters:
- stateDir (string, optional): State directory

---

$3

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

MCP connection issues

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

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

Git checkpoint not created

Ensure you're in a git repository with at least one commit:
`bash
git init
git add .
git commit -m "Initial commit"
`

Tasks not detected

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

---