Skip to main content
Glama

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 build

Data 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.js

Claude 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.

  1. Quit Claude Desktop from the system tray (right-click the icon → Quit). Closing the window is not enough.

  2. Double-click install-desktop.cmd in the repo folder. If Claude is still running, the script asks you to quit it and waits (up to 5 minutes).

  3. The script backs up the config (claude_desktop_config.json.bak-<timestamp>), adds mcpServers.cc-handoff, verifies that nothing else changed, and starts Claude again. Check Settings → Developer for cc-handoff.

Running it again is safe: if the entry is already there, nothing is written. Preview without changing anything:

install-desktop.cmd --dry-run

Notes:

  • 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%\Claude is redirected there, but from a normal terminal that folder does not exist, so a file created at %APPDATA%\Claude is never read. The script follows the app's own rule: it uses the LocalCache file when the package's LocalCache\Roaming\Claude folder exists, and the real %APPDATA%\Claude otherwise (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.exe that 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

create_task(project, title, body)

chat

Creates the next task (P001, P002, …) with status open.

get_next_task(project)

Claude Code

Returns the oldest open task and marks it in_progress.

submit_report(project, task_id, body)

Claude Code

Saves <id>-report.md and marks the task reported.

get_report(project, task_id?)

chat

Returns a task's report; without task_id, the most recent one.

list_tasks(project)

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

  1. Chat: "Create a task in project my-app: add a dark-mode toggle." → create_task → P001 (open)

  2. Claude Code: "Get the next task for my-app." → get_next_task → receives P001, which is now in_progress, and does the work.

  3. Claude Code: submit_report(my-app, P001, "...") → P001 is reported.

  4. 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 cycle

To 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.json

License

MIT

Available Tools

5 tools
create_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

    A3.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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 npm
      34
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Persistent, 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.
      5
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      20
      MIT