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

[knqiufan]

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 Tracking Issue: local Server availability and service installation #1298 / RFC docs(rfc): define local Server service-installation boundaries #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 Tracking Issue: local Server availability and service installation #1298 / RFC docs(rfc): define local Server service-installation boundaries #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:

• Tracking Issue: Agent Integrations for PowerContext #1213 tracks Agent integration roadmap; it does not add a composite setup command
• Tracking Issue: local Server availability and service installation #1298 / RFC docs(rfc): define local Server service-installation boundaries #1299 cover Server availability and personal service installation, not plugin install orchestration
• feat(pi): add native Pi Coding Agent support #1258, feat: Pydantic AI framework integration #1269, feat: LangGraph framework integration #1270, feat(integrations/OpenClaw): research on OpenClaw memory and how to integrate PowerContext as a multi-session Memory Provider #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.

[knqiufan]

Follow-up: revise the orchestration contract before implementation

I still want this issue. The gap is real: first-class hosts already have independent installers, and a multi-agent machine has no official way to enable more than one of them in a single, isolated run.

I no longer think PATH-driven setup detected is the right contract. After comparing it with the current CLI, plugin, and product rules, I want to replace discovery-driven install with catalog + explicit selection + failure isolation. I will implement and open a PR against this revised design.

Why auto-scan is the weaker shape

The current product is explicit at every adjacent boundary:

• powercontext setup with no subcommand still prints help and mutates nothing.
• setup <host> is fail-closed for that host only.
• Plugins never start or embed the Server; setup also never starts the Server.
• Claude Code setup is user-scope and defaults capture_prompts=True.
• Memory writes, Handoff, and scope selection are all user-authorized, not inferred.

PATH presence is not intent. A laptop can have Codex, Claude Code, and DSH on PATH while the user only wants PowerContext on one of them. Auto-installing every detected host would mutate host marketplaces, settings, and prompt-capture behavior without a per-host choice. That is more surprising than asking the user to pick.

There is also no project-local “already connected agents” inventory to scan. Codex / Claude Code / DSH / Hermes setup talks to user-scope host CLIs, not to a per-repo plugin list. The honest menu is the first-class setup catalog, not a guessed project scan and not a PATH scan.

The current tree already has four first-class setup targets: codex, claude-code, dsh, and hermes. A scanner frozen to the original three would rot immediately.

This command must not “launch agents”. Starting Codex, Claude Code, DSH, Hermes, or the PowerContext Server is out of scope. The command only installs or refreshes the selected host plugins.

Revised user contract

Keep the existing per-host commands as the explicit path:

powercontext setup codex
powercontext setup claude-code
powercontext setup dsh
powercontext setup hermes

Add one opt-in orchestration command. Suggested name, still bikesheddable; detected is no longer accurate:

powercontext setup select
powercontext setup select --host codex --host dsh
powercontext setup select --host codex --json

Behavior:

1. List the current first-class setup registry. Do not PATH-scan to build or filter that list. Do not invent a project-local plugin inventory.
2. Interactive TTY and no --host: prompt the user to choose one or more hosts. Empty selection installs nothing and exits 0.
3. Non-interactive or --json: --host is required and repeatable. Do not prompt.
4. For each selected host, call the existing installer (install_codex_plugin, install_claude_code_plugin, install_dsh_plugin, install_hermes_plugin) with the current defaults. Claude-only flags keep their current defaults when Claude is selected.
5. If a selected host CLI is missing, or its installer fails (Claude marketplace conflict, unbuilt DSH lib/index.js, and so on), record failed with the existing SetupError text. Continue the remaining selected hosts. Do not roll back a sibling that already succeeded. Claude’s existing marketplace/plugin rollback stays local to Claude.
6. Unselected hosts are skipped because the user did not choose them, not because they were “not detected”.
7. Print a per-host matrix: selected | skipped | installed | failed. When at least one plugin was installed, print the usual next step: run powercontext server run, then start a new host session.
8. Exit 0 when every selected host succeeded or was already installed. Exit non-zero when any selected host failed.
9. A second run stays idempotent: already-installed plugins are installed/unchanged, not a hard error.

Rules that must not change:

• powercontext setup with no subcommand still prints help.
• setup <host> still fails closed when that host CLI is missing.
• Setup never starts the Server and never enables a login service.
• doctor stays read-only. A later doctor integrations can show CLI/plugin status; that probe does not belong in the mutating setup command.

What stays from the original proposal

• This is orchestration over current installers, not a second plugin installer.
• Shared host registry in the setup/doctor CLI module.
• Failure isolation across hosts.
• DSH honesty: missing lib/index.js fails that row only.
• Docs keep per-host commands as the explicit path and present the composite command as optional.

Revised acceptance criteria

• Fresh install: powercontext setup still prints help.
• User selects Codex and DSH; Claude is unselected: the command installs Codex and DSH only, even if claude is on PATH.
• Selected host missing from PATH: that row fails with the existing unavailable error; other selected hosts continue.
• --json without --host errors and does not prompt.
• setup codex on a machine without Codex still errors exactly as it does today.
• Docs show setup select as the optional multi-host path.

I will implement this revised contract and open a PR against this issue.