# Local agent installer

`edge agents` (also `npx -y @getedge/mcp agents`) lists Claude Code, Codex,
Cursor, their user config paths, CLI availability on PATH and existing Edge
connections. Detection reads only those config files and PATH entries, when
this command runs. It does not start clients, inspect sessions, create identity,
send telemetry or change files. It also recognizes the enabled Claude Edge plugin in user settings. It does not
discover project or managed connections; those can override the user connection.

Choose a target with `edge agents claude`, `edge agents codex` or
`edge agents cursor`. The command prints the exact config line replacement,
native command when applicable, backup and ownership locations. Only typing
`yes` in an interactive terminal permits writes. There is no implicit approval,
`--yes` switch or noninteractive install. Canceling leaves files untouched.

Claude uses `claude mcp add-json --scope user`; Codex uses `codex mcp add`
when its executable is available. Native registration runs in a private staging
config home after approval. The final write applies the reviewed representation,
using PR #439's Codex direct-exposure planner (both `deferred` and `code_mode`
omitted, existing settings preserved). Cursor writes its global `mcp.json`.
Claude requires its native CLI. Codex can configure an installation whose CLI
is not on PATH. The installer pins the connector to its own package version.

New entries share an install-state directory, reusing an existing configured
identity when present. PR #439's dedicated Codex runtime is deleted by
`setup codex --remove`, so its install id is copied into `~/.config/edge`
(shown in the preview) instead of pointing another agent at that directory. Existing
connections keep their environment. If several independent installations are
already configured, set `EDGE_INSTALL_STATE_DIR` explicitly to select the one
to share. Nothing copies keys or other credentials between agents.

After approval, each transaction saves a private JSON backup under
`~/.config/edge/backups/` (or `$EDGE_INSTALL_STATE_DIR/backups/`) with the original config, mode and ownership record.
A lock prevents overlapping installer writes; changed configs invalidate previews.
Atomic writes and read-back verification protect the final config. Errors restore
both config and ownership bytes. Backups also support manual recovery after
process termination: the backup's `before` and `recordsText` values are the exact
original bytes (null means the file was absent). A crash can leave `agents.lock`;
after confirming no installer is running, remove that empty directory and retry.
Verification checks saved configuration, not a live MCP handshake or OAuth.

`edge agents <agent> --remove` previews and approves removal. It only undoes
recorded changes. Pre-existing connections are never adopted. Unrelated edits
are kept; editing a managed entry makes removal refuse rather than delete user
changes. Repeated installation and removal are no-ops when already satisfied.

Native configuration references:
- [Claude Code MCP](https://code.claude.com/docs/en/mcp)
- [Codex MCP](https://developers.openai.com/codex/mcp)
- [Cursor MCP](https://cursor.com/docs/mcp)

# Cross-agent suggestion experiment

Server flag `EDGE_AGENTS_SUGGESTION=1` enables the experiment; default is off.
Only successfully delivered root `use_skill` loads advance eligibility: three
loads across at least two distinct UTC dates. Supporting files, errors, pending
reviews, unavailable candidates, directory-only output and unknown clients do
not advance this experiment. No local-agent discovery runs in tool responses.

A salted SHA-256 assignment (`edge-agents-v1`) of install id gives a stable
50/50 suggestion/holdout split. Both arms persist eligibility. Only Codex in the
suggestion arm receives this exact line in its Edge tool response, once per
install, with state persisted before returning it:

> Edge works in your other coding agents too. To add it to Codex or Cursor, run edge agents.

`returned` means the server included the line in a tool result; it does not
claim the host displayed it to a person. Claude Code's channel is TBD:
`suggestionChannel` in `server/agents-suggestion.ts` is its hook point and
currently returns no delivery channel. Cursor does not receive the line.

Events are `eligible`, `returned`, `installer_run` and `second_agent_use`, with
install id, normalized agent family, experiment arm and internal-traffic flag.
The existing event ledger and PostHog allowlist carry them; no paths, detected
agents, credentials or task text are included. `installer_run` records an
approved, verified addition once per target agent, via the validated, rate-limited
`/agents_event` endpoint. Listing, cancellation and no-op runs do not send it.
`EDGE_TELEMETRY=0` prevents the installer signal. `second_agent_use` records the
first successful root load in a different supported agent from the first one
observed by the experiment, including holdout installs.

State is stored under the server state directory's `agents-suggestion/`, keyed
by the normal hashed install identity. Self-serve install deletion removes it.
Corrupt state or lock contention fails open without reissuing a suggestion.
A terminated writer may leave a `.lock` directory; remove it only after confirming
that no writer for that install is running. Flag-off retains prior once-only
state so reenabling cannot show the line again.