Extract the CLI monolith incrementally: per-domain *_cli.py modules with register(subparsers), shared helpers in core.py

[dotdevdotdev]

Goal

Reduce the 12,767-line __main__.py god-module to an entrypoint + dispatch by continuing the established *_cli.py extraction pattern, moving shared helpers out of the entrypoint, and breaking up the ~1,460-line main() argparse builder — all incrementally, one domain per PR.

Why it matters

__main__.py holds 121 inline cmd_* functions across ~20 domains; the extraction pattern is validated but partial (only council/limits/msg/prompts live in dedicated modules). CLAUDE.md names this file as the SSOT, so it's both an onboarding barrier and the constant merge-conflict surface for a project trying to grow contributors. Three concrete sub-problems: (a) main() (:11308-12767) is one ~1,460-line function building 169 subparsers, untestable as a unit; (b) ~29 stateless helpers (tmux_session_exists :462, load/store_session_metadata :3051/3075, load_config :532, build_agent_command) are trapped in the entrypoint, so prompt_router.py:201 reimplements the metadata-path read instead of reusing load_session_metadata, and 6 inline tmux has-session -t =... strings (:886, 942, 1391, 1442, 3804, 6250) bypass the helper and re-type the = prefix inconsistently; (c) the portal's api_check_path/api_check_branches (server.py:3059-3164) embed forked local/SSH git logic inline, violating the stated 'portal calls CLI, doesn't duplicate logic' rule. NOTE: server.py/mcp_server.py are intentionally thin wrappers that shell to the CLI — do NOT make them import helpers; the genuine in-process import candidate is prompt_router.py.

Proposed approach

1. Create agentwire/core.py and move the stateless helpers there; replace the 6 inline tmux has-session strings with tmux_session_exists() and the prompt_router.py:201 read with load_session_metadata().
2. Per domain, add a *_cli.py exporting its cmd_* and a register(subparsers) that builds only its own argparse subtree; main() loops over the register() callables. Each register() becomes independently unit-testable (unblocks the CLI smoke-test issue).
3. Add agentwire repo-info/agentwire branches --json to the CLI and have the portal git endpoints call them.
4. Target __main__.py under ~500 lines (entry + dispatch).

Effort / risk

Effort L, but each step is mechanical and reviewable in isolation. Risk: low (pure relocation; the *_cli.py and sibling-import patterns are already proven). Lower-priority tech debt — sequence after security + growth work.

[dotdevdotdev]

Execution started — feature branch `cli-extraction`

Decomposed into 3 phases on the `cli-extraction` feature branch; every worktree session forks off it and PRs back into it (final `cli-extraction → main` merge gated by owner).

Recon (verified): dispatch is clean `set_defaults(func=)` + `if hasattr(args,"func")` — no if/elif chain. The real cross-domain `cmd_*` call graph is 5 edges (worktree→new, ensure→new, up→stt_start, up→dev, portal_restart→portal_start/stop), so domains are near-independent and the `diff_cli` deferred-import pattern covers the rest. Extraction parallelizes safely.

Phase 0 — Foundation (in flight, blocking). New `agentwire/core.py` (~32 stateless helpers + `CONFIG_DIR`); fix the 6 inline `tmux has-session` strings + the `prompt_router.py`/`diff_cli.py` consumers; convert dispatch to a `_REGISTRARS` loop; finish `limits_cli`. Pure relocation, CLI surface unchanged.

Phase 1 — Domain extractions (7 parallel sessions, 2 waves). Balanced/cohesive groups: `services` (portal/tts/stt/kokoro/voiceclone/say/channels) · `session` (new/fork/worktree/recreate) · `panes` (list/info/output/kill/spawn/split/detach/jump/resize/send/send_keys) · `scheduler` (scheduler/ensure/task/lock) · `diagnostics` (doctor/network/safety/machine/history) · `integrations` (roles/projects/hooks/tunnels/handoff/mcp) · `system` (notify/open/wiki/research + up/dev/init/listen/scratchpad/services/rebuild/uninstall). Merged one-at-a-time into the feature branch.

Phase 2 — Portal git endpoints + final trim. Add `repo-info`/`branches --json`, rewire `server.py:3059–3164` to shell to the CLI, verify `main.py` ≤ ~500 lines, update CLAUDE.md.

[dotdevdotdev]

Phase 0 (foundation) PR opened: #529 → base cli-extraction. New agentwire/core.py holds the ~32 stateless helpers + AgentCommand/CONFIG_DIR/_UNATTENDED_ENV_KEYS; __main__ re-imports them. prompt_router + diff_cli now consume core; build_parser() runs a _REGISTRARS loop and limits_cli gained register_limits_parser(). Sub-problem (b) was wrong — the 6 inline tmux has-session strings are all remote-over-SSH/_run_remote, not local-helper bypasses, so that swap was dropped (no behavior change). Pure relocation; ruff clean, 2017 unit tests pass.

[dotdevdotdev]

✅ Phase 0 merged into cli-extraction (#529, squash 583436a). agentwire/core.py now holds the ~32 stateless helpers + CONFIG_DIR; prompt_router/diff_cli reuse it; dispatch runs through a _REGISTRARS loop; limits_cli finished. Deliverable #3 (swap inline tmux has-session → tmux_session_exists) dropped — all 6 sites are remote-over-SSH/_run_remote, not local-helper bypasses; #495 premise (b) was incorrect. Verified independently: ruff clean, full CLI parser surface builds, 2017 unit tests pass. Dispatching Phase 1 Wave 1 (services, session, panes — the 3 fully-independent groups) now.

[dotdevdotdev]

✅ Phase 0.5 merged into cli-extraction (#530, squash 2b642c3). Swept 14 cross-group shared helpers into core.py (_run_remote + the portal-client / session-type / git-status / desktop-notify primitives + _start_portal_local/_install_global_tmux_hooks), verified each by call-site→group mapping. Foundation now fully decouples the domain groups.

🚀 Wave 1 dispatched (3 parallel worktree sessions off cli-extraction): cli-services (portal/tts/stt/kokoro/voiceclone/say/channels → portal_cli/tts_cli/channels_cli), cli-session (new/fork/worktree/recreate → session_cli), cli-panes (list/info/output/kill/spawn/split/detach/jump/resize + send → pane_cli/send_cli). Zero cross-module edges among the three; each PRs into cli-extraction, merged one-at-a-time.