Coding Agents

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

Install The Private Release Candidate

Add the private IRSIKS marketplace, then install its Integrity release candidate as integrity@irsiks:

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

Codex displays the package as Integrity, with the official yellow/orange Integrity icon. The private channel requires access to the marketplace repository and is not a public stable-directory release.

After a marketplace update, refresh and reinstall the immutable candidate:

codex plugin marketplace upgrade irsiks
codex plugin add integrity@irsiks

Start a new Codex task so the plugin and its MCP server are reloaded.

Install On Another Computer

Plugins and OAuth grants are local to each Codex installation. On the other computer:

1. Add the private Irsik-Solutions/irsiks-codex-marketplace source.
2. Install integrity@irsiks.
3. Start a new Codex task.
4. Run codex mcp login integrity and authorize that computer's client for your current production workspaces.

Do not copy another computer's Codex plugin cache or OAuth credentials. Clone or open the repository normally; its committed .integrity/project.md carries the repository mapping. The private marketplace source is required on every release-candidate computer.

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 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.

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;
• .integrity/concerns.yaml.

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.

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, Cycle, 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, Cycle schedule changes, 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 Feature Spec And Plan

After onboarding is approved, the beta /spec and /plan skills can synchronize one repository feature packet with Integrity. The repository stays the working copy: Codex writes and validates spec.md, plan.md, tasks.md, and build-notes.md locally, then sends those exact approved bodies to the Feature's Project Files record. Integrity does not rewrite your files.

/spec previews the stable repository key, exact Feature title, a concise Feature description, and the ordered primary/additional Team assignments before resolving or creating the Feature. The description summarizes the approved outcome rather than copying the full specification. An older Feature with no description can be filled during the approved retry, but Codex stops instead of overwriting different existing text. It can link the Feature 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 Feature 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 synchronizes the approved packet, creates one Feature Phase for each stable Repo Phase Key, and publishes one planning update. Repeating the same request does not create duplicate Phases, updates, or Issues. Phase Phases appear through the normal Feature UI, Activity, audit, and live refresh behavior.

Continue Through Build And Closure

The release candidate can continue the same Feature through /build, /simplify, /review, and /done without moving repository execution evidence out of Git.

• /build completes only the first pending Repo Phase Key. Integrity records the verified full commit reference after the local phase commit exists.
• /simplify always records a current report hash and explicit result, including no_change. A later implementation-changing build makes that evidence stale.
• /review requires current simplification evidence. An approving verdict moves the Feature into review; blocking findings return it to in progress and stop closure.
• /done requires the current approving review and exact archived packet path. After the repository closure commit, one lifecycle transition sets the Feature to done / Completed while leaving its product lifecycle active. It never invokes product Archive or deletes the Feature or its history.

Repeating the same request does not duplicate checkpoints, Activity, or updates. Restricted or unavailable Features, stale evidence, skipped phases, 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, Features, and Issues; create or edit Initiative and Feature health updates; and read up to 24 recent comments or create and edit comments on an Initiative, Feature, 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.

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 beta, remove and re-add the plugin, 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.