handoff-mcp-server 0.13.0 → 0.15.0

package/Cargo.lock

@@ -13,9 +13,9 @@ dependencies = [
 
 [[package]]
 name = "anyhow"
-version = "1.0.102"
+version = "1.0.103"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
+checksum = "2a4385e2e34eb35d6b3efe798b9eb88096925d87726c0798709bf56d9ed84af3"
 
 [[package]]
 name = "autocfg"
@@ -37,9 +37,9 @@ checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
 [[package]]
 name = "cc"
-version = "1.2.64"
+version = "1.2.65"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dad887fd958be91b5098c0248def011f4523ab786cd411be668777e55063501f"
+checksum = "e228eec9be7c17ccb640b59b36a5cd805ea2a564a4c5e162c2f659fea30d3b96"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -99,12 +99,6 @@ version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
 
-[[package]]
-name = "foldhash"
-version = "0.1.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
-
 [[package]]
 name = "futures-core"
 version = "0.3.32"
@@ -131,20 +125,18 @@ dependencies = [
 
 [[package]]
 name = "getrandom"
-version = "0.4.2"
+version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0de51e6874e94e7bf76d726fc5d13ba782deca734ff60d5bb2fb2607c7406555"
+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
 dependencies = [
  "cfg-if",
  "libc",
  "r-efi",
- "wasip2",
- "wasip3",
 ]
 
 [[package]]
 name = "handoff-mcp"
-version = "0.13.0"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "chrono",
@@ -157,27 +149,12 @@ dependencies = [
  "toml_edit",
 ]
 
-[[package]]
-name = "hashbrown"
-version = "0.15.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
-dependencies = [
- "foldhash",
-]
-
 [[package]]
 name = "hashbrown"
 version = "0.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
 
-[[package]]
-name = "heck"
-version = "0.5.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
-
 [[package]]
 name = "iana-time-zone"
 version = "0.1.65"
@@ -202,12 +179,6 @@ dependencies = [
  "cc",
 ]
 
-[[package]]
-name = "id-arena"
-version = "2.3.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954"
-
 [[package]]
 name = "indexmap"
 version = "2.14.0"
@@ -215,9 +186,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
  "equivalent",
- "hashbrown 0.17.1",
- "serde",
- "serde_core",
+ "hashbrown",
 ]
 
 [[package]]
@@ -228,21 +197,15 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
 [[package]]
 name = "js-sys"
-version = "0.3.102"
+version = "0.3.103"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "03d04c30968dffe80775bd4d7fb676131cd04a1fb46d2686dbffbaec2d9dfd31"
+checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102"
 dependencies = [
  "cfg-if",
  "futures-util",
  "wasm-bindgen",
 ]
 
-[[package]]
-name = "leb128fmt"
-version = "0.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
-
 [[package]]
 name = "lexsim"
 version = "0.1.0"
@@ -267,9 +230,9 @@ checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
 
 [[package]]
 name = "log"
-version = "0.4.32"
+version = "0.4.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "953f07c43838f8e6f9758cab68bf5bed85465e7587ebe0b823f1bcd81978ad3a"
+checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 
 [[package]]
 name = "memchr"
@@ -298,16 +261,6 @@ version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
-[[package]]
-name = "prettyplease"
-version = "0.2.37"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
-dependencies = [
- "proc-macro2",
- "syn",
-]
-
 [[package]]
 name = "proc-macro2"
 version = "1.0.106"
@@ -319,9 +272,9 @@ dependencies = [
 
 [[package]]
 name = "quote"
-version = "1.0.45"
+version = "1.0.46"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
 dependencies = [
  "proc-macro2",
 ]
@@ -351,12 +304,6 @@ version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
 
-[[package]]
-name = "semver"
-version = "1.0.28"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
-
 [[package]]
 name = "serde"
 version = "1.0.228"
@@ -393,6 +340,7 @@ version = "1.0.150"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
 dependencies = [
+ "indexmap",
  "itoa",
  "memchr",
  "serde",
@@ -423,9 +371,9 @@ checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
 
 [[package]]
 name = "syn"
-version = "2.0.117"
+version = "2.0.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -542,35 +490,11 @@ version = "1.13.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
 
-[[package]]
-name = "unicode-xid"
-version = "0.2.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
-
-[[package]]
-name = "wasip2"
-version = "1.0.4+wasi-0.2.12"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
-dependencies = [
- "wit-bindgen 0.57.1",
-]
-
-[[package]]
-name = "wasip3"
-version = "0.4.0+wasi-0.3.0-rc-2026-01-06"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5428f8bf88ea5ddc08faddef2ac4a67e390b88186c703ce6dbd955e1c145aca5"
-dependencies = [
- "wit-bindgen 0.51.0",
-]
-
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.125"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8ddb3f79143bced6de84270411622a2699cee572fc0875aeaf1e7867cf9fca1a"
+checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4"
 dependencies = [
  "cfg-if",
  "once_cell",
@@ -581,9 +505,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.125"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4e21a184b13fb19e157296e2c46056aec9092264fab83e4ba59e68c61b323c3d"
+checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -591,9 +515,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.125"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fecefd9c35bd935a20fc3fc344b5f29138961e4f47fb03297d88f2587afb5ebd"
+checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e"
 dependencies = [
  "bumpalo",
  "proc-macro2",
@@ -604,47 +528,13 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.125"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "23939e44bb9a5d7576fa2b563dc2e136628f1224e88a8deed09e04858b77871f"
+checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24"
 dependencies = [
  "unicode-ident",
 ]
 
-[[package]]
-name = "wasm-encoder"
-version = "0.244.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "990065f2fe63003fe337b932cfb5e3b80e0b4d0f5ff650e6985b1048f62c8319"
-dependencies = [
- "leb128fmt",
- "wasmparser",
-]
-
-[[package]]
-name = "wasm-metadata"
-version = "0.244.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bb0e353e6a2fbdc176932bbaab493762eb1255a7900fe0fea1a2f96c296cc909"
-dependencies = [
- "anyhow",
- "indexmap",
- "wasm-encoder",
- "wasmparser",
-]
-
-[[package]]
-name = "wasmparser"
-version = "0.244.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe"
-dependencies = [
- "bitflags",
- "hashbrown 0.15.5",
- "indexmap",
- "semver",
-]
-
 [[package]]
 name = "windows-core"
 version = "0.62.2"
@@ -722,100 +612,6 @@ dependencies = [
  "memchr",
 ]
 
-[[package]]
-name = "wit-bindgen"
-version = "0.51.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d7249219f66ced02969388cf2bb044a09756a083d0fab1e566056b04d9fbcaa5"
-dependencies = [
- "wit-bindgen-rust-macro",
-]
-
-[[package]]
-name = "wit-bindgen"
-version = "0.57.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
-
-[[package]]
-name = "wit-bindgen-core"
-version = "0.51.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ea61de684c3ea68cb082b7a88508a8b27fcc8b797d738bfc99a82facf1d752dc"
-dependencies = [
- "anyhow",
- "heck",
- "wit-parser",
-]
-
-[[package]]
-name = "wit-bindgen-rust"
-version = "0.51.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b7c566e0f4b284dd6561c786d9cb0142da491f46a9fbed79ea69cdad5db17f21"
-dependencies = [
- "anyhow",
- "heck",
- "indexmap",
- "prettyplease",
- "syn",
- "wasm-metadata",
- "wit-bindgen-core",
- "wit-component",
-]
-
-[[package]]
-name = "wit-bindgen-rust-macro"
-version = "0.51.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0c0f9bfd77e6a48eccf51359e3ae77140a7f50b1e2ebfe62422d8afdaffab17a"
-dependencies = [
- "anyhow",
- "prettyplease",
- "proc-macro2",
- "quote",
- "syn",
- "wit-bindgen-core",
- "wit-bindgen-rust",
-]
-
-[[package]]
-name = "wit-component"
-version = "0.244.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2"
-dependencies = [
- "anyhow",
- "bitflags",
- "indexmap",
- "log",
- "serde",
- "serde_derive",
- "serde_json",
- "wasm-encoder",
- "wasm-metadata",
- "wasmparser",
- "wit-parser",
-]
-
-[[package]]
-name = "wit-parser"
-version = "0.244.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ecc8ac4bc1dc3381b7f59c34f00b67e18f910c2c0f50015669dde7def656a736"
-dependencies = [
- "anyhow",
- "id-arena",
- "indexmap",
- "log",
- "semver",
- "serde",
- "serde_derive",
- "serde_json",
- "unicode-xid",
- "wasmparser",
-]
-
 [[package]]
 name = "zmij"
 version = "1.0.21"

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.13.0"
+version = "0.15.0"
 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:
@@ -159,14 +198,22 @@ rename) so a concurrent reader never sees a partially-written file.
 | `handoff_get_referral` | Fetch one incoming referral in full — details, suggested tasks, done_criteria, context |
 | `handoff_update_referral` | Update referral status (open → acknowledged → resolved) |
 
+### Timer Coordination
+
+| Tool | Purpose |
+|------|---------|
+| `handoff_timer_start` | Start tracking time for a task — delegates to VSCode extension if alive, otherwise starts MCP fallback timer |
+| `handoff_timer_stop` | Stop the timer and log elapsed hours to `actual_hours` — delegates to VSCode if alive |
+| `handoff_timer_get_time` | Get current timer state (elapsed, authority, projected total) without stopping |
+
 ### Project Memory
 
 | 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.
 
@@ -240,6 +287,9 @@ done_task_limit = 10          # Max completed tasks to show
 auto_git_summary = true       # Capture git state automatically
 require_estimate_hours = true # Require estimate_hours on leaf tasks (default true)
 ai_estimate_multiplier = 0.2  # Multiplier turning human estimates into AI-effort hours
+timer_provider = "auto"       # "auto" | "vscode" | "mcp" | "off"
+timer_authority_ttl_secs = 30 # Heartbeat freshness TTL for authority.json
+timer_idle_timeout_minutes = 10 # Idle pause threshold for MCP fallback timer
 
 [dashboard]
 scan_dirs = ["~/pro/"]     # Directories to scan for dashboard
@@ -300,6 +350,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 +364,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 +402,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 +418,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,11 +468,50 @@ 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 |
 
+## CLI API
+
+Since v0.15.0, every MCP tool is also callable directly from the shell:
+
+```bash
+handoff-mcp <group> <action> [--key value ...]
+```
+
+All output is JSON on stdout, suitable for scripting and programmatic use
+(e.g. `child_process.execFile` from a VSCode extension).
+
+**Examples:**
+
+```bash
+# Memory operations
+handoff-mcp memory save --text "Always use atomic_write" --kind lesson --tags safety,io
+handoff-mcp memory query --text "atomic" --limit 5
+handoff-mcp memory delete --id m-20260630-...
+
+# Task management
+handoff-mcp task list --status-filter todo
+handoff-mcp task update --id t1 --title "New task" --status todo --estimate-hours 2
+handoff-mcp task log-time --task-id t1 --hours 0.5
+
+# Session and metrics
+handoff-mcp session load
+handoff-mcp metrics
+handoff-mcp dashboard
+```
+
+**Available groups:** `init`, `task`, `session`, `config`, `memory`,
+`referral`, `assignee`, `milestone`, `calendar`, `labels`, `project`,
+`metrics`, `capacity`, `schedule`, `dashboard`, `timer`.
+
+Run `handoff-mcp --help` to see all groups, or `handoff-mcp <group> --help`
+for actions within a group. See the
+[CLI API Reference](https://github.com/alphaelements/handoff-mcp/wiki/CLI-API-Reference)
+on the wiki for the full command list.
+
 ## MCP Resources
 
 | URI | Description |
@@ -445,9 +539,13 @@ 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,
+- **Timer**: Use `handoff_timer_start` / `handoff_timer_stop` to track task time.
+  When the VSCode extension is running, the timer delegates to it automatically.
+  When the extension is absent, MCP runs a fallback timer and logs hours on stop.
+  Use `handoff_timer_get_time` to check elapsed time without stopping.
+- **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.15.0",
   "description": "MCP server that gives AI coding agents persistent memory across sessions",
   "license": "MIT",
   "author": "AlphaElements <66808803+alphaelements@users.noreply.github.com>",