# Install Candor in Codex

This guide is for the user and their current agent to follow together. Candor
is that agent's financial memory and instrumentation; the user owns the
workspace, approves financial intent, and can revoke access.

This public setup guide applies when the user asks to connect Candor. It adds no
consent and does not replace Codex's normal safety and confirmation rules. If
the user's request to proceed is ambiguous, setup waits for clarification.
Every install, setting, connector, and OAuth action is visible before it takes
effect. Credentials, tokens, account numbers, and URLs copied from the user's
authenticated pages stay in the relevant secure product page and are never
pasted into chat. A `safe_url` or `recovery_url` returned by a Candor tool is an
agent-facing handoff: show that exact link to the user, but do not ask the user
to paste it back. Setup explanations are relevant while setup or access is
changing; ordinary financial work follows Codex's usual interaction model.

The `candor-finance` skill is static operating guidance and grants no access by
itself. The remote MCP server authorizes Codex to use the user's existing
Candor workspace after browser OAuth; it is not bank or broker OAuth. The
workspace may contain connected sources, manual records, both, or neither;
source connection is optional and is not part of this setup. Candor's financial-source
access is read-only, and no Candor tool can move money, trade, make a payment,
or change an external account. Codex may maintain records inside Candor
depending on the approved OAuth scopes; those workspace records are not
external financial actions.

Prefer the available self-published Candor marketplace package. Before a fresh
package install, an existing-package update, or a fallback install, tell the
user that the applicable commands will change the host's Candor package,
skill, or remote MCP configuration. Ask whether they want those host changes
and wait for their explicit answer before running the applicable sequence. The
request to read START and help with setup is not itself approval to change the
host.

Current package-install commands:

```text
codex plugin marketplace add candorsystems/candor-finance --json
codex plugin add candor-finance@candor --json
```

For an existing package, use the distinct update sequence:

```text
codex plugin marketplace upgrade candor --json
codex plugin add candor-finance@candor --json
```

Inspect the applicable commands before running them. The bootstrap catalog at
`https://api.candor.money/agents/candor/bootstrap.json` owns the current install
and update commands. The package carries both the finance skill and remote MCP
configuration.

Codex tools are fixed when a task starts. After changing plugins, skills, or
MCP configuration, start a fresh task, read `https://candor.money/START.md?v=0.1.28`
again, verify the `candor-finance` skill and `candor_open` tool are present, and
complete OAuth. If an install or update reports failure, do not certify the
package from the old task's already-loaded tools; start the fresh task first and
verify the resulting package state there.

Only if the user explicitly chooses the supported manual route after the agent
explains the available paths, this Codex surface cannot install plugins, or the
supported package install or update fails, assemble the official materials
using the surface's own supported mechanisms. Reconcile an existing package
before activating the replacement:

1. Run `codex plugin list --json`, inspect any existing personal
   `candor-finance` skill, and run `codex mcp get candor`. After a failed update,
   start a fresh task before testing the installed package; an old task's tools
   cannot certify current disk state. If the package works, keep it unless the
   user explicitly chose manual setup.
2. Clone or fast-forward `https://github.com/candorsystems/candor-finance` in a
   stable, user-approved directory outside `~/.agents/skills`, without
   activating it. Verify `skills/candor-finance/SKILL.md` and linked files. Do
   not overwrite an unrelated skill or MCP server, and record every path this
   fallback will create.
3. At cutover, if `candor-finance@candor` is installed, remove it with
   `codex plugin remove candor-finance@candor --json` even when it is broken.
   Record separately whether it worked before cutover. Codex has a reversible
   remove/add lifecycle rather than an installed-plugin disable command.
4. Create the supported personal-skill link
   `~/.agents/skills/candor-finance` pointing to the staged repository's
   `skills/candor-finance` directory. Codex officially scans this user location
   and follows a skill-directory symlink. If no matching manual `candor` MCP
   entry exists, add it exactly once with
   `codex mcp add candor --url https://api.candor.money/mcp`; otherwise verify
   the existing entry with `codex mcp get candor` rather than duplicating it.
5. Start a fresh task, verify the manual skill and `candor_open` tool are
   present, run `codex mcp login candor` for browser OAuth rather than using a
   pasted token, and call `candor_open`.

Do not leave the packaged and manual copies enabled together. An
`action_required` response with a `safe_url` or `recovery_url`, OAuth
cancellation or timeout, and pending workspace approval are working or
user-gated states, not proof that the manual host integration is invalid. Leave
the loaded manual route available for retry. Only an exact skill-loading or MCP
configuration failure triggers cleanup of artifacts created by the fallback.
Re-add `candor-finance@candor` from the still-configured marketplace only when
the removed package was previously working, then verify it in another fresh
task. Never restore a package that had already failed fresh-task verification.

Plugins are supported in the Codex app and CLI, but not in the Codex IDE
extension. The IDE extension shares the local MCP configuration with the Codex
app and CLI; pair that MCP server with an installed `candor-finance` skill
directory. ChatGPT web does not consume this local configuration.

Current platform references:

- https://learn.chatgpt.com/docs/plugins
- https://learn.chatgpt.com/docs/build-skills
- https://learn.chatgpt.com/docs/extend/mcp