# Install Candor in Claude Code

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 Claude Code'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 Claude Code's usual interaction
model.

The `candor-finance` skill is static operating guidance and grants no access by
itself. The remote MCP server authorizes Claude Code 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. Claude Code may maintain records inside Candor
depending on the approved OAuth scopes; those workspace records are not
external financial actions.

Use the self-published Candor package as the default route and let Claude Code
run its supported installation or update commands. Do not send the user
through manual skill or MCP setup when that package route is available. Before
a fresh package install, an existing-package update, or the manual fallback,
tell the user that the applicable route will change the host by installing or
updating the static `candor-finance` skill and Candor's remote MCP
configuration. If manual setup will replace an existing package, also say that
the package will be disabled at cutover and re-enabled if the replacement
fails. Ask whether they want those host changes and wait for their explicit
answer before applying the applicable route. The request to read START and help
with setup is not itself approval for any of those changes. Inspect the
applicable commands before running them.

For a fresh installation:

```text
claude plugin marketplace add candorsystems/candor-finance
claude plugin install candor-finance@candor
```

For an existing installation, refresh the marketplace and update the package:

```text
claude plugin marketplace update candor
claude plugin update candor-finance@candor
```

The package supplies the `candor-finance` skill and remote MCP configuration.
Start a new Claude Code session after installation or update, complete Candor
OAuth in the browser, verify the skill and `candor_open` tool are present, and
call `candor_open`.

Claude Code is currently available through Pro, Max, Team, Enterprise, or an
Anthropic Console account with active billing; a Free Claude subscription by
itself is not a Claude Code account path. On Team/Enterprise, the user may need
an eligible seat and organization permission. If browser OAuth does not open
automatically on a remote or headless host, show the authorization URL to the
user and use Claude Code's documented remote-browser flow; never ask them to
paste Candor credentials or a token into chat.

Only if the user explicitly chooses the supported manual route, the marketplace
mechanism is unavailable, or its supported install or update fails, use the
manual fallback below.

For an existing Candor package, first run `claude plugin list`, then start a
fresh Claude Code session before checking whether its `candor-finance` skill
and `candor_open` tool still work. This is required after a failed update too:
the old session may still hold the pre-update package in memory. If the fresh
session works, keep using that package unless the user explicitly chose manual
setup.

The manual replacement has one staged activation sequence:

1. Clone or fast-forward
   https://github.com/candorsystems/candor-finance in a stable, user-approved
   directory outside `~/.claude/skills`. Verify that its
   `skills/candor-finance/SKILL.md` and linked files are present. This stages the
   skill without activating it.
2. Check `~/.claude/skills/candor-finance` and `claude mcp get candor`. Do not
   overwrite an unrelated skill or add a duplicate server. Record whether this
   fallback will create each path so a failed cutover removes only what it
   created.
3. If `candor-finance@candor` is installed, disable it at cutover with
   `claude plugin disable candor-finance@candor` even when its fresh-session
   verification failed. Record separately whether it was usable before
   cutover; only a previously working copy is eligible for rollback.
4. Create the supported personal-skill link
   `~/.claude/skills/candor-finance` pointing to the staged repository's
   `skills/candor-finance` directory. Claude Code officially supports personal
   skills at this location and follows a skill-directory symlink.
5. If no `candor` MCP server already exists, add it exactly once with
   `claude mcp add --transport http candor --scope user https://api.candor.money/mcp`.
   If one exists, verify that its transport, scope, and URL already match rather
   than adding it again.
6. Start a fresh Claude Code session so this manual skill and MCP configuration
   are the copies being tested. In that session, verify the skill and
   `candor_open` tool are present, then use `/mcp` or `claude mcp login candor`
   for browser OAuth rather than a pasted token and call `candor_open`.

Do not leave the packaged and manual copies enabled together. Disabling the
package is reversible and preserves it for recovery.

An `action_required` response with a `safe_url` or `recovery_url` is a working
integration with an account-state handoff, not a failed replacement. Show the
exact URL, pause for the user to complete the secure browser step, and continue
from the returned envelope.

OAuth cancellation, a browser timeout, or pending organization approval is a
user-gated authorization outcome, not proof that the manual host integration is
broken. Leave the correctly loaded manual route available, explain the exact
state, and guide an authorization retry or administrator approval.

Only if the fresh session is missing the manual skill or tool, or the exact
error proves that the personal-skill link or MCP configuration is invalid,
remove only the symlink or MCP entry created by this fallback. Only when a
pre-existing package was both working and actually disabled, run
`claude plugin enable candor-finance@candor`, start another fresh Claude Code
session, and verify the restored package. If no package existed or the disabled
package had already failed fresh-session verification, do not run the enable
command; report the automatic-route and manual-route failures with the partial
manual artifacts removed. Never leave a prior working package disabled without
a verified replacement, and never re-enable a known-broken package as rollback.

Current Claude Code references:

- https://code.claude.com/docs/en/plugin-marketplaces
- https://code.claude.com/docs/en/skills
- https://code.claude.com/docs/en/mcp
- https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan
- https://support.claude.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan