Connect a coding agent

Connecting a coding agent lets it implement your product from a published release rather than from chat history. This guide covers the setup that's the same for every agent, then the small extras each client needs. Before you start, you'll want an OriginAI account, a project with a published release (recommended for implement-from-spec), and Node.js so you can run npx originai.

The universal setup

These three steps apply to every coding agent.

1. Authorize once per machine

npx originai login
# stores your token in ~/.origin/settings.json — never commit it

2. Link the project in your app repository

cd your-app-repo
npx originai link --project <project-id>
# add --skill / --claude-code / --codex / --cursor / --all as needed

Linking writes:

.origin.json — the project_id, api_url, and release_hash. This is safe to commit.
Optional skill or instruction files, depending on the flags you pass.

3. Verify the setup

npx originai doctor
npx originai whoami

4. Pull the changes and implement

npx originai get-diff    # shows a unified diff plus content; does not move the pointer
# the agent implements the changes from the diff
npx originai sync        # advances release_hash once the code matches

Or simply ask the agent: "Read the OriginAI skill (or MCP tools) and implement the latest release."

Per-client extras

After the universal login and link, each client needs a little extra:

Client	Extra setup
Claude Code	Install the Origin plugin from the marketplace. MCP runs locally via `originai mcp` (uses your login).
Cursor	`link --cursor --skill`, then `originai mcp config --cursor`.
Codex	`link --codex --skill`; the agent uses the CLI via `AGENTS.md`.
Pi / Hermes / OpenCode	`link --skill` installs the Agent Skill plus the CLI.
skills.sh	Install the skill from the well-known endpoint, then still run login and link.
CI	Use an `ORIGIN_TOKEN` secret — see Access tokens.

For the full matrix, see MCP & agent install.

You've succeeded when…

The agent reads release files, rather than guessing from chat.
The release_hash in .origin.json only advances after real implementation (via sync).
After the first release, agent writes stage a change request for you to apply in Origin.
Day-to-day, humans don't have to manage export ORIGIN_TOKEN; login is enough.

Troubleshooting

Symptom	Cause and fix
A release read returns `404`	Nothing is published yet — publish in the UI, or use `--read-type workspace` for pre-release indexing only.
A write returns `suggested: true`	Expected after the first release. The agent should `describe-proposal` then `submit-proposal`; you apply the change request in Origin, then publish.
A write returns `403`	Unexpected — check token scope and project access, not the old “release lock”.
Auth errors	Re-run `npx originai login`, or set `ORIGIN_TOKEN` for CI.
MCP isn't authenticated	For the Claude plugin, run `originai login` and restart; a remote MCP host needs `ORIGIN_TOKEN`.
The agent tries to use `curl`	The skill forbids raw HTTP — use MCP tools or the CLI only.

Connect a coding agent

On this page