Coding Agents

Integrity coding-agent connections use browser OAuth. You do not create, copy, or save an Integrity API token. Your coding agent opens Integrity, you sign in and approve that installation once for all of your current workspaces in that environment, and the agent stores and refreshes its OAuth credentials. Each repository still names the exact workspace it uses.

Connect Codex

Integrity for Codex is distributed through the private IRSIKS marketplace, so you need access to the Irsik-Solutions/irsiks-codex-marketplace repository. Add the marketplace, then install the production plugin integrity@irsiks:

codex plugin marketplace add https://github.com/Irsik-Solutions/irsiks-codex-marketplace.git
codex plugin add integrity@irsiks

Start a new Codex task so the plugin and its integrity MCP server load, then authorize the installation as described below. When a new version is published, run codex plugin marketplace upgrade irsiks, install integrity@irsiks again, and start a new task.

Plugins and OAuth grants are local to each Codex installation. Repeat the install and authorization on each computer rather than copying another computer's plugin cache or credentials. A repository's committed .integrity/project.md carries its workspace mapping when you clone it.

Sign In And Authorize

Run:

codex mcp login integrity

Codex opens Integrity in your browser. Then:

1. Sign in to Integrity. If profile onboarding or two-factor authentication is required, complete it; Integrity returns you to the same authorization.
2. Confirm the displayed name and email before Integrity links the request to an account. If the browser reused the wrong session, select Switch account, sign in as the intended user, and return to the same request.
3. Select Continue. Integrity now links the request to the confirmed account and records future connection actions as that user.
4. Review the requesting client, redirect URI, scopes, and All current workspaces. There is no workspace picker: current membership is checked whenever the client uses a workspace.
5. Select Authorize. This authorizes only the named environment. Production integrity and development integrity-dev keep separate credentials.

The Codex connection receives only the Integrity MCP tools listed by the plugin. It does not receive general access to Integrity, SQL, files, terminals, Git, or workspace administration.

Connect Claude Code

If your organization already provides an Integrity plugin, it may declare the integrity MCP server for you. In that case, run only claude mcp login integrity and skip the add command below to avoid a duplicate connection. For a direct MCP connection, run:

claude mcp add --transport http integrity --scope user https://integrity.irsiks.com/api/integrity/mcp
claude mcp login integrity

Connect Devin CLI

Devin CLI uses a direct MCP connection. Run these commands on each computer where you use it:

devin mcp add -s user integrity https://integrity.irsiks.com/api/integrity/mcp
devin mcp login integrity

Connect Other Coding Agents

These clients use the same production MCP endpoint. Run the setup command on the computer using that client, then authenticate as shown.

GitHub Copilot CLI

copilot mcp add --transport http integrity https://integrity.irsiks.com/api/integrity/mcp

Start copilot, then run /mcp auth integrity inside its interactive session. This applies to Copilot CLI; the Copilot cloud agent has different remote MCP authentication support.

Gemini CLI

gemini mcp add --scope user --transport http integrity https://integrity.irsiks.com/api/integrity/mcp

Start gemini, then run /mcp auth integrity inside its interactive session.

OpenCode

opencode mcp add integrity --global --url https://integrity.irsiks.com/api/integrity/mcp
opencode mcp auth integrity

The --global option makes the connection available in every OpenCode project. Omit it to configure only the current project.

Each authentication opens Integrity's browser authorization. Confirm your account, review the requesting client, and select Authorize. Return to Settings → Coding agents to see that installation. Each client maintains its own OAuth connection, even when several use the same Integrity account. A direct MCP connection provides Integrity tools; it does not install workflow skills or project rules in that client.

Onboard A Repository

In the selected repository, ask Codex:

Set up Integrity for this project

You do not need to provide the file paths or repeat the safety instructions. When the canonical files are missing, Codex explains that the project does not yet have Integrity's repository-local project context and asks whether you want to begin. After you confirm, Codex verifies the authorized workspace, inspects the repository without changing it, lists the accessible active Teams in that workspace, and asks which Team should be the repository default. It then creates or updates these canonical local files:

• .integrity/project.md;
• .agents/rules/index.yaml and the rule files under .agents/rules/.

Codex leaves the files uncommitted and shows you the diff. Correct or accept the content in the same conversation. Codex validates the files and commits them only after you explicitly confirm the diff and request a commit. Integrity does not store a second Project Draft and there is no separate Coding agents approval screen.

One account-scoped connection follows your current workspace memberships. You do not repeat login when you join another workspace, and losing membership blocks that workspace on the next request. The identity check may show a display-safe list, but the repository's workspace_slug is always checked directly and is never authorized merely because it appeared in that list.

During consent, give the connection a name that identifies that installation, such as Office desktop or Home laptop. The name is personal display metadata; the requesting client remains visible separately, and changing the name never changes authorization. Each separately registered machine has its own connection and can use a different Integrity account.

When an installation has no existing connection, choose Create new during consent. Choose Reconnect only when you intentionally want to use one of your own existing connection groups; select the displayed target and review its name before authorizing. Reconnect does not silently move another client, lease, receipt, or provider grant. After cancellation, expiry, or a stale target, start a fresh login and review the current choices. An uncertain transport result can be retried with the same unchanged choice while the authorization remains valid.

Older connections remain visibly labeled Legacy workspace access until you reauthorize them with codex mcp login integrity. Reauthorization upgrades the client without copying credentials or changing another environment. User Settings > Coding agents then shows one All current workspaces row for the client.

The Foundation stores the workspace as a display-safe value such as workspace_slug: irsiks and the Team choice as default_team_ref: team:systems-safety. Two repositories may use the same coding-agent client while selecting different workspaces and Teams. An older Foundation without workspace_slug remains valid when the client has one authorized workspace. With several, lifecycle work pauses and proposes the exact additive frontmatter change for review. Team options are always resolved inside the selected workspace.

These defaults have different owners. The workspace connection belongs to the coding-agent client, the repository default belongs to that repository's Foundation file, and any personal default Team remains an account preference in Integrity. Connecting the same account from another computer does not copy a repository Foundation: clone the repository so its committed Foundation travels with it, then authorize that computer's client and review the resolved workspace and Team before continuing.

Administer Teams With A Coding Agent

An authorized coding agent can read an accessible Team's configuration and can propose Team profile, access, Issue-workflow, Triage, and recurring-Issue changes through the same server-authoritative permissions as the Integrity UI. It uses immutable lowercase, hyphen-separated team:<slug> references, previews high-impact effects, and asks for a short-lived confirmation before applying privacy cascades, hierarchy cleanup, lifecycle changes, destructive workflow edits, or recurrence actions. The server checks access and the preview fingerprint again when the action is applied.

The agent cannot permanently delete a Team, silently change the workspace or personal default Team, reveal private-Team details to an unauthorized caller, or write arbitrary settings JSON. Successful and failed applications return a typed receipt; applicable changes also appear in Team Logs and refresh the same Team surfaces as UI changes. If permission or Team access changes while a request is open, refresh the Team configuration and prepare the action again. Direct access to a related Issue does not grant Team-settings access.

For an existing repository, both files may already exist while concern discovery is still incomplete. If the Concern Registry is empty, Codex inspects the repository rules read-only and proposes a small set of cross-cutting concerns. Detailed instructions remain in their existing files and are linked from the registry; Codex does not replace them. Review the proposed concern diff through the same local confirmation and commit boundary.

Synchronize A Project Spec And Plan

After onboarding is approved, /spec and optional /plan can synchronize one repository Project packet with Integrity. The repository stays the working copy. spec.md and build-notes.md are required; plan.md and tasks.md appear only when they help execution or handoff. Integrity does not rewrite your files.

/spec previews the stable repository key, exact Project title, a concise Project description, and the ordered primary/additional Team assignments before resolving or creating the Project. The description summarizes the approved outcome rather than copying the full specification. An older Project with no description can be filled during the approved retry, but Codex stops instead of overwriting different existing text. It can link the Project to one confirmed Initiative and also stops when identity is ambiguous, the object is restricted or deleted, the packet changed elsewhere, or the request would reparent the Project or change its owner, priority, dates, or scope.

The repository default is a suggestion for new objects, not a lock. You may confirm another primary Team or add Teams in the preview. New Initiatives normally use the repository default; Codex asks about another Team only when the request explicitly names one, an existing Initiative already supplies that context, or the scope is explicitly cross-Team. Existing Integrity assignments remain authoritative. If a Team was archived, became inaccessible, or changed elsewhere, Codex stops and asks you to refresh or select a replacement rather than silently falling back.

/plan is useful when dependencies, trade-offs, risk, or parallel work need a durable design. It can synchronize stable Project Phases when the plan actually uses them. Small Projects can proceed directly from an approved spec to Build, and no Phase creates a synthetic Issue.

Continue Through Build And Closure

The release candidate can continue the same Project through /build and /review to its merge without moving repository evidence out of Git. There is no separate closing command: the merge completes the Project.

• /build completes the approved scope unless you named a smaller Phase, path, or stopping point. It verifies affected behavior, removes unnecessary complexity as part of implementation, and integrates at the agreed delivery boundary. When the task branch exists the Project moves to In Progress and shows the agent as its active work.
• /review independently checks the exact implementation commit. The Project moves to In Review when the reviewer is requested. Blocking findings return named remedies to Build and stop closure.
• When the review approves, the agent asks you to try the result if the repository's policy calls for your final check. Your reply is the last thing it needs: when the repository allows merging without asking, the agent records your result and merges in the same turn. The merge validates the reviewed candidate, records the build, review and done checkpoints, marks the Project Completed while leaving its product lifecycle active, posts the closing health update, and archives or prunes according to the repository's policy. When one of those steps fails, the agent fixes the cause and runs the closing step again; it asks you only when a fix needs your decision.
• When you merge the pull request yourself, for example on GitHub, the next agent session on the same computer completes the Project the same way and tells you in one line. It leaves the Project alone, and says why, when the work started again after the merge or the merge does not contain the reviewed work.

Repeating the same request does not duplicate checkpoints, Activity, or updates. Restricted or unavailable Projects, stale evidence, conflicting retries, and missing capabilities stop without changing Integrity or the local packet. Linear remains read-only historical compatibility; lifecycle work never replays the completed import.

Manage Daily Work

The development MCP can read and safely change ordinary work in its authorized workspace. It can create or edit Initiatives, Projects, and Issues; create or edit Initiative and Project health updates; and read up to 24 recent comments or create and edit comments on an Initiative, Project, or Issue.

Routine create and edit commands apply only after you explicitly ask for them. Integrity checks your current permissions and the exact version you read, so a stale item stops with a refresh-and-retry message. Health-update and comment deletion is recoverable and never applies directly: Codex first shows an exact, short-lived preview, then applies it only after you confirm. Each confirmation is bound to your account, connection, workspace, target state, and one use.

The coding agent does not receive raw database identifiers or hidden content. Restricted and unavailable objects stay generic or absent, and all successful changes use the same Activity, history, notification, unread, and live-update behavior as the Integrity interface. Bulk and permanent deletion remain unavailable.

For the complete supported-action, confirmation, retry, and troubleshooting guide, see Coding Workflow.

Review Or Revoke A Connection

Open either location:

• your avatar > Settings > Coding agents;
• Workspace Settings > Personal > Coding agents.

An account-scoped client appears once under its connection name with All current workspaces. A legacy row appears under the same parent connection name as Legacy workspace access and names the exact workspace it can use. Each row shows the requesting client, OAuth authentication, authorization date, and last use. Use the pencil action to rename an installation; provider identity and access do not change.

To disconnect an account-scoped agent, select the trash action and confirm Revoke connection. Integrity blocks the whole client connection before provider cleanup. Legacy rows still revoke only their exact workspace grant; removing the final legacy grant blocks that parent. If provider cleanup is temporarily unavailable, authorization asks you to retry while local access remains blocked; the retry safely handles a provider grant that was already removed.

Renaming changes the selected connection group's display name. Revoking it disconnects every client in that group; other independent groups remain active. Existing merged groups keep their current authority and history; they are not automatically split. Reconnect a new registration deliberately from consent. Recovery never moves an old lease or receipt merely because callback details look similar.

OAuth credentials belong to the coding-agent installation that completed the authorization. Do not assume a connection is synchronized between computers; authorize each separately registered client and revoke each connection individually.

Troubleshooting

• If no browser opens, run codex mcp login integrity again from PowerShell.
• If Integrity says a previous approval was cleared, return to Codex and start login once more. This reopens the account-access review for a provider grant that had already been approved; it does not grant or broaden access silently.
• If the request is invalid or expired, or it was already linked to another account in a previous browser step, return to Codex and restart login.
• If the workspace is missing or denied, confirm your current Integrity workspace membership and the repository's .integrity/project.md workspace_slug.
• If Codex keeps using an older version, run codex plugin marketplace upgrade irsiks, install integrity@irsiks again, then start a new task.
• If Team selection stops, confirm the Team is active and that you can access it in the authorized workspace, then choose it again from the returned options.
• Do not add INTEGRITY_MCP_CONNECTION_TOKEN; the OAuth beta does not use it.