An MCP (Model Context Protocol) server for coordinating agentic work through projects, tasks, and threads with evolved prompts.
taskhelix gives any MCP-compatible agent a structured way to break work into tasks, track dependencies, and spawn subagent threads with accumulated context — each thread inherits the wisdom of all previous work.
A work session derived from a PRD (Product Requirements Document). Contains tasks and threads.
A unit of work parsed from a PRD. Each task has a status: pending, in_progress, completed, or failed. Tasks can declare dependencies on other tasks.
A subagent or worker that receives an evolved prompt containing:
- The original intent
- Previous thread reports (accumulated context)
- Completed tasks (preserved work)
This gives subagents the context they need without re-explaining everything from scratch.
The core primitive. When a thread starts, it receives a prompt containing context from all previous work. This accumulates wisdom across threads — each new thread builds on what came before.
MCP Client (Claude, opencode, etc.)
│
▼
┌────────────┐
│ taskhelix │ ◄── stdio transport, single client
└────────────┘
│
▼
Agent(s) ◄── Main agent + Subagent threads
Harness A ──┐ ┌── Harness B
(MCP) │ │ (MCP)
▼ ▼
┌──────────────────────────────┐
│ taskhelix (HTTP) │ ◄── Streamable HTTP + SSE
│ your-host:8642/mcp │
└──────────────────────────────┘
│
store.db (SQLite + WAL)
| Tool | Description |
|---|---|
project_start |
Start a new project from a PRD (file or inline content) |
project_status |
Get current status of a project (tasks, threads, progress) |
project_list |
List all projects |
project_merge |
Complete a project (verifies all tasks are done) |
project_stuck |
Signal that work is blocked |
project_log |
Add a timestamped log entry |
project_logs |
Retrieve logs, optionally filtered by task |
| Tool | Description |
|---|---|
task_pick |
Claim a task (validates dependencies) |
task_complete |
Mark a task done with evidence |
task_fail |
Mark a task as failed with a reason |
task_add |
Add a new task mid-project |
task_update |
Update task title, description, or dependencies |
| Tool | Description |
|---|---|
thread_start |
Start a new thread with an evolved prompt |
thread_report |
Report progress from a thread (returns next evolved prompt) |
| Tool | Description |
|---|---|
budget_set |
Set the call budget for an API key |
budget_status |
Check remaining budget for an API key |
go install github.com/mythosxyz/taskhelix-mcp@latestOr build from source:
git clone https://github.com/mythosxyz/taskhelix-mcp.git
cd taskhelix-mcp
go build -o taskhelixFor a single agent on the same machine. Add to your MCP client configuration:
{
"mcpServers": {
"taskhelix": {
"command": "/path/to/taskhelix",
"env": {
"TASKHELIX_STORE_PATH": "/path/to/store.db"
}
}
}
}Default store path: ~/.taskhelix/store.db
Run a single taskhelix server that multiple agents connect to over HTTP:
# Start the server
TASKHELIX_HTTP_ADDR=":8642" \
TASKHELIX_API_KEY="your-secret-key" \
TASKHELIX_STORE_PATH="/shared/taskhelix/store.db" \
./taskhelixThen configure each remote MCP client:
{
"mcpServers": {
"taskhelix": {
"url": "http://your-host:8642/mcp",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer your-secret-key"
}
}
}
}The X-Budget-Remaining header is returned on every POST response, so agents can self-regulate their usage.
When TASKHELIX_API_KEY is set, every tool call costs 1 budget unit. Use budget_set to allocate a call budget per key:
Agent calls: budget_set(api_key="helix", total=500)
→ Agent has 500 calls. Each POST decrements the counter.
→ When budget hits 0, the next call returns HTTP 402 Payment Required.
→ Agent sees X-Budget-Remaining header on every response.
If no budget row exists for a key, calls are unlimited.
| Variable | Default | Description |
|---|---|---|
TASKHELIX_HTTP_ADDR |
(empty) | Set to ":port" or "host:port" to enable HTTP mode. Omit for stdio. |
TASKHELIX_HTTP_PATH |
/mcp |
HTTP endpoint path |
TASKHELIX_API_KEY |
(empty) | Bearer token for auth + budget tracking. |
TASKHELIX_STORE_PATH |
~/.taskhelix/store.db |
Path to the SQLite database |
taskhelix parses markdown PRDs for tasks. Supported formats:
- [ ] Implement user authentication
> Requires OAuth2 integration
- [ ] Create dashboard
- [x] Database schema (already done)## Task: User Login
Implement the login flow with email and password.
Include password reset functionality.
## Task: API Rate Limiting
Add rate limiting to all public endpoints.If no tasks are found, the entire PRD becomes a single task: "Complete PRD objectives".
Tasks can declare dependencies using a Depends on: line:
- [ ] Setup database
- [ ] Create API
> Depends on: Setup database
- [ ] Build UI
> Depends on: Create APIDependencies are matched by task title (case-insensitive). task_pick enforces that all dependencies are completed before a task can be claimed.
When a thread starts, it receives a prompt containing context from all previous work:
# Primary Objective
Implement the dashboard UI
# Previous Thread Reports
## Thread proj_a1b2c3 (Intent: Auth module)
Completed OAuth integration. Session tokens stored in Redis.
# Completed Tasks (Preserve This Work)
- task_d4e5f6: Implement user authentication
# Remaining Tasks
- [pending] task_g7h8i9: Create dashboard (depends: none)
# Current Context
Project ID: proj_a1b2c3
PRD: /path/to/prd.mdOlder threads are automatically summarized to keep the prompt within context limits. The 3 most recent threads get full reports, up to 10 older threads get summaries, and anything beyond that is omitted.
User: Start a project from ./feature-prd.md
Agent: [calls project_start with prd_content]
Project started: proj_93b6f6
Tasks:
[pending] task_b11cc9: Write tests
[pending] task_9b015d: Deploy
Agent: [calls task_pick for task_b11cc9]
Agent: [works on tests]
Agent: [calls task_complete with evidence]
Completed: task_b11cc9
Progress: 1/2 tasks
Agent: [calls thread_start to spawn subagent for deployment]
Subagent receives evolved prompt with test work context
Agent: [continues work, completes remaining tasks]
Agent: [calls project_merge]
Project merged successfully. 2 tasks completed, 0 tasks failed.
All project state is persisted to SQLite with WAL mode, which provides safe concurrent reads and writes without file-level locking. This handles multiple fast agents hammering the store simultaneously — SQLite serializes writes at the database level while allowing concurrent reads.
In HTTP mode, the database lives on the server — all clients read and write through the central instance. No file syncing needed.
- Evolved prompts preserve context — Subagents inherit accumulated wisdom from previous threads. This is the core primitive.
- Agent self-reports progress — No polling. The agent calls tools to update state.
- Stuck ≠ failed — Signals are for communication, not punishment. A stuck project can be unblocked and resumed.
- Human-in-the-loop friendly — Jump in anytime with guidance or check progress.
- Dependency enforcement — Tasks can only be picked when their dependencies are satisfied.
- Budget as identity — The API key authenticates AND tracks spend. No separate metering needed.
Apache License 2.0 — see LICENSE.