VibeTasks MCP Server for Claude Code, Cursor, and AI coding tools. Status-based task management: todo → vibing → done.
npm install @vibetasks/mcp-servertodo -> vibing -> done - track what you're actively working on
taskflow login)
bash
Install globally from npm
npm install -g @vibetasks/mcp-server
Verify installation
vibetasks-mcp --version
`
$3
Edit your Claude Code config file:
- macOS/Linux: ~/.config/claude-code/config.json
- Windows: %APPDATA%\claude-code\config.json
`json
{
"mcpServers": {
"vibetasks": {
"command": "vibetasks-mcp",
"env": {
"TASKFLOW_SUPABASE_URL": "https://your-project.supabase.co",
"TASKFLOW_SUPABASE_KEY": "your-supabase-anon-key",
"ANTHROPIC_API_KEY": "sk-ant-your-key-here"
}
}
}
}
`
Note: ANTHROPIC_API_KEY is optional but required for RLM tools (rlm_query_codebase, rlm_get_codebase_stats). If not provided, only the 11 standard task tools will be available.
Environment Variables:
- TASKFLOW_SUPABASE_URL - Your Supabase project URL (required)
- TASKFLOW_SUPABASE_KEY - Your Supabase anon key (required)
- ANTHROPIC_API_KEY - Claude API key for RLM tools (optional)
- RLM_MAX_DEPTH - Max recursion depth for RLM (default: 3)
- RLM_VERBOSE - Enable RLM debug logs (default: false)
- RLM_SUB_MODEL - Model for RLM sub-queries (default: claude-haiku-4-5-20241022)
`json
`
Restart Claude Code after updating the config.
$3
If you're developing locally instead of using the npm package:
`bash
From the apps/mcp-server directory
npm install
npm run build
`
Then configure Claude Code with the full path:
`json
{
"mcpServers": {
"vibetasks": {
"command": "node",
"args": ["/absolute/path/to/taskflow/apps/mcp-server/dist/index.js"],
"env": {
"TASKFLOW_SUPABASE_URL": "https://your-project.supabase.co",
"TASKFLOW_SUPABASE_KEY": "your-supabase-anon-key"
}
}
}
}
`
$3
For automatic session logging (creates completed tasks when you end AI sessions):
`json
{
"mcpServers": {
"vibetasks": {
"command": "vibetasks-mcp",
"env": {
"TASKFLOW_SUPABASE_URL": "...",
"TASKFLOW_SUPABASE_KEY": "..."
}
}
},
"hooks": {
"SessionStart": [
{
"type": "command",
"command": "vibetasks-mcp",
"env": {
"CLAUDE_HOOK_TYPE": "SessionStart",
"TASKFLOW_SUPABASE_URL": "..."
}
}
],
"Stop": [
{
"type": "command",
"command": "vibetasks-mcp",
"env": {
"CLAUDE_HOOK_TYPE": "SessionEnd",
"TASKFLOW_SUPABASE_URL": "..."
}
}
]
}
}
`
Usage
$3
Access tools by typing @ in Claude Code:
#### create_task
Create a new task:
`
@vibetasks create_task
title: "Add authentication"
notes: "Implement OAuth with Supabase"
priority: "high"
due_date: "2026-01-15"
tags: ["backend", "security"]
`
#### create_task_with_subtasks
Create a parent task with subtasks in one call (perfect for TodoWrite integration):
`
@vibetasks create_task_with_subtasks
title: "Implement user authentication"
subtasks: ["Create login form", "Add API endpoints", "Implement JWT handling"]
priority: "high"
due_date: "2026-01-15"
tags: ["backend", "auth"]
`
Use case: When using Claude's TodoWrite feature, automatically mirror your todo list to VibeTasks for persistent tracking beyond the session.
#### Using Copyable Values in Instructions
When creating tasks with specific values users need to copy (app names, IDs, URLs, etc.), use markdown backticks in the instructions field to make values copyable with one click:
Example:
`typescript
{
title: "Create OAuth App",
instructions: "1. Go to Apple Developer Console\n2. Create app with name: VibeTasks\n3. Set Bundle ID: com.sparktory.vibetasks\n4. Save the App ID for later"
}
`
What the user sees:
- "Create app with name:" as plain text
- VibeTasks highlighted with a hover copy button
- com.sparktory.vibetasks highlighted with copy button
- "App ID" in bold (markdown)
Supported markdown in instructions:
- inline code → Copyable with button
- bold → Emphasized text
- italic → Italic text
- links → Clickable links
- ``code blocks` → Multi-line code
@vibetasks list_tasks status: "todo"
@vibetasks list_tasks status: "vibing"
@vibetasks list_tasks status: "done"
`
Status filters:
- todo - Tasks not yet started
- vibing - Tasks currently in progress
- done - Completed tasks
- (no filter) - All tasks
#### update_task
Update task properties including status:
`
@vibetasks update_task
task_id: "abc-123..."
title: "Updated title"
priority: "medium"
status: "vibing"
`
#### complete_task
Mark a task as done:
`
@vibetasks complete_task task_id: "abc-123..."
`
#### start_vibing
Mark a task as "vibing" (in progress). This sets the status to vibing and optionally adds context notes:
`
@vibetasks start_vibing
task_id: "abc-123..."
context_notes: "Working on the login form, need to add validation next"
`
WIP Limit Awareness: If you have 3+ tasks already in "vibing" status, the tool will warn you to finish existing work before starting new tasks.
#### get_vibing_tasks
Get all tasks currently in "vibing" (in progress) status:
`
@vibetasks get_vibing_tasks
`
Returns tasks you're actively working on, along with their context notes showing where you left off.
#### set_context_notes
Update the "where I left off" notes for a task:
`
@vibetasks set_context_notes
task_id: "abc-123..."
context_notes: "Finished the API, need to wire up the frontend next"
`
Use this to capture your progress before switching tasks or ending a session.
#### delete_task
Delete a task:
`
@vibetasks delete_task task_id: "abc-123..."
`
#### search_tasks
Search by title:
`
@vibetasks search_tasks query: "authentication" limit: 10
`
#### log_ai_session
Manually log a session:
`
@vibetasks log_ai_session
summary: "Implemented user authentication"
files: ["auth.ts", "login.tsx"]
duration_minutes: 45
`
$3
RLM tools enable querying massive codebases (10M+ tokens) with no context window limits. Based on MIT's RLM paper, these tools treat your codebase as an external environment that can be recursively explored.
#### rlm_query_codebase
Query your entire codebase with complex questions:
`
@vibetasks rlm_query_codebase
query: "How does user authentication work from login button to database?"
focused: true
maxFiles: 100
`
Parameters:
- query (required): Your question about the codebase
- focused (default: true): Pre-filter relevant files using semantic search (faster, cheaper)
- maxFiles (default: 100): Maximum files to include in focused mode
- verbose (default: false): Show detailed execution logs
- maxDepth (default: 3): Maximum recursion depth
Example Queries:
- "List all API endpoints with their HTTP methods and routes"
- "Find all TODO and FIXME comments grouped by priority"
- "What files depend on UserService and how do they use it?"
- "How does the payment flow work end-to-end?"
- "Find all database queries that don't use prepared statements"
Benefits:
- No context limits: Handles 10M+ tokens (thousands of files)
- Better accuracy: 29% more accurate than base LLM (MIT paper)
- Lower cost: 3x cheaper than loading full context
- No information loss: Uses recursive search, not summarization
Cost:
- Small codebase (~500k tokens): $0.01 - $0.05 per query
- Large codebase (10M tokens): $0.50 - $2.00 per query
- vs Base LLM: 15-60x cost reduction
How it works:
1. Loads codebase into Python REPL environment (not LLM context)
2. LLM writes Python code to search/filter context
3. LLM recursively calls itself on relevant chunks
4. Aggregates results and returns answer
#### rlm_get_codebase_stats
Get statistics about your codebase without running a query:
`
@vibetasks rlm_get_codebase_stats
`
Returns:
- File count
- Total size (bytes)
- Estimated tokens
- Estimated cost for RLM query
- Top file types
Use this before running expensive queries to understand scope.
#### rlm_clear_cache
Clear the RLM context cache to force reloading files:
`
@vibetasks rlm_clear_cache
`
Useful when files have changed and you want fresh context.
$3
Resources provide automatic context to AI:
- vibetasks://tasks/active - All incomplete tasks
- vibetasks://tasks/today - Tasks due today
- vibetasks://tasks/upcoming - Future tasks
- vibetasks://tasks/vibing - Tasks currently in progress (with context notes)
The AI can access these without explicit tool calls.
$3
VibeTasks uses a simple 3-state workflow:
`
todo -> vibing -> done
`
- todo: Task is captured but not started
- vibing: You're actively working on this task (WIP)
- done: Task is complete
Why "vibing"? It's a playful term for "work in progress" that fits the vibe coding culture. When you're vibing on a task, you're in the zone.
$3
Each task can have context notes that capture your progress:
`
@vibetasks set_context_notes
task_id: "abc-123..."
context_notes: "Finished auth API, need to add frontend form. Check auth.ts for the endpoint structure."
`
Context notes are shown when you:
- Call get_vibing_tasks - see where you left off on all active work
- Start a new session - AI sees your current context
- Switch between tasks - never lose your place
$3
When you create tasks, VibeTasks automatically detects your current project from git:
`bash
In a git repo with remote "github.com/user/my-project"
@vibetasks create_task title: "Fix bug"
Task is auto-tagged with "my-project"
`
This helps filter tasks by project when you have multiple codebases.
$3
When Claude Code hooks are configured:
1. SessionStart: Loads today's tasks as context
2. SessionEnd: Automatically creates a completed task summarizing your work
No manual intervention required!
$3
When Claude uses its built-in TodoWrite feature for multi-step tasks, it can automatically sync to TaskFlow:
How it works:
1. Claude creates a TodoWrite list for planning (ephemeral, session-only)
2. Claude calls create_task_with_subtasks to mirror the list in TaskFlow
3. Each todo becomes a persistent subtask
4. As Claude completes todos, it marks TaskFlow subtasks complete
5. Your tasks survive beyond the session and sync across all platforms
Example:
`
User: "Implement user authentication"
Claude creates TodoWrite:
1. Create login form component
2. Add authentication API endpoints
3. Implement JWT token handling
4. Add protected route middleware
Claude also calls create_task_with_subtasks:
{
title: "Implement user authentication",
subtasks: [
"Create login form component",
"Add authentication API endpoints",
"Implement JWT token handling",
"Add protected route middleware"
]
}
Result: Session todos + persistent TaskFlow task with subtasks
`
Development
$3
`bash
npm run dev
`
$3
`bash
npm run build
`
$3
`bash
Test STDIO communication
echo '{"method":"list_tools"}' | node dist/index.js
Test SessionStart hook
CLAUDE_HOOK_TYPE=SessionStart node dist/index.js
Test SessionEnd hook
CLAUDE_HOOK_TYPE=SessionEnd node dist/index.js
`
Troubleshooting
$3
1. Check config file location:
- macOS/Linux: ~/.config/claude-code/config.json
- Windows: %APPDATA%\claude-code\config.json
2. Verify vibetasks-mcp is installed: vibetasks-mcp --version
3. Check logs: Restart Claude Code with verbose logging
4. Verify authentication: vibetasks config
$3
`bash
Re-login to VibeTasks
vibetasks login
Verify tokens are stored
vibetasks config
`
$3
1. Check hook configuration in config.json
2. Verify environment variables are set correctly
3. Test hooks manually:
`bash
CLAUDE_HOOK_TYPE=SessionStart vibetasks-mcp
`
Architecture
`
┌─────────────────┐
│ Claude Code │
│ or Cursor │
└────────┬────────┘
│ STDIO
│
┌────────▼────────┐
│ VibeTasks MCP │
│ - 11 Tools │
│ - Resources │
│ - Status Flow │
│ - Context Notes│
└────────┬────────┘
│
┌────────▼────────┐
│ @vibetasks/ │
│ core │
└────────┬────────┘
│
┌────────▼────────┐
│ Supabase │
│ PostgreSQL │
└─────────────────┘
`
Tool Reference
| Tool | Description |
|------|-------------|
| create_task | Create a new task (with optional parent for subtasks) |
| create_task_with_subtasks | Create parent + multiple subtasks in one call |
| list_tasks | Get tasks with status filter (todo, vibing, done) |
| update_task | Update task properties including status |
| complete_task | Mark task as done |
| start_vibing | Mark task as in progress with optional context |
| get_vibing_tasks | Get all tasks currently in progress |
| set_context_notes | Update "where I left off" notes |
| delete_task | Delete a task |
| search_tasks | Search tasks by title |
| log_ai_session` | Log an AI coding session |