refactor: replace MCP tools with session CLI transport (#60)

Author: benvinegar

README.md

@@ -122,7 +122,7 @@ Then load it in Pi with:
 /skill:hunk-review
 ```
 
-The skill explains what Hunk is and how to use Hunk's MCP tools for live code review.
+The skill explains what Hunk is and how to use `hunk session ...` for live code review.
 
 ## Config
 
@@ -144,13 +144,14 @@ agent_notes = false
 ## Advanced workflows
 
 - `hunk diff --agent-context <file>` loads inline agent rationale from a JSON sidecar
-- `hunk mcp serve` runs the local MCP daemon for agent-to-diff communication
+- `hunk mcp serve` runs the local Hunk session daemon and websocket broker
+  - normal Hunk sessions auto-start/register with it when MCP is enabled
   - Hunk keeps the daemon loopback-only by default
   - if you intentionally need remote access, set `HUNK_MCP_UNSAFE_ALLOW_REMOTE=1` and choose a non-loopback `HUNK_MCP_HOST`
 
 ### Live session control CLI
 
-`hunk session ...` is the human/script interface to the same local daemon that MCP uses for live review sessions.
+`hunk session ...` is the user-facing and agent-facing interface to Hunk's local live review session daemon.
 
 Use explicit session targeting with either a live `<session-id>` or `--repo <path>` when exactly one live session matches that repo root.
 

bun.lock

@@ -63,7 +63,6 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
     "@opentui/core": "^0.1.88",
     "@opentui/react": "^0.1.88",
     "@pierre/diffs": "^1.1.0",

package.json

@@ -1,14 +1,14 @@
 ---
 name: hunk-review
-description: Use when the task involves Hunk or Hunk MCP review sessions. Helps Pi briefly explain what Hunk is, prefer live Hunk MCP inspection over shell parsing, inspect current review focus, navigate hunks, and leave inline review comments.
+description: Use when the task involves Hunk review sessions. Helps Pi briefly explain what Hunk is, prefer live Hunk session CLI inspection over shell parsing, inspect current review focus, navigate hunks, and leave inline review comments.
 compatibility: Requires Hunk from this repo or the published hunkdiff package. Works best with a real TTY for interactive review.
 ---
 
 # Hunk Review
 
 Use this skill when working with Hunk itself or when the user wants a code-review workflow centered on Hunk.
 
-When this skill activates, start by briefly explaining what Hunk is in plain language before jumping into MCP details.
+When this skill activates, start by briefly explaining what Hunk is in plain language before jumping into session-control details.
 
 ## What Hunk is
 
@@ -21,42 +21,42 @@ Keep these product rules in mind:
 - `[` and `]` navigate hunks across the full review stream
 - agent notes belong beside the code they explain
 
-## Default rule: prefer live MCP review
+## Default rule: prefer live session CLI review
 
-If a live Hunk session already exists, prefer Hunk's MCP tools over launching new shell commands or scraping terminal output.
+If a live Hunk session already exists, prefer `hunk session ...` over launching new shell commands that scrape terminal output.
 
-The MCP daemon is local-only and brokers commands to one or more live Hunk sessions.
+The local Hunk daemon is loopback-only by default and brokers commands to one or more live Hunk sessions.
 
 Important behavior:
 - normal Hunk sessions auto-start and register with the daemon when MCP is enabled
-- `hunk mcp serve` exists for manual startup or debugging
-- `HUNK_MCP_DISABLE=1` disables MCP registration for a session
+- `hunk mcp serve` exists for manual startup or debugging, but it is not the default review path
+- `HUNK_MCP_DISABLE=1` disables daemon registration for a session
 - one daemon can serve many Hunk sessions
 
-## Recommended MCP review loop
+## Recommended review loop
 
 Use this flow by default:
-1. `list_sessions`
-2. `get_selected_context`
-3. `navigate_to_hunk` only if the current focus is wrong
-4. `comment`
+1. `hunk session list`
+2. `hunk session context`
+3. `hunk session navigate` only if the current focus is wrong
+4. `hunk session comment add`
 
-Use `get_session` only when you need broader session metadata.
+Use `hunk session get` only when you need broader session metadata.
 
 Guidelines:
 - if multiple sessions are live, pass `sessionId` explicitly
-- prefer `get_selected_context` before navigating blindly
-- use `navigate_to_hunk` for hunk-level movement; do not invent extra remote-control behavior
-- use `comment` for concise inline review notes tied to real diff lines
-- prefer `reveal: true` unless the user wants a quieter action
+- prefer `hunk session context` before navigating blindly
+- use `hunk session navigate` for hunk-level movement; do not invent extra remote-control behavior
+- use `hunk session comment add` for concise inline review notes tied to real diff lines
+- prefer visible, review-oriented actions over shell parsing of rendered terminal output
 
-For concrete MCP tool behavior and examples, read [references/mcp-review.md](references/mcp-review.md).
+For concrete review flow examples, read [references/mcp-review.md](references/mcp-review.md).
 
 ## Start Hunk only when needed
 
-If no live Hunk session exists and the user wants an interactive review UI, launch Hunk itself with a minimal command and let it auto-start/register with the MCP daemon.
+If no live Hunk session exists and the user wants an interactive review UI, launch Hunk itself with a minimal command and let it auto-start/register with the daemon.
 
-After launching Hunk, go back to `list_sessions` rather than suggesting manual daemon management.
+After launching Hunk, go back to `hunk session list` rather than suggesting manual daemon management.
 
 Inside the Hunk repo, prefer the source entrypoint:
 
@@ -87,7 +87,7 @@ When using Hunk for agent changes:
 Prefer a skill over a prompt dump:
 - keep always-loaded context small
 - load the full Hunk workflow only when the task is actually about review
-- use Hunk's existing MCP tools rather than ad hoc shell parsing
+- use Hunk's session CLI rather than a separate agent-facing MCP tool surface
 
 Prefer review-oriented actions:
 - inspect the current live diff session

skills/hunk-review/SKILL.md

@@ -2,7 +2,7 @@
 
 ## Source repo vs installed CLI
 
-Launching Hunk normally should auto-start/register the MCP daemon when MCP is enabled, so Pi usually does not need to run `hunk mcp serve` first.
+Launching Hunk normally should auto-start/register the local session daemon when MCP is enabled, so Pi usually does not need to run `hunk mcp serve` first.
 
 If Pi is operating inside the Hunk source repo, prefer the source entrypoint so review and validation target the current checkout:
 

skills/hunk-review/references/commands.md

@@ -1,6 +1,6 @@
-# Hunk MCP review flow
+# Hunk live review flow
 
-Hunk MCP is a local-only loopback daemon that brokers commands to one or more live Hunk review sessions.
+Hunk uses one local-only loopback daemon to broker commands to one or more live Hunk review sessions.
 
 ## Daemon model
 
@@ -11,34 +11,37 @@ Hunk MCP is a local-only loopback daemon that brokers commands to one or more li
 hunk mcp serve
 ```
 
-- Disable MCP registration for one Hunk session with:
+- Disable daemon registration for one Hunk session with:
 
 ```bash
 HUNK_MCP_DISABLE=1 hunk diff
 ```
 
-## Current tool surface
+## User and agent interface
 
-The review-oriented MCP tools are:
-- `list_sessions`
-- `get_session`
-- `get_selected_context`
-- `navigate_to_hunk`
-- `comment`
+The review-oriented interface is `hunk session ...`:
+- `hunk session list`
+- `hunk session get`
+- `hunk session context`
+- `hunk session navigate`
+- `hunk session comment add`
+- `hunk session comment list`
+- `hunk session comment rm`
+- `hunk session comment clear --yes`
 
-## Recommended agent flow
+## Recommended review flow
 
 ### 1. Discover the target session
 
-Call `list_sessions` first.
+Run `hunk session list` first.
 
-If no session exists but the user wants interactive review, launch Hunk (`hunk diff`, `hunk show`, or the source entrypoint in this repo), then come back and call `list_sessions` again.
+If no session exists but the user wants interactive review, launch Hunk (`hunk diff`, `hunk show`, or the source entrypoint in this repo), then come back and run `hunk session list` again.
 
-Use `sessionId` explicitly whenever more than one live session exists.
+Use explicit `sessionId` or `--repo <path>` whenever more than one live session exists.
 
 ### 2. Inspect current focus
 
-Call `get_selected_context` to see:
+Run `hunk session context` to see:
 - current file
 - current hunk index
 - selected hunk old/new ranges
@@ -49,30 +52,28 @@ This is the best way to respect what the human reviewer is already looking at.
 
 ### 3. Move only when needed
 
-If the current focus is wrong, call `navigate_to_hunk` with either:
-- `hunkIndex`, or
-- `side` + `line`
+If the current focus is wrong, run `hunk session navigate` with either:
+- `--hunk <n>`, or
+- `--old-line <n>` / `--new-line <n>`
 
 Prefer hunk-level movement over adding broader remote-control actions.
 
 ### 4. Leave inline review notes
 
-Call `comment` with:
-- `sessionId`
-- `filePath`
-- `side`
-- `line`
-- `summary`
-- optional `rationale`
-- optional `author`
-- usually `reveal: true`
+Run `hunk session comment add` with:
+- `<session-id>` or `--repo <path>`
+- `--file`
+- `--old-line` or `--new-line`
+- `--summary`
+- optional `--rationale`
+- optional `--author`
 
 Use concise review comments tied to actual diff lines.
 
 ## Practical guidance for Pi
 
-- Prefer MCP tools over scraping terminal text when a live Hunk session already exists.
-- Use `get_session` when you need broad session metadata; use `get_selected_context` for fast focus-aware checks.
+- Prefer `hunk session ...` over scraping terminal text when a live Hunk session already exists.
+- Use `hunk session get` when you need broad session metadata; use `hunk session context` for fast focus-aware checks.
 - In multi-session setups, never assume the sole-session fallback is still safe after new windows open.
 - Keep comments review-oriented rather than conversational.
 - If the user wants silent inspection rather than visible interaction, avoid unnecessary navigation and only comment when asked.

skills/hunk-review/references/mcp-review.md

@@ -127,7 +127,7 @@ function renderCliHelp() {
     "  hunk pager                              general Git pager wrapper with diff detection",
     "  hunk difftool <left> <right> [path]     review Git difftool file pairs",
     "  hunk session <subcommand>               inspect or control a live Hunk session",
-    "  hunk mcp serve                          run the local Hunk MCP daemon",
+    "  hunk mcp serve                          run the local Hunk session daemon",
     "",
     "Options:",
     "  -h, --help                              show help",
@@ -691,7 +691,7 @@ async function parseMcpCommand(tokens: string[]): Promise<ParsedCliInput> {
       text: [
         "Usage: hunk mcp serve",
         "",
-        "Run the local Hunk MCP daemon and websocket session broker.",
+        "Run the local Hunk session daemon and websocket session broker.",
         "",
         "Environment:",
         "  HUNK_MCP_HOST                  bind host (default 127.0.0.1; loopback only unless explicitly overridden)",
@@ -711,7 +711,7 @@ async function parseMcpCommand(tokens: string[]): Promise<ParsedCliInput> {
       text: [
         "Usage: hunk mcp serve",
         "",
-        "Run the local Hunk MCP daemon and websocket session broker.",
+        "Run the local Hunk session daemon and websocket session broker.",
       ].join("\n") + "\n",
     };
   }