Skip to content

MCP slimdown — Move 2: CLI parity for 13 deprecation candidates #80

@mbachaud

Description

@mbachaud

Parent spec: `docs/specs/2026-05-12-mcp-slimdown-plan.md` (PR #78).

Depends on / blocks: #79 (Move 1) — independent, but cleaner to land
identity unification first so deprecation warnings have a TOML-pointed
home for opt-in.

Goal

Build CLI peers for 13 of the 17 MCP tools we're deprecating so the
slimdown is non-breaking before tool removal.

Scope (4 new subcommand clusters)

`helix sessions {list, recent, register}`

  • Replaces `helix_sessions_list`, `helix_session_recent`.
  • `helix sessions list [--party X] [--status active|stale|all]`
  • `helix sessions recent [--limit N] [--since UNIX_TS]`
  • `helix sessions register --handle X --party Y [--host Z]` (the
    CLI equivalent of `POST /sessions/register` from MCP startup).
  • Reuses `helix_context/bridge.py` — CLI becomes the third caller
    alongside MCP and the HTTP server.

`helix status` flag expansion

  • `helix status --stats` → replaces `helix_stats`.
  • `helix status --tokens` → replaces `helix_metrics_tokens`.
  • `helix status --bridge` → replaces `helix_bridge_status`.
  • All three coexist with existing `helix status` default output.

`helix diag` subcommand additions

  • `helix diag gene ` → `helix_gene_get`
  • `helix diag neighbors [--top-k N]` → `helix_neighbors`
  • `helix diag splice ` → `helix_splice_preview`
  • `helix diag resonance ` → `helix_resonance`
  • `helix diag fingerprint ` → `helix_fingerprint`
  • `helix diag refresh-plan ` → `helix_refresh_targets`
  • `helix diag hitl [--since UNIX_TS] [--limit N]` → `helix_hitl_recent`

`helix consolidate`

  • `helix consolidate [--source-ids X,Y,Z]` → `helix_consolidate`.
  • Cold-start subcommand (single shot, exits).

Estimate

~3 days total; each subcommand is ~40 LOC of argparse + bridge call +
JSON/text formatter. Tests follow `tests/test_cli_*.py` pattern (one
test file per cluster).

Acceptance

  • `helix --help` lists `sessions`, `consolidate` as first-class
    subcommands; `helix diag --help` lists 7 new operations.
  • Each new subcommand has at least 3 tests (success + error + JSON).
  • Existing MCP tools still work — this is additive, no MCP changes yet.
  • Docs: `docs/clients/cli.md` gains 4 new sections.

Not in scope

  • Removing or warning on MCP tools (that's Move 3).
  • Touching `helix_announce` or `helix_hitl_emit` — deliberately
    CLI-incompatible per spec §"Non-goals" and §"HITL — split".

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions