> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openreason.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code with OpenReason

> Run the Claude Code CLI you already use through OpenReason. Same command, same tools — your prompts bill to your org and show up in your audit log.

You already use Claude Code. `claude-or` runs the same CLI, with the same tools and subagents and skills and `CLAUDE.md`, against your OpenReason organization instead of your personal Anthropic account. What actually changes for you: prompts bill to your org's Anthropic key (not your card), every request lands in your org's audit log tagged with you, and any per-user budget your admin has set applies.

Setup takes about 30 seconds. Your existing `claude` login isn't touched — `claude-or` sits alongside it in a separate terminal tab, and you decide per-tab which one to use.

## Prerequisites

From your OpenReason organization (one-time, both in the admin dashboard):

* **An OpenReason API key issued to you** — [admin.openreason.app/dashboard/api-keys](https://admin.openreason.app/dashboard/api-keys). One key per user, so audit rows attribute back to you specifically. If you're not an admin, ask yours to issue one.
* **Your org's Anthropic key registered (BYOK).** An admin does this once at [admin.openreason.app/dashboard/byok](https://admin.openreason.app/dashboard/byok). The Anthropic key stays server-side in OpenReason; your laptop never sees it. The installer's preflight fails clearly if this step hasn't happened yet.

On your laptop:

* **macOS.** Linux and Windows are tracked but not yet shipped.
* **[Claude Code CLI](https://docs.claude.com/en/docs/claude-code)** — `brew install claude-code`.
* **`jq`** — `brew install jq`. Used by the wrapper's preflight and the statusline.

## Install

```bash theme={null}
curl -fsSL https://openreason.app/install/claude-or | bash
```

You'll be prompted for your OpenReason API key:

```text theme={null}
Paste your OpenReason API key (starts with sk-or_…), then press Enter:
> sk-or_live_proj_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

To skip the prompt (useful for CI or when following a personalized command from the dashboard), pass the key inline:

```bash theme={null}
OR_API_KEY=sk-or_live_proj_xxxxxxxx \
  curl -fsSL https://openreason.app/install/claude-or | bash
```

<Tip>
  The installer is idempotent. Re-running it overwrites the wrapper scripts with the latest version but preserves your key and settings — that's how you update.
</Tip>

## Verify

The installer prints a preflight summary before it exits:

```text theme={null}
· shell: zsh (/Users/you/.zshrc)
✓ wrote /Users/you/.claude/or-key (chmod 600)
✓ wrote /Users/you/.claude/or-settings.json
· downloaded claude-or
· downloaded claude-or-statusline.sh
✓ installed claude-or + claude-or-statusline.sh in /Users/you/.local/bin
✓ wrote claude-or block to /Users/you/.zshrc
· preflighting https://api.openreason.app/v1/models …
✓ key valid · BYOK provisioned · 3 Anthropic models · 25 total models

✓ claude-or installed.
```

Open a new terminal, then:

```bash theme={null}
claude-or
```

The Claude Code TUI opens. Look at the statusline at the bottom — it should read:

```text theme={null}
via OpenReason · BYOK · $0.0000
```

The cost accrues per turn. Every request writes an audit row at [admin.openreason.app/dashboard/audit](https://admin.openreason.app/dashboard/audit) — model, tokens in and out, upstream cost, price after your org's markup, and the user who ran it.

<Note>
  The header of the TUI may still show your normal Anthropic Console workspace name (e.g. "eDRV" or your Team plan name). That's a cached display label from your OAuth session — cosmetic only. Real auth is via the OpenReason key. Confirm inside the session with `/status`:

  ```text theme={null}
  Auth token:          apiKeyHelper
  API key:             apiKeyHelper
  Anthropic base URL:  https://api.openreason.app
  ```
</Note>

## How it works

The installer writes two files under `~/.claude/`:

```json ~/.claude/or-settings.json theme={null}
{
  "apiKeyHelper": "cat $HOME/.claude/or-key",
  "statusLine": {
    "type": "command",
    "command": "/Users/you/.local/bin/claude-or-statusline.sh"
  }
}
```

Claude Code's `apiKeyHelper` field wins over its stored OAuth token — so when `claude` is invoked with `--settings ~/.claude/or-settings.json` and `ANTHROPIC_BASE_URL=https://api.openreason.app` (both set by the wrapper), every request is authenticated with your OpenReason key and sent to OpenReason's router. The router looks up your BYOK Anthropic key in its server-side Vault, calls Anthropic on your behalf, and streams the response back. Your Anthropic key never leaves the Vault.

The plaintext `~/.claude/or-key` file (chmod 600) is the same trust model as your `~/.aws/credentials` or `~/.config/gh/hosts.yml` — readable only by your user.

## What runs through OpenReason

Every model call — chat turns, tool decisions, subagent spawns, streaming responses. Anything Claude Code sends to Anthropic goes through OpenReason first and is subject to your org's budgets, audit trail, and BYOK Vault.

Unchanged from a normal `claude` session (still local, still yours): WebFetch, WebSearch, Bash, Read, Write, Edit, custom subagents, custom skills, `CLAUDE.md` auto-discovery, auto-memory, user MCP servers (`railway`, `mcp-streaming`, and any others you've added to `~/.claude.json`).

## What won't work under `claude-or`

<Warning>
  **Claude subscription features are unavailable.** `claude-or` authenticates with an OpenReason API key, not with your Claude subscription's OAuth session. Anthropic gates several integrations on that OAuth identity — they check "is this a signed-in Claude Team/Pro user?" before they'll attach to a session. An API-key session can't satisfy that check, so those integrations don't load. This isn't a limitation of the wrapper — the same features are unavailable if you point plain `claude` at Anthropic's API directly with a raw `ANTHROPIC_API_KEY`.
</Warning>

**Specifically, the following will not load or respond in a `claude-or` session:**

* **Claude for Chrome** — the browser-control extension (tools prefixed `mcp__claude-in-chrome__*`). Chrome pairing lives in your Claude subscription's OAuth state; API-key sessions can't attach to it.
* **Slack** (`claude.ai/*` MCP) — Anthropic-hosted, OAuth-authenticated against your Claude account.
* **Gmail** (`claude.ai/*` MCP) — same reason.
* **Google Drive** (`claude.ai/*` MCP) — same reason.
* **Notion** (`claude.ai/*` MCP) — same reason.
* **Apollo.io, Mercury, QuickBooks, Kiwi.com** — every `claude.ai/*`-hosted MCP integration in Anthropic's catalog.

Inside a `claude-or` session, `/mcp` will show a shorter list — only your user-scope MCPs (from `~/.claude.json`). The Anthropic-hosted MCPs simply won't appear.

**Workarounds:**

* **Browser automation** — use the `dev-browser` skill (`/dev-browser` inside the session, or invoke it explicitly with `use dev-browser to open cnn.com`). It uses a sandboxed local browser with JavaScript execution, no OAuth required.
* **Anything else on that list** — run it in your normal `claude` session (mainline `claude` in another terminal tab). The two commands coexist; your OAuth session isn't affected by installing `claude-or`.

<Tip>
  Use `claude` for tasks that need Slack/Gmail/Drive/Chrome integrations. Use `claude-or` for tasks that need OpenReason governance, cost attribution, and audit. Same laptop, different terminal tabs, no conflict.
</Tip>

## Update

Re-run the install command. Same URL, same behavior — new wrapper scripts, preserved key and settings.

```bash theme={null}
curl -fsSL https://openreason.app/install/claude-or | bash
```

## Uninstall

```bash theme={null}
claude-or --uninstall
```

Confirms with `[y/N]`, then removes: the wrapper, the statusline renderer, `~/.claude/or-key`, `~/.claude/or-settings.json`, and the `claude-or` block from your shell rc. Open a new terminal to drop the alias from your shell.

If the wrapper itself is already gone, remove the rest by hand:

```bash Manual uninstall theme={null}
rm ~/.local/bin/claude-or ~/.local/bin/claude-or-statusline.sh
rm ~/.claude/or-key ~/.claude/or-settings.json
# Then edit ~/.zshrc (or ~/.bashrc / ~/.config/fish/config.fish) and remove
# everything between the "# BEGIN claude-or" and "# END claude-or" markers.
```

## Troubleshooting

<Accordion title="✗ jq is required" icon="triangle-exclamation">
  The wrapper's preflight and statusline both need `jq` to parse JSON. Install it:

  ```bash theme={null}
  brew install jq
  ```

  Then re-run the installer.
</Accordion>

<Accordion title="✗ Claude Code CLI not found on PATH" icon="triangle-exclamation">
  Install Claude Code first, then re-run the installer:

  ```bash theme={null}
  brew install claude-code
  ```
</Accordion>

<Accordion title="✗ OR router rejected the key (HTTP 401)" icon="triangle-exclamation">
  Your OpenReason key was rotated, revoked, or mistyped. Regenerate at [admin.openreason.app/dashboard/api-keys](https://admin.openreason.app/dashboard/api-keys), then update your key file:

  ```bash theme={null}
  printf 'sk-or_live_proj_NEW_KEY' > ~/.claude/or-key
  chmod 600 ~/.claude/or-key
  ```

  Or just re-run the installer.
</Accordion>

<Accordion title="✗ Anthropic BYOK not provisioned for this org" icon="triangle-exclamation">
  The preflight sees no `claude-*` models in `/v1/models`, which means your org has an OpenReason key but hasn't registered an Anthropic key. Add one at [admin.openreason.app/dashboard/byok](https://admin.openreason.app/dashboard/byok), then re-run the installer.
</Accordion>

<Accordion title="✗ Credit balance too low" icon="triangle-exclamation">
  This is Anthropic returning an upstream error — the Anthropic account tied to the BYOK key registered for your org has a depleted balance or has hit a spend cap. Sign in to [console.anthropic.com](https://console.anthropic.com), find the workspace that owns the key, and top up (Settings → Billing → Add funds) or raise the workspace spend limit.
</Accordion>

<Accordion title="`claude-or` command not found after install" icon="circle-info">
  Your shell rc file wasn't sourced yet. Either open a new terminal, or:

  ```bash theme={null}
  source ~/.zshrc    # or ~/.bashrc / ~/.config/fish/config.fish
  ```

  If you're on a shell other than zsh, bash, or fish, the installer defaulted to zsh and warned you — add the alias manually:

  ```bash theme={null}
  alias claude-or='$HOME/.local/bin/claude-or'
  ```
</Accordion>

<Accordion title="Statusline shows the wrong org name" icon="circle-info">
  The header of the TUI reads your cached Anthropic Console workspace, not "OpenReason". This is display-only — confirm real routing with `/status` inside the session. The bottom statusline (`via OpenReason · BYOK · $…`) is the source of truth.
</Accordion>

## Next

<CardGroup cols={2}>
  <Card title="Add your Anthropic key (BYOK)" icon="key" href="/quickstart/byok-anthropic">
    Register the Anthropic API key that OpenReason uses on your behalf, and set an optional workspace-level spend cap.
  </Card>

  <Card title="Invite a teammate" icon="user-plus" href="/guides/add-team-member">
    Share the setup with an engineer on your team so their Claude Code usage lands in the same audit trail and budget.
  </Card>
</CardGroup>