# Using ProductOS with Claude Code

> Two ways: the MCP server (workspace inside your editor) and GitHub-Action dispatch (run Claude Code remotely from a feature).

Source: https://productos.ca/documentation/guides/ai/claude-code (last reviewed 2026-09-22)

ProductOS treats Claude Code as a first-class surface. There are two integration paths, pick the one that matches where the work lives.

## Path 1: MCP server (in-editor)

You're in Claude Code in your terminal or editor, working on a feature, and you want Claude to load the full spec, walk the Golden Thread, and post status back as it works. Use the MCP server.

→ Full setup in [MCP server](https://productos.ca/documentation/api/v1/mcp).

In short:

1. Add the server with the Claude Code CLI: `claude mcp add --transport http --scope user productos https://productos.ca/api/mcp/mcp`.
2. Run `/mcp` inside Claude Code, pick **productos**, choose **Authenticate**, and approve the connection in the browser tab that opens. That is an OAuth sign-in against your ProductOS account, so no token is pasted anywhere and access follows your workspace role.
3. You'll see tools like `get_feature`, `get_golden_thread`, `search_features`, `execute_action`, `update_feature_status`, `report_progress`, and `attach_artifact` appear.

For scripts and CI, or a session dispatched from ProductOS (open a feature → **Send to Claude Code**, which provisions a session-bound token automatically), pass a token instead: add `--header "Authorization: Bearer pos_live_..."` to the command above, using a token from **Settings → API Tokens**.

When to use this:
- Loading a feature's full spec + linked context at the start of a coding session.
- Searching for parallel / duplicate work before creating new entities.
- Posting progress updates and attaching the PR you just opened.
- "Given this code change, which feature should I update?"

The server is built around the coding-session lifecycle, but it also reads every entity type (`search_entities`, `list_entities`, `get_entity`, `count_entities`) and writes through the same validated action catalog as the app (`execute_action`). For bulk imports, exports and anything scripted at volume, use the [REST API](https://productos.ca/documentation/api/v1/authentication).

## Path 2: GitHub-Action dispatch (out-of-editor)

You're inside ProductOS, looking at a feature's detail page. You want Claude Code to actually go off and *do the work*: open a PR, run tests, push a draft. Use the GitHub-Action dispatch.

→ Full setup in [Connecting GitHub](https://productos.ca/documentation/guides/integrations/github).

In short:

1. Install the ProductOS GitHub App on your repo (**Settings → Integrations → ProductOS GitHub App → Connect GitHub**).
2. Open **Send to Claude Code** on a feature and pick the repo. The dialog checks its setup and lists what a run needs, linking the page that fixes anything missing:
   - **Workflow.** **Install workflow** opens a PR adding `.github/workflows/productos-claude.yml`; merge it. **Install and merge** (owners and admins) opens and merges it in one go, unless branch protection wants a review or passing checks, in which case the PR stays open for you.
   - **`ANTHROPIC_API_KEY`.** A repository secret, or an organization secret whose repository access includes the repo. GitHub doesn't let organization secrets reach private repos on GitHub Free, so use a repository secret there. ProductOS does not ship your key into Actions: your key, your CI minutes.
   - **Actions policy.** If your organization only allows some actions (**Settings → Actions → General → Policies**), allow `anthropics/claude-code-action@*` and `oven-sh/setup-bun@*`. claude-code-action installs Bun through `oven-sh/setup-bun`, and the policy covers it too; without both, GitHub refuses to start the run.
   - **Anthropic's Claude GitHub App** installed on the repo, which claude-code-action signs in through.
   - **ProductOS GitHub App permissions.** Checking the secret needs **Secrets: Read-only** and checking the Actions policy needs **Administration: Read-only**; both are optional and read names and settings, never secret values. Without them those items say ProductOS can't check, with what to look at.
3. Fix what the checklist flags; the dialog won't dispatch while the workflow is missing, the secret is missing or the policy would refuse the run.
4. On a feature's detail page, click **Send to Claude Code**, pick the repo, keep or edit the branch (the feature's id and a few words of its title by default, such as `wrk-000123-sidebar-flyout`; a name git doesn't allow, such as one with spaces, is cleaned up), pick the model by version (**Default**, the latest **Fable**, **Opus**, **Sonnet** and **Haiku**, an earlier version, or a custom model id; the dialog shows the exact id it will run and remembers your last pick), optionally add a prompt override, and **Dispatch**. The session records the model, and **Retry** reuses it. A repo on workflow v7 or older ignores the model, so update the workflow from the dialog first.

### Working across several repos

When a change spans repos, say an API and the SDK that calls it, check each one in the dialog. The first one you check hosts the run: it needs the workflow (v10 or later) and the `ANTHROPIC_API_KEY` secret, and **Run here** moves the run to another checked repo. The others need only the ProductOS GitHub App. Claude works in all of them in the same run, on the same branch, and opens a pull request in each one it changes; the session lists every repo with its pull request.

If Claude finds it needs a repo you didn't check, it asks for it, with the reason, on the session. Click **Add** or **Decline** on the session in **Code → Sessions** (you are notified of the question), or add another connected repo to a running session yourself. Check **Let the run add other connected repos it needs without asking** before dispatching to skip the question. Git reaches those repos through tokens ProductOS issues to that run only, one repo at a time and for an hour; nothing new goes into the repo's secrets. Working across repos is being rolled out: if the dialog has a **Repository** dropdown rather than a list of repos to check, it isn't turned on for your workspace yet.

The dispatch payload is deliberately tiny: session id, feature id, branch, your MCP URL and a 24-hour session-scoped token. The runner's first move is `get_feature` over MCP, so it always works from the spec as it is when the run starts, not as it was when you clicked. It reads the repo's `CLAUDE.md` or `AGENTS.md` and follows its conventions for commits, PR titles and descriptions (with workflow v9; without any, the PR is titled after the feature), reports milestones with `report_progress`, and opens a PR from the branch. The PR description lists anything production needs beyond the merge, such as migrations or env vars, and what Claude could not verify. The PR webhook links that PR back to the session; the feature's **Sessions** tab shows the timeline and the diff. When the PR merges, a feature left at `in-progress` advances to `testing`.

A session reads **Queued** until GitHub starts the run, then **Running**. If GitHub refuses to start the run, usually because of the Actions policy, it sends ProductOS nothing; while the session is open in **Code → Sessions**, ProductOS looks its run up on GitHub every minute or so, and a refused run closes the session as **Failed** with the reason and the fix. If the run fails before Claude starts, for example because the secret is missing, the session closes as **Failed** with the reason. A session queued for more than two minutes without checking in shows a link to the run and a **Retry** button; Retry dispatches a new run with the same repo and prompt and closes the stuck one.

To talk to Claude, use the reply box on the session in **Code → Sessions**. A run still going reads your reply the next time it reports progress. When the run has finished, a reply starts a follow-up run (after you confirm) on the same branch and pull request with your reply as its instructions, so you can ask a question about the work or ask for changes without starting over. Replies don't go to GitHub: an `@claude` comment on the pull request doesn't start anything unless the repo has its own Claude workflow.

When to use this:
- The feature is well-specced and you want Claude Code to take the first pass.
- You want a draft PR you can review and iterate on, not a partial edit you have to clean up.
- Async / lights-out work, kick off before lunch, review on return.

## Which path for which task

| Task | Path |
| :--- | :--- |
| "Why was this feature scoped this way?" | MCP |
| "What does FEAT-000123's acceptance criteria look like?" | MCP |
| "File a feature for this Intercom feedback" | MCP |
| "Implement FEAT-000123, open a draft PR" | GitHub-Action |
| "Refactor the auth middleware per FEAT-000456 spec" | GitHub-Action |
| "What features touch the auth code?" | MCP (uses repo indexing) |
| "Post a progress note on FEAT-000123's session" | MCP |

Rule of thumb: MCP for **reading + low-stakes writes**; GitHub-Action for **anything that ends in a PR**.

## Caveats

- **Token capability is role-based, not per-endpoint.** A token runs at the workspace role it was issued with; if the issuer is later demoted below that role, the token is revoked. A `commenter`-role token cannot write, regardless of what scopes you might have specified. Issue tokens at the role the integration actually needs (`member` for writes). An OAuth sign-in from `/mcp` gets your own role automatically.
- **Writes can be switched off workspace-wide.** The *Allow AI to apply changes* toggle on **Settings → AI** blocks `execute_action` and the other MCP write tools for everyone when it's off; reads keep working.
- **GitHub-Action dispatch uses YOUR Anthropic key.** Not ProductOS's. Make sure `ANTHROPIC_API_KEY` is set on the repo. A typical Claude Code run is $0.50–$3, make sure your Anthropic billing isn't capped.
- **MCP tools have no separate quota, but each call is capped at 60 seconds.** Write tools go through the same validated core as the REST API. A session that calls `report_progress` at every checkpoint is fine; don't loop `search_features` on every keystroke. Read [Rate limits](https://productos.ca/documentation/api/v1/rate-limits) for the REST classes before any heavy workflow.

## Next

- [MCP server reference](https://productos.ca/documentation/api/v1/mcp): full tool list and config.
- [Connecting GitHub](https://productos.ca/documentation/guides/integrations/github): install + dispatch.
- [BYO Anthropic key](https://productos.ca/documentation/guides/ai/byo-anthropic-key): billing notes.