feat: add opt-in setup for all detected local agent CLIs

Feature description

Keep the existing per-integration setup commands as the explicit path:

powercontext setup codex
powercontext setup claude-code
powercontext setup dsh

Add one opt-in command that inspects the current user environment for those host CLIs and installs the matching PowerContext plugin for each CLI that is already present. Suggested name, still bikesheddable:

powercontext setup detected

A machine that already has Codex, Claude Code, and DeepSeek Harness on PATH would then need one command instead of three. A machine that only has Codex would install the Codex plugin and skip the rest.

This command stays optional. powercontext setup with no subcommand continues to print help. The existing single-target commands keep their current fail-closed behavior when the host CLI is missing.

First version covers only the current first-class setup targets: codex, claude-code, and dsh.

Problem and proposed solution

Why this issue exists

The documented onboarding path is already a sequence of host-specific commands. Official install docs tell the user to run setup codex and setup dsh separately; Claude Code is a third command with its own flags. Each command is correct in isolation: it talks to one host CLI, installs one plugin, and fails if that CLI is not on PATH.

That design does not match a common local machine. Many contributors and users already have more than one coding agent installed. After uv tool install powercontext, they still have to remember which hosts they have and retype one setup command per host. Missing a host is silent later: doctor without a subcommand does not scan integrations, and the leftover agent simply has no PowerContext plugin.

This is not a defect in setup codex / setup claude-code / setup dsh. Those commands should stay explicit and fail when their host is absent. The gap is the missing orchestration entry for "install every plugin whose host is already here."

Gap this fills

Today the product has:

• three independent installers;
• three independent doctor subcommands;
• PATH probes inside each installer (which("codex"), which("claude"), which("dsh") / dsh.cmd);
• no command that uses those probes as a discovery list;
• no composite setup command.

setup is no_args_is_help=True. doctor without a subcommand checks only the PowerContext package and Server liveness/readiness. Neither surface answers "which local agents are present, and which plugins are still missing?"

Value

• One command finishes local plugin install on a multi-agent laptop.
• Users do not have to remember the exact setup subcommand for each host they already use.
• Missing hosts are skipped instead of aborting the whole run, which is the failure mode if someone just concatenates the three current commands in a shell.
• Existing single-target commands, defaults, and docs remain valid.
• The same detection can later feed a read-only doctor summary, without making doctor install anything.

Proposed user contract

powercontext setup detected
powercontext setup detected --json

Behavior:

1. Probe only the current first-class hosts, with the same PATH rules the single-target installers already use.
2. For each missing host, record skipped and continue. Do not exit 1 only because Claude Code or DSH is absent.
3. For each detected host, call the existing installer (install_codex_plugin, install_claude_code_plugin, install_dsh_plugin) with the same source / ref defaults, plus Claude Code's existing server_url and capture_prompts defaults.
4. If a detected host's install fails, record failed with the existing SetupError text. Do not hide Claude marketplace conflicts or an unbuilt DSH plugin.
5. Print a per-host matrix: detected | skipped | installed | failed, then the usual "Next: run powercontext server run" note when at least one plugin was installed.
6. Exit 0 when every detected host succeeded or was already installed. Exit non-zero when any detected host failed.
7. A second run is idempotent: already-installed plugins are reported as installed/unchanged, not as a hard error.

Rules that must not change:

• powercontext setup with no subcommand still prints help and installs nothing.
• setup codex / setup claude-code / setup dsh still fail when their host CLI is missing.
• setup never starts the Server and never enables a login service. That remains #1298 / RFC #1299.
• Detection is PATH-based, same as today. A GUI or version-manager install that is not on PATH is out of scope for v1.
• Do not auto-discover research integrations that have no first-class setup yet (Pi, OpenClaw, Hermes, LangGraph, Pydantic AI).

Implementation suggestion

This should be orchestration over the current functions, not a second plugin installer.

1. Shared host registry in the setup/doctor CLI module: name, PATH probe, install function, diagnostic function. Today that list is three rows.
2. setup detected walks the registry, classifies each row, and reuses the existing installers. Shared --source / --ref / --json flags pass through. Claude-only flags (--server-url, --capture-prompts) keep their current defaults when the Claude host is detected.
3. Failure isolation: one host failure must not roll back a sibling host that already succeeded. Claude's existing marketplace/plugin rollback stays local to Claude.
4. DSH honesty: if dsh is on PATH but the plugin tree has no lib/index.js, report that host as failed with the current unbuilt-plugin error. Do not pretend detection guarantees a successful install.
5. Optional follow-up, not required for v1: powercontext doctor or doctor integrations can print the same detected/missing/plugin matrix as a read-only view. Keep that out of the install command.
6. Tests: table-driven cases for none detected, one detected, all three detected, already installed, detected-but-install-failed, and "single-target commands still fail when the host is missing."

Acceptance criteria

• Fresh install: powercontext setup still prints help.
• Host A and B on PATH, host C absent: setup detected installs A and B, skips C, exits 0.
• No first-class host on PATH: command exits 0 and reports three skips. It does not install anything.
• Detected DSH with a missing lib/index.js fails that row and does not undo a successful Codex install in the same run.
• setup codex on a machine without Codex still errors exactly as it does today.
• Docs show setup detected as the optional multi-host path and keep the per-host commands as the explicit path.

Alternatives considered

1. Tell users to run the three commands themselves. This already works, and it is what the docs do. A shell one-liner still fails closed on the first missing host, which is the opposite of "install whatever is here."
2. Change powercontext setup with no subcommand into the auto-installer. Too surprising. The current help-only default is the safe contract.
3. Start from doctor and install as a side effect. doctor is a read-only environment check. Mixing mutation into it would blur the setup/doctor split.
4. Start Server or enable a login service from this command. That is a different lifecycle problem and is already tracked by #1298 / RFC #1299.
5. Discover every future agent automatically. Pi, OpenClaw, and similar hosts do not have a first-class setup command yet. A generic registry would be a new extension mechanism and should not block this issue.
6. Open an RFC first. The current proposal only composes existing installers and keeps every current command unchanged. If maintainers consider the new CLI contract substantial, I will follow the RFC process. I would rather confirm the skip/fail matrix here first.

Additional context

Sources:

• src/powercontext/cli/system.py — setup is help-only without a subcommand; setup codex / setup claude-code / setup dsh fail when which(...) misses; doctor without a subcommand does not scan integrations
• src/powercontext/cli/dsh.py — DSH also requires a built lib/index.js
• docs/en/docs/how-to/install-and-run.md and docs/en/docs/how-to/troubleshoot.md — official path is one setup command per host; missing host CLI is an error, not a skip

Related but not duplicates:

• #1213 tracks Agent integration roadmap; it does not add a composite setup command
• #1298 / RFC #1299 cover Server availability and personal service installation, not plugin install orchestration
• #1258, #1269, #1270, #1281 are future or research integrations and are out of scope for v1

Dedup: searched setup detected, setup all, composite plugin install, and doctor integration scanning. No existing tracker for this orchestration command as of 2026-08-21.

I am willing to implement this after the skip/fail matrix is confirmed. If you consider this CLI contract substantial, I can follow up with an RFC; otherwise I am happy to implement against this issue.

Are you willing to contribute to this feature?

• Yes, I am willing to contribute code, docs, or design feedback.

Start in src/powercontext/cli/system.py, where the setup subcommands and existing host checks are defined, and read src/powercontext/cli/dsh.py for DSH's built-plugin requirement. Trace the current installers and add table-driven coverage for no hosts, partial detection, all hosts, idempotency, failures, and unchanged single-target errors. Update docs/en/docs/how-to/install-and-run.md and docs/en/docs/how-to/troubleshoot.md so the optional detected path and its outcomes are documented.