CALL THIS FIRST at the start of every Claude Code session.

Returns the minimum context needed to orient yourself: active tasks, open blockers, and decisions relevant to the files you're currently working on.

This is the ONLY tool you need to call proactively. Everything else is on-demand.

Args:

• workflow_id: The workflow for this project (from CLAUDE.md)

• cwd: Current working directory (pass process.cwd() equivalent)

• depth: How much context to load minimal = active tasks + open blockers only (~300 tokens) standard = + relevant decisions (~600 tokens, DEFAULT) deep = + teammate activity + patterns (~1200 tokens)

Returns: SessionContext with workflow state, active work, open blockers, relevant decisions, and a hint.

After calling this, DO NOT call workflow_summary, task_list, or decision_list unless the user explicitly asks. Pull individual records on demand with their ID.

Detect which workflow matches the current git branch.

Call this if you don't have a workflow_id in CLAUDE.md yet, or if you're on an unfamiliar branch and want to know if a workflow already exists for it.

Returns either a matched workflow or a suggestion to create one.

Set your personal retrieval depth preference for session init.

This is saved by your git email and applied automatically on every future session.

minimal = active tasks + open blockers only (fastest, smallest context cost) standard = + relevant decisions (default, recommended) deep = + teammate activity + historical patterns (use when debugging complex issues)

Get overall Claude Project History status: storage summary and active workflow count.

Use this to check that the plugin is working, not to get project context. For project context, use cph_session_init.

Synchronize project context with the database.

Call this at the start of every session and after completing each task.

First call (or full_refresh=true): returns full context snapshot like session_init. Subsequent calls: returns only changes (deltas) since last sync, within token budget.

If a tool returns a conflict error, call this to get current state before retrying.

Args:

• workflow_id: The workflow for this project (from CLAUDE.md)

• cwd: Current working directory for git context

• depth: How much context to load (minimal | standard | deep)

• full_refresh: Force a full snapshot instead of deltas

Returns: { context, deltas, synced_at }

Create a new workflow (project container for tasks, blockers, decisions).

Create one per feature branch, sprint, or meaningful engineering effort.

Args:

• name: Short name (e.g. "OAuth Migration", "API v2", "Payments Refactor")

• description: Goals and scope (optional)

• git_branch_pattern: Branch pattern for auto-detection (e.g. "feature/auth-", "fix/") Set this so cph_detect_workflow automatically finds this workflow on matching branches.

Returns: Created workflow with ID. PUT THIS ID IN YOUR CLAUDE.md.

List workflows filtered by status.

Returns: Array of workflows with ID, name, status. No task counts (use cph_workflow_summary for that).

Get a full status summary of a workflow.

Returns task counts by status, open blocker count, decision count, and estimation accuracy ratio.

Use this when a user explicitly asks for project status. Don't call proactively.

Update a workflow's name, description, status, or git branch pattern.

Create a task within a workflow.

Call this when beginning any discrete piece of work that will take more than ~5 minutes. Create BEFORE starting work, not after.

Args:

• workflow_id: Which workflow

• title: What you're doing (e.g. "Implement JWT refresh token rotation")

• description: Acceptance criteria and requirements (optional)

• parent_task_id: If this is a subtask (optional)

• priority: low | medium | high | critical

• estimated_minutes: Your estimate. ALWAYS provide this even if rough. Skipping this excludes the task from estimation accuracy analysis. Guess if unsure — a bad estimate is more useful than no estimate.

Returns: Created task. Call cph_task_start immediately after.

Mark a task as in_progress and record start time.

CALL THIS BEFORE writing any code or making any changes for this task. The hook system uses the existence of an in_progress task to allow file writes.

State machine: pending → in_progress (only valid transition from this tool)

Mark a task as completed.

State machine: in_progress → completed (rejects if not in_progress)

Args:

• task_id: The task to complete

• actual_minutes: Actual time spent. CRITICAL for estimation training. This is the ground truth that improves future predictions. Provide even if the task was blocked for part of the time.

• completion_notes: What was done, any gotchas, what to know next time (optional)

List tasks filtered by workflow and/or status.

Returns ID and title only for efficiency. Use cph_task_get for full details on a specific task.

Call this only when explicitly asked — session_init already provides active tasks.

Get full details of a single task including subtasks and open blockers.

Update task fields. For starting/completing, prefer task_start and task_complete.

Cancel a task that is no longer needed.

State machine: pending | in_progress | blocked → cancelled

Args:

• task_id: The task to cancel

• reason: Why the task is being cancelled (optional but recommended)

Log a blocker that is preventing progress.

CALL THIS IMMEDIATELY when blocked — before asking the user, before trying workarounds. The timestamp of when you were blocked is important data. Don't record it retroactively.

Blocker types: dependency → waiting on another task, PR, or service to be ready waiting_on_human → needs human decision, approval, or response technical → technical problem with no clear solution yet external → blocked by something outside the team unclear_requirements → requirements are ambiguous other → doesn't fit above

Auto-behavior: if task_id is provided, the task status is automatically set to 'blocked'.

Mark a blocker as resolved.

Always provide a resolution note — this is training data for predicting future blockers and is the most valuable signal in the system after actual_minutes on tasks.

Auto-behavior: if blocker has a task_id and unblock_task=true, task is set back to in_progress.

Mark a blocker as escalated — open but needs urgent attention.

Use when a blocker has been open too long and needs to be surfaced to stakeholders.

List blockers by workflow and/or status.

Call this when user asks about blockers. session_init already surfaces open blockers — don't duplicate.

Record an architectural, design, or process decision.

This is the institutional memory of the project. Future sessions — and future engineers — will use this to understand why things are built the way they are.

Record a decision when:

• You chose between two or more approaches

• You made an assumption about requirements

• The word "because" appears in your reasoning

• You're doing something non-obvious that someone will question later

The post-commit hook will automatically attach the commit hash to recent decisions — you don't need to provide it manually.

Args:

• workflow_id, title, decision: Required

• context: What problem were you solving? What constraints existed?

• rationale: Why this option over the alternatives?

• alternatives_considered: Structured list of options evaluated and why rejected

• trade_offs: What does this choice cost or foreclose?

• tags: Comma-separated (e.g. "auth,database,performance") or array

• reversibility: How hard is it to undo? (reversible | costly | irreversible)

• confidence: How confident are you? (low | medium | high)

• files_affected: Which files does this decision impact?

• forcing_constraint: What external force required this decision now?

• revisit_if: Under what conditions should this be revisited?

Search decisions by keyword across title, decision, context, and rationale.

CALL THIS before making any significant architectural choice to check if it was already decided. This is the primary anti-repetition tool.

Returns summary view (id + title + decision only) to preserve context budget. Use cph_decision_get for full details on a specific result.

Get full details of a single decision including rationale and alternatives.

Use after cph_decision_search returns relevant IDs.

List decisions for a workflow. Returns summary view only.

Call this when user explicitly asks to see decisions. session_init surfaces relevant ones automatically.

Internal: Called by the post-commit git hook to link recent decisions to a commit.

Do NOT call this manually. The hook calls it automatically after every commit.

Attaches commit_hash and diff_stat to decisions recorded in the last 30 minutes that don't already have a commit attached.

Get inferred thinking-time breakdown for recent turns.

Claude Code's extended thinking is not directly observable. This tool infers thinking time from the gaps between tool calls:

• Initial gap: time from user prompt to first tool use

• Interleaved gaps: time between consecutive tool calls

• Final gap: time from last tool to response

Returns per-turn breakdowns, aggregate stats, tool baselines, and a caveat explaining inference limitations.

Args:

• session_id: Filter to a specific session (optional)

• workflow_id: Filter to a specific workflow (optional)

• limit: Number of recent turns to return (default 10)

Show active agents/developers and what they're working on.

Returns annotated list of active sessions with:

• Developer name and identity

• Current task (if any)

• Current blocker (if any)

• Status: active | blocked | idle_with_task | available

• Summary counts

Use this to understand team state before starting work.

Get recent activity events for team awareness.

Shows what's been happening: tasks started/completed, decisions recorded, blockers created/resolved, sessions started.

Filter by workflow, time range, and event types.

Reconstruct the full history of a workflow for handoff or review.

Aggregates tasks, decisions, blockers, sessions, and activity into a comprehensive reconstruction object. Identifies dead ends (cancelled tasks and resolved blockers) to show the journey, not just the destination.

Use this when:

• Handing off a workflow to another developer

• Reviewing what happened during a project

• Debugging why certain decisions were made

Register or update file area ownership for a workflow.

Use this during plan mode to declare which parts of the codebase are relevant to the current workflow, what their responsibilities are, and their dependencies.

Each area is a path pattern (e.g. "src/auth/**") with an optional responsibility description and dependency list.

Upserts by workflow_id + path_pattern — safe to call multiple times.