Tools Reference

Tools Reference

Every tool the handoff-mcp server exposes. Tool names are prefixed handoff_ (in Claude Code they appear as mcp__handoff__handoff_*). All tools take an optional project_dir; when omitted it defaults to the current working directory.

Rule of thumb: drive everything through these tools. Do not read or write the .handoff/ JSON files directly — the server keeps them consistent and writes them atomically.

Session management

handoff_init

Initialize a .handoff/ directory for a project. Call this once, when handoff_load_context reports the project is not initialized.

• Input: project_name (required), project_dir.
• Creates: config.toml, sessions/, and tasks/.

handoff_load_context

Load session context at the start of a session: outstanding tasks, recent decisions, blockers, unread referrals, and git state.

• Input: project_dir, optional session_id to resume a specific session.
• Output: task_summary, task_tree, previous_session, next_actions, open_sessions, and — when no active session exists — a session_guidance block telling the agent to establish one.
• First move: read next_actions (the previous session's recommended steps) before re-verifying completed work.

handoff_save_context

Save session state. With session_status: "active" it establishes (or updates in place) a persistent active session that survives interruptions; with the default session_status: "closed" it writes handoff data and closes the session as history.

• Key fields: summary (required), decisions, blockers, checklist, handoff_notes (caution / context / suggestion), references, context_pointers.
• Pausing: pause_active / pause_session_id pause sessions for later resumption instead of closing them.

handoff_update_session

Incrementally update the active session without closing it — toggle checklist items, append decisions, notes, or context pointers as work progresses.

handoff_list_sessions

List sessions (open / active / paused / closed) with summary info. Filter by status and limit.

handoff_get_session

Get the full detail of one session by ID: decisions, checklist, notes, and pointers.

Task management

handoff_list_tasks

List tasks with filters: status, assignee, milestone, priority, label.

handoff_get_task

Get the full details of one task — notes, done_criteria, schedule, links, dependencies.

handoff_update_task

Create, update, or move a task in the hierarchical tree. Upsert by id; omit id for an auto-generated one; move_to relocates a subtree.

• Always include done_criteria, priority, labels, and assignee.
• Estimates are required: when settings.require_estimate_hours is true (the default), creating or updating a leaf task in todo / in_progress / review / done requires schedule.estimate_hours > 0. Parent tasks and blocked / skipped tasks are exempt. See Estimates and Capacity.

handoff_check_criterion

Toggle a single done_criteria item by index — check items off as you verify them, rather than all at once when the task completes.

handoff_log_time

Record hours worked: atomically adds to actual_hours and deducts from remaining_hours. Prefer this over setting actual_hours by hand.

handoff_bulk_update_tasks

Apply status, schedule, assignee, or priority changes to many tasks in one call.

Metrics and scheduling

handoff_get_metrics

Project health: completion %, effort totals, overdue count, budget status, and a per-milestone breakdown. Reports ai_estimate_multiplier, total_adjusted_estimate_hours, and per-milestone adjusted_estimate_hours — the raw estimates scaled by the AI-effort multiplier.

handoff_get_capacity

Available work hours across a date range, respecting the project calendar and per-assignee config. A task's raw estimate is multiplied by ai_estimate_multiplier when distributed across days; remaining_hours (actual progress) is used as-is.

handoff_auto_schedule

Compute optimal task dates from dependencies, estimates, and capacity. Use dry_run: true first to preview changes before applying them.

Configuration and team

handoff_get_config / handoff_update_config

Read the full config.toml as JSON, or patch any section with dot-notation keys (e.g. "settings.ai_estimate_multiplier": 0.3, "calendar.work_hours_per_day": 7). See Configuration.

Team — handoff_list_assignees / handoff_add_assignee / handoff_update_assignee / handoff_remove_assignee

List members with task counts and effort stats; add, update (partial — null clears a field), or remove a member. Removal also unassigns them from every task.

Milestones — handoff_list_milestones / handoff_add_milestone / handoff_update_milestone / handoff_remove_milestone

Full CRUD over [milestones.*] (date, color, description).

Project — handoff_update_calendar / handoff_update_labels / handoff_start_project

Patch the [calendar] (work hours, closed days, day_hours, schedule mode), set the project label vocabulary, or set started_at (optionally shifting all task dates to the start).

Cross-project

handoff_dashboard

Overview of every handoff-enabled project found under the configured scan_dirs.

handoff_import_context

Bulk-import tasks and session data from handoff documents.

handoff_refer / handoff_list_referrals / handoff_get_referral / handoff_update_referral

Send a referral to another project, list incoming referrals (summaries only), fetch one referral in full, or advance a referral's status. See Cross-Project Referrals.

MCP Resources

Beyond tools, the server exposes two MCP resources (referenced with @ in Claude Code, e.g. @handoff:handoff://sessions). They are not auto-loaded — handoff_load_context remains the main retrieval path; resources are for manual inspection and debugging.

URI	Returns
handoff://sessions	Active session data (JSON)
handoff://config	Project configuration (TOML)

CLI API

Since v0.15.0, every MCP tool is also callable as a shell command:

handoff-mcp <group> <action> [--key value ...]

All output is JSON on stdout, suitable for programmatic consumption (e.g. child_process.execFile from a VSCode extension or a shell script).

See the full reference: CLI API Reference.