cc-handoff
cc-handoff is a local MCP server that hands Markdown tasks and reports back and forth between a planning Claude chat and Claude Code.
create_task(project, title, body) — the planner creates the next task (
P001,P002, …) with statusopen.get_next_task(project) — Claude Code takes the oldest
opentask, receiving its ID, title and body, and the task becomesin_progress.submit_report(project, task_id, body) — Claude Code saves
<id>-report.mdand marks the taskreported.get_report(project, task_id?) — the planner reads a specific task's report, or the most recent one if no ID is given.
list_tasks(project) — lists ID, title and status of every task in a project.
Tasks move through
open→in_progress→reported→closed, though closing is a manual file edit since no tool does it.Inputs are validated: project slugs must be lowercase/digits/hyphens (e.g.
my-app), task IDs matchP001-style patterns, and bodies are Markdown.All state lives as plain Markdown files with YAML frontmatter in
~/.cc-handoff/(orHANDOFF_DIR), one sub-folder per project.All tools declare
execution.taskSupport: "forbidden"— they run synchronously and never spawn or manage long-running server-side tasks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cc-handoff Create a task in my-app: add a dark-mode toggle"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
cc-handoff
A small local MCP server that removes the copy-paste loop between a planning Claude chat (Claude Desktop) and Claude Code. The chat writes a task, Claude Code picks it up and leaves a report, and the chat reads the report — all through plain Markdown files on your disk.
Install
Requires Node.js 20+.
git clone https://github.com/ardayldz8/cc-handoff.git
cd cc-handoff
npm install
npm run buildData lives in ~/.cc-handoff/ by default (override with the HANDOFF_DIR
environment variable). Each project is a sub-folder holding P001-task.md,
P001-report.md, and so on. Task files carry YAML frontmatter
(id, project, title, status, created_at, updated_at).
Related MCP server: backlog
Configure
Use the absolute path to dist/index.js. Point both clients at the same data
directory (the default does that), so they see the same tasks.
Claude Code (user scope, available in every project):
claude mcp add --scope user cc-handoff -- node /absolute/path/to/cc-handoff/dist/index.jsClaude Desktop on Windows: after npm run build, quit Claude Desktop and
double-click install-desktop.cmd in the repo folder. See
Windows: Claude Desktop install below.
Claude Desktop on macOS: with the app fully quit, add this to
~/Library/Application Support/Claude/claude_desktop_config.json, then start it:
{
"mcpServers": {
"cc-handoff": {
"command": "node",
"args": ["/absolute/path/to/cc-handoff/dist/index.js"]
}
}
}Windows: Claude Desktop install
Claude Desktop must be fully closed while its config is edited. The running
app keeps claude_desktop_config.json in memory and rewrites the whole file
whenever a setting changes, so anything added while it runs is silently lost.
Quit Claude Desktop from the system tray (right-click the icon → Quit). Closing the window is not enough.
Double-click
install-desktop.cmdin the repo folder. If Claude is still running, the script asks you to quit it and waits (up to 5 minutes).The script backs up the config (
claude_desktop_config.json.bak-<timestamp>), addsmcpServers.cc-handoff, verifies that nothing else changed, and starts Claude again. Check Settings → Developer forcc-handoff.
Running it again is safe: if the entry is already there, nothing is written. Preview without changing anything:
install-desktop.cmd --dry-runNotes:
Where the config really is. Claude Desktop from the Microsoft Store / MSIX installer reads
%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.json. Inside the app (and in terminals it starts)%APPDATA%\Claudeis redirected there, but from a normal terminal that folder does not exist, so a file created at%APPDATA%\Claudeis never read. The script follows the app's own rule: it uses the LocalCache file when the package'sLocalCache\Roaming\Claudefolder exists, and the real%APPDATA%\Claudeotherwise (classic installs, or MSIX installs upgraded from the classic installer).Run it outside Claude. Claude Code sessions in the desktop app are child processes of Claude Desktop and are closed with it, so the script refuses to install from inside one. Use Explorer or a normal terminal.
The entry stores the full path of the
node.exethat ran the script. If you move or reinstall Node.js elsewhere, or move this repo, run the installer again.
Tools
Tool | Who uses it | What it does |
| chat | Creates the next task ( |
| Claude Code | Returns the oldest |
| Claude Code | Saves |
| chat | Returns a task's report; without |
| both | Lists ID, title and status of every task. |
Statuses: open → in_progress → reported → closed (close a task by
editing its file; no tool does that yet).
Example flow
Chat: "Create a task in project
my-app: add a dark-mode toggle." →create_task→P001(open)Claude Code: "Get the next task for
my-app." →get_next_task→ receives P001, which is nowin_progress, and does the work.Claude Code:
submit_report(my-app, P001, "...")→ P001 isreported.Chat: "Read the latest report for
my-app." →get_report→ plans the next step.
Development
npm test # store and installer unit tests (vitest)
npm run smoke # builds, starts the server over stdio, runs a full task -> report cycleTo try the Windows installer against a copy of a config file:
node scripts/install-desktop.mjs --dry-run --config path/to/copy/claude_desktop_config.jsonLicense
MIT
Available Tools
5 toolscreate_taskCreate taskB
Planner: create a new task for Claude Code in a project. Gets the next ID (P001, P002, ...) and status open.
Inputs: body (required), title (required), project (required).
get_next_taskGet next taskA
Claude Code: take the oldest open task in a project. Returns its ID, title and body and marks it in_progress.
Inputs: project (required).
get_reportGet reportA
Planner: read a task's report. Without task_id, returns the most recently submitted report in the project.
Inputs: project (required), task_id.
list_tasksList tasksB
List all tasks in a project with ID, title and status.
Inputs: project (required).
submit_reportSubmit reportB
Claude Code: save the report for a task and mark the task reported.
Inputs: body (required), project (required), task_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct action and resource: creating tasks, claiming the next task, submitting reports, reading reports, and listing tasks. The role annotations further clarify intended usage, so an agent should not confuse them.
All tool names use consistent snake_case verb_noun phrasing, such as create_task, get_next_task, submit_report, get_report, and list_tasks. The pattern is predictable and easy to scan.
Five tools are well-scoped for a lightweight task handoff workflow. Each tool supports a distinct step in the planner/Claude Code loop without unnecessary surface area.
The core handoff lifecycle is covered: create, claim, report, read report, and list. A direct get_task by ID or update/delete operation is missing, but the main workflow has no obvious dead ends.
Maintenance
Related MCP Connectors
Shared workspace where Claude, ChatGPT, Codex and Grok share files, tasks, decisions and handoffs.
One shared project for a team's coding agents: decisions, a task board and handoffs.
A task list shared by you and your coding agents (Claude Code, Cursor, Codex and any MCP client). Agents plan each task into steps, report live progress to a board, and block on questions you answer from your phone.
Shared task board and knowledge base for AI coding agents Give your coding agents a shared task board and knowledge base, so the plan survives between sessions and across agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA shared operational layer that synchronizes tasks and project contexts across Claude Chat, Cowork, and Code surfaces using local markdown files. It enables persistent state management and cross-session knowledge sharing without the need for a database.329 npm34MIT
- AlicenseAqualityDmaintenancePersistent, cross-session task management for Claude Code. 24 MCP tools for tasks, projects, dependencies, and docs. 7 skills for planning, standups, and handoffs. Event-sourced storage with per-project isolation.5MIT
- FlicenseBqualityAmaintenanceA local, file-backed feature/bug board for projects, enabling Claude to read and write markdown boards (featurelist.md / buglist.md) directly in chat for task planning, bug logging, and velocity tracking.2172-
- AlicenseBqualityBmaintenanceEnables AI agents to manage a filesystem-based issue tracker through typed MCP tools such as list_tasks, create_task, change_task_status, log_work, and get_sprint, instead of shelling out to a CLI. Tasks and sprints are plain folders of Markdown files, so agents can create, claim, comment on, and move work by topic without any database or server state.20MIT