handoff-mcp-server 0.13.0 → 0.13.1

package/Cargo.lock

@@ -144,7 +144,7 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.13.0"
+version = "0.13.1"
 dependencies = [
  "anyhow",
  "chrono",
@@ -393,6 +393,7 @@ version = "1.0.150"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
 dependencies = [
+ "indexmap",
  "itoa",
  "memchr",
  "serde",

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.13.0"
+version = "0.13.1"
 edition = "2021"
 description = "MCP server that gives AI coding agents persistent memory across sessions"
 license = "MIT"
@@ -14,7 +14,7 @@ exclude = ["lefthook.yml", "tmp/", "wiki/", "docs/", ".claude/", ".vscode/"]
 
 [dependencies]
 serde = { version = "1", features = ["derive"] }
-serde_json = "1"
+serde_json = { version = "1", features = ["preserve_order"] }
 toml = "0.8"
 toml_edit = "0.22"
 chrono = { version = "0.4", features = ["serde"] }

package/README.md

@@ -33,12 +33,23 @@ At session start, the agent calls `handoff_load_context` to pick up where things
 
 ## Installation
 
-### npm (recommended)
+### cargo (recommended if you have Rust)
+
+```bash
+cargo install handoff-mcp
+```
+
+### npm
 
 ```bash
 npm install -g handoff-mcp-server
 ```
 
+Both install the same binary. `cargo install` fetches the crate from
+[crates.io](https://crates.io/crates/handoff-mcp) and compiles it directly;
+`npm install` downloads the source and runs `cargo build --release` via
+postinstall, so either way you need a Rust toolchain.
+
 ### Build from source
 
 ```bash
@@ -73,6 +84,34 @@ The `-s user` flag registers it globally (available in all projects). Verify wit
 }
 ```
 
+### Enable automatic memory injection (optional)
+
+If you want project memories to be automatically injected into your context
+(instead of calling `handoff_memory_query` manually every time), run:
+
+```bash
+handoff-mcp setup
+```
+
+This installs Claude Code hooks into `~/.claude/settings.json` that
+automatically call `handoff_memory_query` on every prompt and file edit, and run
+`handoff_memory_cleanup` at session start. Restart Claude Code after running setup.
+
+You can check the current status or remove the hooks:
+
+```bash
+handoff-mcp setup --check      # Show hook status
+handoff-mcp setup --uninstall  # Remove handoff hooks
+```
+
+The hooks fire on every prompt and file edit, which adds a small overhead per
+interaction. If you want to stop automatic injection, run
+`handoff-mcp setup --uninstall` — the memory tools themselves remain available
+for manual use, only the automatic hooks are removed.
+
+See [Automatic injection via hooks](#automatic-injection-via-hooks) for the
+manual configuration alternative.
+
 ## Quick Start
 
 1. **Initialize** a project:
@@ -163,10 +202,10 @@ rename) so a concurrent reader never sees a partially-written file.
 
 | Tool | Purpose |
 |------|---------|
-| `memory_save` | Save a durable project memory (lesson/rule/convention/gotcha); detects exact and near-duplicate memories and hands near-duplicates back for AI-driven merge |
-| `memory_query` | Return the memories most relevant to the current prompt/file (BM25 + scope-path boost); with a `session_id`, suppresses repeats already injected this session |
-| `memory_delete` | Delete a memory by id (full id or unique prefix) |
-| `memory_cleanup` | Housekeeping (for SessionStart): silently merge exact duplicates, return near-duplicate/stale recommendations, gc old injection sidecars |
+| `handoff_memory_save` | Save a durable project memory (lesson/rule/convention/gotcha); detects exact and near-duplicate memories and hands near-duplicates back for AI-driven merge |
+| `handoff_memory_query` | Return the memories most relevant to the current prompt/file (BM25 + scope-path boost); with a `session_id`, suppresses repeats already injected this session |
+| `handoff_memory_delete` | Delete a memory by id (full id or unique prefix) |
+| `handoff_memory_cleanup` | Housekeeping (for SessionStart): silently merge exact duplicates, return near-duplicate/stale recommendations, gc old injection sidecars |
 
 See [Project Memory](#project-memory-1) below for what it is and how to wire automatic injection.
 
@@ -300,6 +339,11 @@ Sessions answer *"what was I doing last time?"*. **Memory** answers a longer-liv
 question: *"what should every session in this project always know?"* — durable
 lessons, rules, conventions, and gotchas that outlive any one session.
 
+> **Note:** The memory tools (`handoff_memory_save`, `handoff_memory_query`, etc.) can always be
+> called directly by the agent. For **automatic** injection — where relevant
+> memories are surfaced on every prompt without the agent asking — you need to
+> configure Claude Code hooks. See [Automatic injection via hooks](#automatic-injection-via-hooks).
+
 Memories live in `.handoff/memory/` (one JSON file per memory, plus per-session
 `injected/` sidecars). A built-in multilingual similarity engine (Japanese /
 English, dictionary-free) ranks relevance and detects duplicates, all in-memory
@@ -309,28 +353,28 @@ and sub-millisecond.
 
 The agent can call the memory tools at any time:
 
-- `memory_save` — record a memory. An exact duplicate is reported (not
+- `handoff_memory_save` — record a memory. An exact duplicate is reported (not
   rewritten); a near-duplicate comes back as a `conflict` with both bodies so the
   agent can merge them (`merge_into=<id>`, `absorb_ids=[…]`) or save separately
   with `force=true`. **handoff-mcp never merges for you** — it surfaces both
   bodies and lets the agent decide.
-- `memory_query` — fetch the memories most relevant to some text and/or files.
-- `memory_delete` / `memory_cleanup` — prune and de-duplicate the store.
+- `handoff_memory_query` — fetch the memories most relevant to some text and/or files.
+- `handoff_memory_delete` / `handoff_memory_cleanup` — prune and de-duplicate the store.
 
 ### Automatic injection via hooks
 
 MCP is request/response — the server cannot push a memory into the agent's
 context on its own. **Claude Code hooks** close that gap: they fire regardless of
-what the agent intends, call `memory_query`, and inject the matching memories as
+what the agent intends, call `handoff_memory_query`, and inject the matching memories as
 `additionalContext`. A per-session diff (keyed on the hook `session_id`) ensures
 the same memory is **not injected twice in one session** — and an *edited* memory
 (new content hash) is re-injected.
 
 | Event | Calls | Effect |
 |-------|-------|--------|
-| `UserPromptSubmit` | `memory_query` (prompt text) | Inject memories relevant to the prompt |
-| `PreToolUse` (`Edit\|Write\|MultiEdit`) | `memory_query` (file path) | Inject memories scoped to the file being edited |
-| `SessionStart` | `memory_cleanup` | Merge exact duplicates, gc old sidecars |
+| `UserPromptSubmit` | `handoff_memory_query` (prompt text) | Inject memories relevant to the prompt |
+| `PreToolUse` (`Edit\|Write\|MultiEdit`) | `handoff_memory_query` (file path) | Inject memories scoped to the file being edited |
+| `SessionStart` | `handoff_memory_cleanup` | Merge exact duplicates, gc old sidecars |
 
 > **Wire hooks in your *user/global* settings, not in the repo.** Hooks are a
 > personal workflow choice; the handoff-mcp repo does not ship a `.claude/`
@@ -347,14 +391,14 @@ MCP tool from a hook directly, with no wrapper script. In
   "hooks": {
     "UserPromptSubmit": [
       { "hooks": [ {
-        "type": "mcp_tool", "server": "handoff", "tool": "memory_query",
+        "type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_query",
         "input": { "project_dir": "${cwd}",
                    "session_id": "${session_id}", "text": "${prompt}" }
       } ] }
     ],
     "PreToolUse": [
       { "matcher": "Edit|Write|MultiEdit", "hooks": [ {
-        "type": "mcp_tool", "server": "handoff", "tool": "memory_query",
+        "type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_query",
         "input": { "project_dir": "${cwd}",
                    "session_id": "${session_id}", "tool_name": "${tool_name}",
                    "text": "${tool_input.file_path}",
@@ -363,7 +407,7 @@ MCP tool from a hook directly, with no wrapper script. In
     ],
     "SessionStart": [
       { "hooks": [ {
-        "type": "mcp_tool", "server": "handoff", "tool": "memory_cleanup",
+        "type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_cleanup",
         "input": { "project_dir": "${cwd}" }
       } ] }
     ]
@@ -413,7 +457,7 @@ All under `[settings]` in `.handoff/config.toml`, all with safe defaults
 |-----|---------|---------|
 | `memory_enabled` | `true` | Master switch. When `false`, all four memory tools return a benign empty result and write nothing |
 | `memory_dup_threshold` | `0.72` | Jaccard similarity at/above which a save is a near-duplicate conflict and cleanup groups a cluster |
-| `memory_query_min_score` | `0.5` | BM25 relevance floor for `memory_query` results |
+| `memory_query_min_score` | `0.5` | BM25 relevance floor for `handoff_memory_query` results |
 | `memory_query_limit` | `5` | Max memories returned per query |
 | `memory_stale_days` | `60` | Days without a reference before a memory is flagged stale |
 | `memory_injected_gc_days` | `14` | Age at which per-session injection sidecars are garbage-collected |
@@ -445,9 +489,9 @@ This project uses handoff-mcp for session continuity.
 - **Decisions**: Record decisions with confidence levels as they are made,
   not just at session end. Use `confirmed` for verified facts, `estimated`
   for reasonable assumptions, `unverified` for unknowns.
-- **Project memory**: Use `memory_save` to record durable lessons, rules,
+- **Project memory**: Use `handoff_memory_save` to record durable lessons, rules,
   conventions, and gotchas that every future session should know. Use
-  `memory_query` to retrieve relevant memories. Near-duplicate memories are
+  `handoff_memory_query` to retrieve relevant memories. Near-duplicate memories are
   surfaced as conflicts for you to merge or force-save — never merged silently.
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-mcp-server",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "MCP server that gives AI coding agents persistent memory across sessions",
   "license": "MIT",
   "author": "AlphaElements <66808803+alphaelements@users.noreply.github.com>",

package/scripts/handoff-memory-hook.py

@@ -2,15 +2,15 @@
 """Claude Code hook wrapper for handoff-mcp project memory.
 
 This is the **fallback path** for memory auto-injection. The preferred wiring is
-a native ``mcp_tool`` hook that calls ``memory_query`` / ``memory_cleanup``
+a native ``mcp_tool`` hook that calls ``handoff_memory_query`` / ``handoff_memory_cleanup``
 directly (see README "Project Memory"); this script exists for Claude Code
 versions that lack the ``mcp_tool`` hook type, by translating a Claude Code hook
 event into a single JSON-RPC ``tools/call`` against the handoff-mcp server and
 emitting the result as ``hookSpecificOutput.additionalContext``.
 
 It speaks the server's line-delimited JSON-RPC over stdio: one request object on
-one line in, one response object on one line out. ``memory_query`` /
-``memory_cleanup`` return their payload as a JSON *string* inside
+one line in, one response object on one line out. ``handoff_memory_query`` /
+``handoff_memory_cleanup`` return their payload as a JSON *string* inside
 ``result.content[0].text`` (so both this wrapper and the native hook path parse
 it identically), which this script re-parses.
 
@@ -142,7 +142,7 @@ def _emit(event: str, context: str) -> None:
 
 
 def _format_memories(payload: dict) -> str:
-    """Turn a ``memory_query`` payload into an injectable context block."""
+    """Turn a ``handoff_memory_query`` payload into an injectable context block."""
     memories = payload.get("memories") or []
     if not memories:
         return ""
@@ -188,7 +188,7 @@ def main() -> int:
         if file_paths:
             arguments["file_paths"] = file_paths
 
-        payload = _call(bin_path, "memory_query", arguments)
+        payload = _call(bin_path, "handoff_memory_query", arguments)
         if payload:
             _emit(event, _format_memories(payload))
         return 0
@@ -197,7 +197,7 @@ def main() -> int:
         # Housekeeping only: merge exact duplicates and gc sidecars. We do not
         # inject the cleanup recommendations as context (that is for an explicit
         # AI-driven pass), so there is no additionalContext to emit here.
-        _call(bin_path, "memory_cleanup", {"project_dir": project_dir})
+        _call(bin_path, "handoff_memory_cleanup", {"project_dir": project_dir})
         return 0
 
     # Unknown event — nothing to do.

package/src/lib.rs

@@ -1,2 +1,3 @@
 pub mod mcp;
+pub mod setup;
 pub mod storage;

package/src/main.rs

@@ -3,6 +3,35 @@ use std::io::{self, BufRead, Write};
 use handoff_mcp::mcp::protocol::process_line;
 
 fn main() {
+    let args: Vec<String> = std::env::args().collect();
+
+    if args.len() >= 2 {
+        match args[1].as_str() {
+            "setup" => {
+                let check = args.iter().any(|a| a == "--check");
+                let uninstall = args.iter().any(|a| a == "--uninstall");
+                if let Err(e) = handoff_mcp::setup::run_setup(check, uninstall) {
+                    eprintln!("Error: {e:#}");
+                    std::process::exit(1);
+                }
+                return;
+            }
+            "--version" | "-V" => {
+                println!("handoff-mcp v{}", env!("CARGO_PKG_VERSION"));
+                return;
+            }
+            "--help" | "-h" => {
+                print_help();
+                return;
+            }
+            other => {
+                eprintln!("Unknown command: {other}");
+                eprintln!("Run `handoff-mcp --help` for usage.");
+                std::process::exit(1);
+            }
+        }
+    }
+
     eprintln!("handoff-mcp v{}", env!("CARGO_PKG_VERSION"));
 
     let stdin = io::stdin();
@@ -27,3 +56,21 @@ fn main() {
         }
     }
 }
+
+fn print_help() {
+    println!(
+        "handoff-mcp v{version}
+MCP server for AI session handoff
+
+USAGE:
+    handoff-mcp              Start the MCP server (stdio transport)
+    handoff-mcp setup        Install memory auto-injection hooks into Claude Code
+    handoff-mcp setup --check    Check if hooks are installed
+    handoff-mcp setup --uninstall    Remove handoff hooks from Claude Code
+
+OPTIONS:
+    -h, --help       Print this help message
+    -V, --version    Print version",
+        version = env!("CARGO_PKG_VERSION")
+    );
+}

package/src/mcp/handlers/mod.rs

@@ -75,10 +75,10 @@ pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {
         "handoff_update_calendar" => calendar::handle_update_calendar(arguments),
         "handoff_update_labels" => calendar::handle_update_labels(arguments),
         "handoff_start_project" => calendar::handle_start_project(arguments),
-        "memory_save" => memory::handle_save(arguments),
-        "memory_query" => memory::handle_query(arguments),
-        "memory_delete" => memory::handle_delete(arguments),
-        "memory_cleanup" => memory::handle_cleanup(arguments),
+        "handoff_memory_save" => memory::handle_save(arguments),
+        "handoff_memory_query" => memory::handle_query(arguments),
+        "handoff_memory_delete" => memory::handle_delete(arguments),
+        "handoff_memory_cleanup" => memory::handle_cleanup(arguments),
         _ => Err(anyhow::anyhow!("Tool not implemented: {name}")),
     };
 

package/src/mcp/tools.rs

@@ -1024,7 +1024,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
             }),
         },
         ToolDefinition {
-            name: "memory_save".to_string(),
+            name: "handoff_memory_save".to_string(),
             description: "Save a long-lived project memory (lesson/rule/convention/gotcha) that future sessions should respect. Detects exact and near-duplicate memories: an exact match is reported (not rewritten), a near-duplicate is returned as a 'conflict' with both bodies for you to merge (call again with merge_into=<id> and absorb_ids=[…]) or save separately with force=true. Returns a JSON string.".to_string(),
             input_schema: json!({
                 "type": "object",
@@ -1042,7 +1042,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
             }),
         },
         ToolDefinition {
-            name: "memory_query".to_string(),
+            name: "handoff_memory_query".to_string(),
             description: "Return the project memories most relevant to the given text/file (BM25 + scope-path boosting). Intended for automatic injection via hooks, but callable directly. Returns a JSON string {\"memories\":[{id,text,kind,score}],\"injected_count\"}.".to_string(),
             input_schema: json!({
                 "type": "object",
@@ -1059,7 +1059,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
             }),
         },
         ToolDefinition {
-            name: "memory_delete".to_string(),
+            name: "handoff_memory_delete".to_string(),
             description: "Delete a project memory by id (full id or unique prefix). Use for AI-driven cleanup of stale memories. Returns a JSON string {\"status\":\"deleted\",\"id\"}.".to_string(),
             input_schema: json!({
                 "type": "object",
@@ -1071,7 +1071,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
             }),
         },
         ToolDefinition {
-            name: "memory_cleanup".to_string(),
+            name: "handoff_memory_cleanup".to_string(),
             description: "Housekeep the project memory store (intended for SessionStart). Silently merges exact duplicates (lossless), then returns recommendations the AI should act on: near-duplicate clusters (merge with memory_save merge_into=…) and stale memories (consider memory_delete). Also garbage-collects old per-session injection sidecars. Returns a JSON string {\"auto_merged_exact\":n,\"cleanup_recommendations\":{\"similar_clusters\":[…],\"stale\":[…]},\"injected_sidecars_removed\":k}.".to_string(),
             input_schema: json!({
                 "type": "object",

package/src/setup.rs

@@ -0,0 +1,424 @@
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use anyhow::{Context, Result};
+use serde_json::Value;
+
+const HOOK_SERVER: &str = "handoff";
+const HOOK_TOOL_QUERY: &str = "handoff_memory_query";
+const HOOK_TOOL_CLEANUP: &str = "handoff_memory_cleanup";
+
+fn settings_path() -> Result<PathBuf> {
+    let home = std::env::var("HOME")
+        .or_else(|_| std::env::var("USERPROFILE"))
+        .context("cannot determine home directory (HOME / USERPROFILE not set)")?;
+    Ok(Path::new(&home).join(".claude").join("settings.json"))
+}
+
+fn read_settings(path: &Path) -> Result<Value> {
+    if path.exists() {
+        let text = std::fs::read_to_string(path)
+            .with_context(|| format!("failed to read {}", path.display()))?;
+        serde_json::from_str(&text).with_context(|| format!("failed to parse {}", path.display()))
+    } else {
+        Ok(Value::Object(serde_json::Map::new()))
+    }
+}
+
+fn write_settings(path: &Path, value: &Value) -> Result<()> {
+    let parent = path
+        .parent()
+        .context("settings path has no parent directory")?;
+    std::fs::create_dir_all(parent)
+        .with_context(|| format!("failed to create {}", parent.display()))?;
+
+    let text = serde_json::to_string_pretty(value)?;
+    let tmp = parent.join(".settings.json.tmp");
+    std::fs::write(&tmp, text + "\n")
+        .with_context(|| format!("failed to write {}", tmp.display()))?;
+    std::fs::rename(&tmp, path)
+        .with_context(|| format!("failed to rename {} -> {}", tmp.display(), path.display()))
+}
+
+fn mcp_tool_hook(tool: &str, input: Value) -> Value {
+    serde_json::json!({
+        "type": "mcp_tool",
+        "server": HOOK_SERVER,
+        "tool": tool,
+        "input": input
+    })
+}
+
+fn build_hooks_config() -> BTreeMap<&'static str, Value> {
+    let mut hooks = BTreeMap::new();
+
+    hooks.insert(
+        "UserPromptSubmit",
+        serde_json::json!([{
+            "hooks": [mcp_tool_hook(HOOK_TOOL_QUERY, serde_json::json!({
+                "project_dir": "${cwd}",
+                "session_id": "${session_id}",
+                "text": "${prompt}"
+            }))]
+        }]),
+    );
+
+    hooks.insert(
+        "PreToolUse",
+        serde_json::json!([{
+            "matcher": "Edit|Write|MultiEdit",
+            "hooks": [mcp_tool_hook(HOOK_TOOL_QUERY, serde_json::json!({
+                "project_dir": "${cwd}",
+                "session_id": "${session_id}",
+                "tool_name": "${tool_name}",
+                "text": "${tool_input.file_path}",
+                "file_paths": ["${tool_input.file_path}"]
+            }))]
+        }]),
+    );
+
+    hooks.insert(
+        "SessionStart",
+        serde_json::json!([{
+            "hooks": [mcp_tool_hook(HOOK_TOOL_CLEANUP, serde_json::json!({
+                "project_dir": "${cwd}"
+            }))]
+        }]),
+    );
+
+    hooks
+}
+
+fn has_handoff_hook(arr: &Value) -> bool {
+    let Some(entries) = arr.as_array() else {
+        return false;
+    };
+    for entry in entries {
+        let Some(hooks) = entry.get("hooks").and_then(|v| v.as_array()) else {
+            continue;
+        };
+        for hook in hooks {
+            if hook.get("server").and_then(|v| v.as_str()) == Some(HOOK_SERVER) {
+                return true;
+            }
+        }
+    }
+    false
+}
+
+pub fn run_setup(check_only: bool, uninstall: bool) -> Result<()> {
+    anyhow::ensure!(
+        !(check_only && uninstall),
+        "--check and --uninstall cannot be used together"
+    );
+
+    let path = settings_path()?;
+    let mut settings = read_settings(&path)?;
+
+    if check_only {
+        return run_check(&settings, &path);
+    }
+
+    if uninstall {
+        return run_uninstall(&mut settings, &path);
+    }
+
+    run_install(&mut settings, &path)
+}
+
+fn run_check(settings: &Value, path: &Path) -> Result<()> {
+    println!("Settings file: {}", path.display());
+
+    let hooks_obj = settings.get("hooks");
+    let desired = build_hooks_config();
+    let mut all_ok = true;
+
+    for event in desired.keys() {
+        let installed = hooks_obj
+            .and_then(|h| h.get(*event))
+            .map(has_handoff_hook)
+            .unwrap_or(false);
+
+        if installed {
+            println!("  {event}: installed");
+        } else {
+            println!("  {event}: NOT installed");
+            all_ok = false;
+        }
+    }
+
+    if all_ok {
+        println!("\nAll hooks are configured. Memory auto-injection is active.");
+    } else {
+        println!("\nSome hooks are missing. Run `handoff-mcp setup` to install them.");
+    }
+
+    Ok(())
+}
+
+fn run_install(settings: &mut Value, path: &Path) -> Result<()> {
+    let obj = settings
+        .as_object_mut()
+        .context("settings.json root is not an object")?;
+
+    let hooks_val = obj
+        .entry("hooks")
+        .or_insert_with(|| Value::Object(serde_json::Map::new()));
+    let hooks_obj = hooks_val
+        .as_object_mut()
+        .context("settings.json 'hooks' is not an object")?;
+
+    let desired = build_hooks_config();
+    let mut installed = 0u32;
+    let mut skipped = 0u32;
+
+    for (event, config) in desired {
+        let existing = hooks_obj.get(event);
+        if existing.map(has_handoff_hook).unwrap_or(false) {
+            println!("  {event}: already installed, skipping");
+            skipped += 1;
+            continue;
+        }
+
+        match existing {
+            Some(Value::Array(arr)) => {
+                let mut merged = arr.clone();
+                if let Some(new_entries) = config.as_array() {
+                    merged.extend(new_entries.iter().cloned());
+                }
+                hooks_obj.insert(event.to_string(), Value::Array(merged));
+                println!("  {event}: merged with existing hooks");
+            }
+            _ => {
+                hooks_obj.insert(event.to_string(), config);
+                println!("  {event}: installed");
+            }
+        }
+        installed += 1;
+    }
+
+    if installed > 0 {
+        write_settings(path, settings)?;
+        println!("\nWrote {path}", path = path.display());
+        println!("{installed} hook(s) installed, {skipped} already present.");
+        println!("\nRestart Claude Code for hooks to take effect.");
+    } else {
+        println!("\nAll hooks already installed. Nothing to do.");
+    }
+
+    Ok(())
+}
+
+fn run_uninstall(settings: &mut Value, path: &Path) -> Result<()> {
+    let Some(hooks_obj) = settings.get_mut("hooks").and_then(|v| v.as_object_mut()) else {
+        println!("No hooks configured. Nothing to remove.");
+        return Ok(());
+    };
+
+    let events: Vec<String> = hooks_obj.keys().cloned().collect();
+    let mut removed = 0u32;
+
+    for event in &events {
+        let Some(arr) = hooks_obj.get_mut(event).and_then(|v| v.as_array_mut()) else {
+            continue;
+        };
+
+        let before = arr.len();
+        arr.retain(|entry| {
+            let Some(hooks) = entry.get("hooks").and_then(|v| v.as_array()) else {
+                return true;
+            };
+            !hooks
+                .iter()
+                .any(|h| h.get("server").and_then(|v| v.as_str()) == Some(HOOK_SERVER))
+        });
+
+        let after = arr.len();
+        if before != after {
+            println!("  {event}: removed handoff hook(s)");
+            removed += 1;
+        }
+
+        if arr.is_empty() {
+            hooks_obj.remove(event);
+        }
+    }
+
+    if hooks_obj.is_empty() {
+        if let Some(obj) = settings.as_object_mut() {
+            obj.remove("hooks");
+        }
+    }
+
+    if removed > 0 {
+        write_settings(path, settings)?;
+        println!("\nWrote {path}", path = path.display());
+        println!("{removed} hook event(s) cleaned up.");
+        println!("\nRestart Claude Code for changes to take effect.");
+    } else {
+        println!("No handoff hooks found. Nothing to remove.");
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn build_hooks_has_three_events() {
+        let hooks = build_hooks_config();
+        assert_eq!(hooks.len(), 3);
+        assert!(hooks.contains_key("UserPromptSubmit"));
+        assert!(hooks.contains_key("PreToolUse"));
+        assert!(hooks.contains_key("SessionStart"));
+    }
+
+    #[test]
+    fn has_handoff_hook_detects_presence() {
+        let arr = serde_json::json!([{
+            "hooks": [{"type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_query"}]
+        }]);
+        assert!(has_handoff_hook(&arr));
+    }
+
+    #[test]
+    fn has_handoff_hook_returns_false_for_other_server() {
+        let arr = serde_json::json!([{
+            "hooks": [{"type": "mcp_tool", "server": "other", "tool": "other_tool"}]
+        }]);
+        assert!(!has_handoff_hook(&arr));
+    }
+
+    #[test]
+    fn has_handoff_hook_returns_false_for_empty() {
+        assert!(!has_handoff_hook(&serde_json::json!([])));
+    }
+
+    #[test]
+    fn install_into_empty_settings() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        let mut settings = Value::Object(serde_json::Map::new());
+        run_install(&mut settings, &path).unwrap();
+
+        let written: Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        let hooks = written.get("hooks").unwrap().as_object().unwrap();
+        assert!(hooks.contains_key("UserPromptSubmit"));
+        assert!(hooks.contains_key("PreToolUse"));
+        assert!(hooks.contains_key("SessionStart"));
+    }
+
+    #[test]
+    fn install_merges_with_existing_hooks() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        let mut settings = serde_json::json!({
+            "hooks": {
+                "UserPromptSubmit": [{
+                    "hooks": [{"type": "command", "command": "my-other-hook"}]
+                }]
+            }
+        });
+
+        run_install(&mut settings, &path).unwrap();
+
+        let written: Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        let user_prompt = written["hooks"]["UserPromptSubmit"].as_array().unwrap();
+        assert_eq!(user_prompt.len(), 2);
+        assert!(has_handoff_hook(&written["hooks"]["UserPromptSubmit"]));
+    }
+
+    #[test]
+    fn install_skips_if_already_present() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        let mut settings = Value::Object(serde_json::Map::new());
+        run_install(&mut settings, &path).unwrap();
+
+        let mut settings2 = serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        run_install(&mut settings2, &path).unwrap();
+
+        let written: Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        let user_prompt = written["hooks"]["UserPromptSubmit"].as_array().unwrap();
+        assert_eq!(user_prompt.len(), 1);
+    }
+
+    #[test]
+    fn uninstall_removes_handoff_hooks() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        let mut settings = Value::Object(serde_json::Map::new());
+        run_install(&mut settings, &path).unwrap();
+
+        let mut settings2: Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        run_uninstall(&mut settings2, &path).unwrap();
+
+        let written: Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        assert!(written.get("hooks").is_none());
+    }
+
+    #[test]
+    fn check_and_uninstall_conflict_is_rejected() {
+        assert!(run_setup(true, true).is_err());
+    }
+
+    #[test]
+    fn install_preserves_key_order() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        let original = r#"{
+  "env": {"A": "1", "B": "2"},
+  "model": "opus",
+  "permissions": {"defaultMode": "auto"}
+}
+"#;
+        std::fs::write(&path, original).unwrap();
+
+        let mut settings: Value = serde_json::from_str(original).unwrap();
+        run_install(&mut settings, &path).unwrap();
+
+        let written = std::fs::read_to_string(&path).unwrap();
+        let env_pos = written.find("\"env\"").unwrap();
+        let hooks_pos = written.find("\"hooks\"").unwrap();
+        let model_pos = written.find("\"model\"").unwrap();
+        assert!(env_pos < model_pos, "env should come before model");
+        assert!(
+            hooks_pos > env_pos,
+            "hooks should be appended after existing keys"
+        );
+    }
+
+    #[test]
+    fn uninstall_preserves_other_hooks() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("settings.json");
+
+        let mut settings = serde_json::json!({
+            "hooks": {
+                "UserPromptSubmit": [
+                    {"hooks": [{"type": "command", "command": "my-hook"}]},
+                    {"hooks": [{"type": "mcp_tool", "server": "handoff", "tool": "handoff_memory_query"}]}
+                ]
+            }
+        });
+        run_uninstall(&mut settings, &path).unwrap();
+
+        let written: Value =
+            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        let user_prompt = written["hooks"]["UserPromptSubmit"].as_array().unwrap();
+        assert_eq!(user_prompt.len(), 1);
+        assert!(!has_handoff_hook(&written["hooks"]["UserPromptSubmit"]));
+    }
+}