Batch task executor for AI coding assistants with git checkpoints, context sharing, and persistent clarifications
npm install oki-taskBatch 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
---
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.
---
---
``bash`
npx oki-task install
Interactive mode guides you through setup. Or use flags:
`bashInstall for specific platforms
npx oki-task install --claude # Claude Code only
npx oki-task install --opencode # opencode only
$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 directoryReturns: 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 directoryReturns: 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 directoryReturns: 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)---
| Platform | Status |
|----------|--------|
| Claude Code | Fully supported |
| opencode | Fully supported |
---
Contributions welcome! Please open an issue or submit a pull request.
---
MIT - Stefano De Cillis
---
Built for the Model Context Protocol ecosystem