Introducing a new way to review your PRs.

Read the announcement

pbakaus / impeccable

The design vocabulary for your coding agent. Steer with polish and bolder, review with critique and audit, catch AI slop before it ships.

View on GitHub

32 documents · Updated Nov 20, 2026

docs / agent-protocol-services

Agent protocol services

Agent protocol services form the native bridge between coding-agent clients and Impeccable. They expose managed agent configuration through a remote service and add local capabilities for asset transfer, browser use, sign-in recovery, and agent presence. The bridge keeps agent processes on a line-based MCP protocol while protecting local files, credentials, and browser access.

MCP client boundary

Stdio MCP session

The MCP session is the client-facing entry point for an agent. Each agent starts one local impeccable mcp process over standard input and output. The process forwards service requests while keeping protocol frames on stdout and diagnostics on stderr.

The session presents one stable tool boundary even when a capability is local. It forwards normal requests to the account service, replaces the service asset tool with a local-file form, and adds browser tools only when the local browser relay is available.

The main request path is shown below.

flowchart LR
    Agent[External coding agent] --> MCP[Local MCP session]
    MCP --> Local[Local tools]
    MCP --> Account[Account service MCP]
    Local --> Reply[Tool result]
    Account --> Reply
    Reply --> Agent

References: crates/…/lib.rs• L1-18 crates/…/lib.rs• L63-75 crates/…/lib.rs• L98-185

Service requests

The account service remains the source for remote agent operations. The local session uses the CLI's stored sign-in and sends the MCP request to the account service without asking the agent to manage a token. This keeps service access consistent across agents on the same machine.

When a call needs authentication, the session can hold the call while the person signs in through the browser. It retries the call once after a successful sign-in. On a headless or SSH session it returns a direct instruction to run impeccable login instead.

Only one sign-in runs on a machine at a time. A second agent waits for the first sign-in result rather than opening another authorization flow.

References: crates/…/lib.rs• L28-60 crates/…/lib.rs• L321-359 crates/…/lib.rs• L389-455 crates/…/lib.rs• L486-525

Local capability services

Asset transfer

The asset tool lets an agent give an artifact a local file without sending the file bytes through the model. The session reads a supported regular file, checks its size and type, hashes its bytes, and asks the account service to reserve the matching content key.

If the workspace already has that content, the agent receives the key at once. Otherwise the service returns a short-lived upload address and the local session sends the bytes directly to it. The agent receives only the content key.

This flow separates file selection from remote storage and makes repeated uploads idempotent by content digest.

References: crates/…/asset.rs• L1-11 crates/…/asset.rs• L33-43 crates/…/asset.rs• L53-83 crates/…/lib.rs• L218-259 crates/…/lib.rs• L376-387

Browser control

The browser service lets an agent drive the person's signed-in Chrome through the Impeccable extension. It is local: the extension chooses which sites the person allows, and the remote service never reaches the browser relay.

Chrome starts a native-messaging host that accepts only approved Impeccable extension origins. The host relays framed JSON through a user-only Unix socket. One agent owns the browser session at a time; other agents receive a busy result until that session ends.

The browser tools cover page navigation, interaction, page inspection, and session end. A browser session can return an accessibility tree, images, styles, or other page views so an agent can inspect the result of its actions.

References: crates/…/browser.rs• L1-11 crates/…/browser.rs• L18-31 crates/…/browser.rs• L74-92 crates/…/browser.rs• L200-239 crates/…/lib.rs• L103-185

Browser host registration

Browser registration connects Chrome to the local relay. Installation writes one stable launcher and a native-messaging manifest for each supported Chromium browser profile that is present on the machine.

The launcher selects the newest verified local engine at run time. This lets engine updates take effect without changing each browser manifest. Sandboxed browser packages are reported when they cannot start the host outside their sandbox.

Registration is limited to macOS and Linux. It does not register a host until a verified engine is available, and it leaves an existing host with a different path unchanged.

References: crates/…/host_setup.rs• L1-7 crates/…/host_setup.rs• L16-45 crates/…/host_setup.rs• L121-145 crates/…/host_setup.rs• L138-193

Agent presence

The presence service gives the local CLI a view of active coding-agent sessions. A connected MCP session writes a short-lived record when it initializes and removes the record when it ends. The record links the session to its harness, process start time, working folder, and repository label.

The reader checks both process identity and process start time. It removes records from crashed sessions and scans for harness processes that do not use the MCP entry point. Those processes appear as seen but not connected, so the view distinguishes an active protocol session from an agent that is only visible in the process list.

The from value supplied by a needs-you request becomes the session's display name when present. Names are cleaned before they are stored or shown to the user.

References: crates/…/presence.rs• L1-7 crates/…/presence.rs• L106-175 crates/…/presence.rs• L193-253 crates/…/lib.rs• L108-150

Managed agent resources

Target files

Targets are derived from the request rather than supplied as arbitrary paths. Hooks select the harness settings files. Instructions select the harness rule file. Codex approval changes select its existing config.toml.

HarnessHook targetsInstruction targetApproval target
Claude Codesettings.jsonCLAUDE.mdNot supported
Codexhooks.json and config.tomlAGENTS.mdExisting server table in config.toml

This fixed target model limits the service to known agent integration points and gives status and undo a stable view of what the request can affect.

References: crates/…/targets.rs• L5-23 crates/…/cli.rs• L81-114

Resource records

A resource is one independently tracked part of an installation. Examples include a hook entry, an instruction block, the Codex hooks setting, a Codex MCP approval, or an MCP server. Records keep the last value written, the prior value when known, and the installations that claim the resource.

Reapply updates the last written value while keeping the original baseline from the first install. This lets status check the current desired part and lets undo restore the correct earlier value after a staged change.

This model allows status to check the managed part instead of treating every unrelated edit in the same settings file as drift. It also lets undo preserve user content and release shared resources in the correct order.

References: crates/…/lib.rs• L213-260 crates/…/resources.rs• L252-424 crates/…/tests.rs• L1234-1247

Installation lifecycle

JSON protocol

The service accepts one JSON specification for one owner, harness, and account root. The command boundary validates that request, selects an operation, and returns a versioned JSON result or a structured error. The supported operations are capabilities, list, plan, apply, undo, status, and recover.

The protocol keeps the client independent from the details of either coding-agent harness. A client can inspect the supported scope first, preview changes without writing, apply or remove an installation, and inspect drift later.

References: crates/…/cli.rs• L4-66 crates/…/cli.rs• L68-121 crates/…/lib.rs• L18-54

In-process access

The service also exposes the same validated operations to native callers that already build a Spec in code. These callers can run a plan, apply, status, or undo operation without crossing the command-line boundary. They can also list the installations owned by one owner and recover an interrupted installation.

This access path reads committed and pending state from the service journal. It therefore lets a caller undo or recover what was installed earlier instead of reconstructing that state from the current environment.

References: crates/…/lib.rs• L504-510 crates/…/lib.rs• L512-561 crates/…/lib.rs• L564-568

Request scope

Each request names an owner and a harness. The harness is either Claude Code or Codex. The account root is an absolute path that identifies the user installation to change. Hooks, instructions, MCP servers, and Codex approval modes are optional parts of the same desired state.

The service stores its private state outside the account root. This lets several owners or account roots share a physical resource while keeping each installation claim separate.

References: crates/…/lib.rs• L39-59 crates/…/lib.rs• L105-114 crates/…/cli.rs• L123-146

Change planning

Planning compares the requested state with the current files and harness state. It reports whether each target will be created, updated, or left unchanged. It also reports MCP server changes and whether an existing JSON file would be reformatted. Planning does not write the target or the journal.

References: crates/…/targets.rs• L25-87 crates/…/tests.rs• L667-686

Change application

Application first checks for changes made outside the service. It also refuses to replace an instruction block that a person edited. It then renders the requested content, writes the files, updates MCP settings through the selected harness, and records the result. The journal is the source for later status checks and undo operations.

On a reapply, the service keeps the original baseline when only its own earlier write changed the resource. An outside edit changes the cleanup path to a surgical update, so undo does not restore over the person’s change.

The main lifecycle is shown below.

flowchart LR
    Client[Agent client] --> Request[JSON specification]
    Request --> Validate[Validate scope]
    Validate --> Plan[Plan targets and resources]
    Plan --> Apply[Apply file and MCP changes]
    Apply --> Journal[Record claims and written state]
    Journal --> Result[Versioned JSON result]
    Apply --> Recover[Pending transaction]
    Recover --> Result

References: crates/…/resources.rs• L3-57 crates/…/resources.rs• L58-250 crates/…/render.rs• L105-132 crates/…/tests.rs• L1356-1373 crates/…/tests.rs• L1417-1457

Change removal

Undo removes only content that the installation owns. It restores original bytes when the service still controls the whole file. When a person or another installation changed the resource, it removes only the owned part when that is safe. Otherwise it reports a conflict and leaves the changed content in place.

Undo uses the journaled installation state rather than only the caller’s current request. If the journal is missing while the installation’s marker or exact hook remains on disk, the service reports the missing state instead of claiming that removal succeeded.

References: crates/…/resources.rs• L577-688 crates/…/render.rs• L77-103 crates/…/tests.rs• L1375-1388 crates/…/cli.rs• L148-168

Harness integration

Configuration rendering

Rendering adds the requested agent behavior to the harness format while preserving unrelated content. JSON settings reject invalid or duplicate-key input. Codex TOML keeps existing keys, comments, and line endings while changing only the features or approval data that the request owns.

Instruction text uses an owner marker in CLAUDE.md or AGENTS.md. The marker gives the service a clear boundary for later updates and removal. Ambiguous markers or edits inside the owned block stop replacement or removal rather than risk deleting user text.

Codex approval changes apply only to an existing standard MCP server table. The service changes the approval value or removes the line later without creating or rewriting a different table form.

References: crates/…/render.rs• L8-75 crates/…/render.rs• L105-161 crates/…/render.rs• L544-645 crates/…/render.rs• L737-802 crates/…/tests.rs• L131-216 crates/…/tests.rs• L952-1019

Hook behavior

Hooks are expressed once in the request and mapped to the shape expected by the selected harness. Claude Code stores them in user settings. Codex stores them in its hook file and enables the Codex hook feature when that feature is not already set.

The service does not take ownership of an explicit Codex choice to disable hooks. It asks for that setting to be enabled first, so a request cannot silently change the user’s safety choice.

Undo can remove an unchanged managed hook while keeping a personal hook in the same event. If a person changes the managed hook’s options, the service leaves that entry in place and reports the specific hook as a conflict.

References: crates/…/lib.rs• L60-103 crates/…/render.rs• L34-63 crates/…/render.rs• L163-193 crates/…/render.rs• L268-339 crates/…/tests.rs• L1392-1414 crates/…/tests.rs• L1501-1532

MCP integration

MCP server state

MCP, or Model Context Protocol, servers are named external tools that a coding-agent harness can start or use. The service manages these servers through the Claude Code or Codex command-line interface. It reads back the installed configuration after an add and compares that observation with the requested value.

The service treats an existing name as a real resource. A foreign configuration causes a collision. Identical claims can be shared, and the server is removed only after the last claim is released.

References: crates/…/mcp.rs• L3-49 crates/…/mcp.rs• L51-117 crates/…/mcp.rs• L222-328 crates/…/resources.rs• L10-19 crates/…/resources.rs• L397-424

Codex approvals

Codex approval modes control how a configured MCP server is allowed to run. The service changes only the approval line in an existing standard server table. It records the prior mode so undo can restore it without changing other Codex settings.

An absent server or an unsupported table form is rejected. A person’s later change to the approval mode is treated as drift, not as permission for the service to set the old mode again. Status checks each approval against its own server, so a matching mode on another server cannot hide drift.

References: crates/…/render.rs• L556-645 crates/…/render.rs• L647-666 crates/…/resources.rs• L21-42 crates/…/targets.rs• L158-168 crates/…/tests.rs• L1202-1247

Safe state changes

File ownership

File writes protect the user’s account and the service’s ownership boundary. The service accepts regular files and user-owned target locations, follows an existing symlink without replacing the link, and refuses unsafe or ambiguous targets.

Before and after a write or delete, the service checks that the target still has the expected identity and content. It writes through a temporary file and verifies the final result. A concurrent change therefore becomes an explicit conflict instead of an overwrite.

References: crates/…/fs_writer.rs• L17-135 crates/…/fs_writer.rs• L153-248 crates/…/tests.rs• L217-240

Shared claims

Several installations may claim the same physical file or MCP server. The service permits this only when the desired values agree. An undo keeps a shared resource for remaining claims and restores it after the final claim is released.

This claim model is important for symlinked account roots and for Codex settings shared by multiple installations. A different desired value is refused before it can replace another owner’s configuration. A shared Codex configuration can still remove one owner’s approval when no other owner claims that server.

References: crates/…/resources.rs• L109-143 crates/…/resources.rs• L465-575 crates/…/resources.rs• L600-633 crates/…/tests.rs• L474-510 crates/…/tests.rs• L1166-1200

Recovery and visibility

Interrupted transactions

Application records a pending transaction before it changes files or MCP state. If the process stops before the journal commit, recover compares the current state with the intended and prior state. It rolls back only changes that still match the transaction and reports a conflict when another change prevents a safe rollback.

The same journal also protects against a newer or invalid state format. Such state is rejected instead of being guessed at or overwritten.

References: crates/…/lib.rs• L275-382 crates/…/resources.rs• L159-186 crates/…/tests.rs• L242-336

Status reports

Status reports whether an installation exists, whether its managed resources still match, and whether Codex needs a manual action such as hook approval or folder trust. The list operation summarizes all readable installations without exposing account roots or hook commands. Resources that need a harness CLI to check can be marked unchecked when that CLI is not available.

Status evaluates each owned resource separately. Unrelated file edits remain acceptable, while an edited hook, instruction block, MCP server, or approval becomes a conflict. Invalid or newer journals do not hide other readable installations from the list report.

References: crates/…/targets.rs• L89-186 crates/…/cli.rs• L182-240 crates/…/tests.rs• L688-727 crates/…/tests.rs• L1281-1343

Runtime relationships

This page describes the agent-service boundary used by the native runtime, CLI, and external coding-agent clients. For the surrounding process model, read Native runtime and CLI and Rust CLI runtime. For account and paid-service boundaries, read Account and Pro services. For workflows that create agent behavior, read Design seed generation and Component composition operations. For the design rules that guide those workflows, read Design foundations and taste.

References: crates/…/lib.rs• L1-18 crates/…/lib.rs• L1-35 crates/…/cli.rs• L4-58

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the MCP tool list, local tool interception, and tools/list_changed behavior aligned when a local capability is added or removed.
  • Keep account-service request forwarding, sign-in retry rules, progress messages, and headless-browser errors aligned when authentication behavior changes.
  • Keep asset file checks, digest reservation, upload expiry handling, and returned-key semantics aligned across local and remote sides.
  • Keep browser extension origins, native-host manifests, socket permissions, frame size limits, and one-agent ownership rules aligned.
  • Keep presence record identity, process start-time checks, display-name rules, and the connected versus seen distinction aligned.
  • Keep target selection, rendering, resource recording, status checks, and undo logic aligned when a new managed resource is added.
  • Preserve the pending-transaction and journal contract when changing apply order or recovery behavior.
  • Recheck shared-claim and last-undo behavior when changing resource identity or installation identity.

Important failure modes

TriggerConsequenceGuard
The account sign-in is missing or lacks a needed scopeThe call waits for approval or returns a login instructionOne browser sign-in is held and the call is retried once
A local upload is missing, empty, too large, unsupported, or a symlinkNo asset reservation or upload occursThe file type, size, identity, and byte count are checked
An upload address is expired or rejectedThe asset tool returns an error and no key is claimed as completeThe upload response is checked and the agent must call the asset tool again
A browser host has an unverified engine or an unapproved extension originChrome cannot start the browser relayHost registration requires a verified engine and fixed extension origins
Another agent owns the browser relayThe caller receives a busy resultThe relay assigns one driver and tracks pending calls by connection
The browser relay or extension closes during a callThe tool returns a browser-gone error and the next call reconnectsSocket identity and framed-call failures are checked
A presence record outlives its process or its PID is reusedA stale session could appear connectedThe reader compares the recorded process start time
Another installation wants a different value for a shared file or MCP nameThe requested change is refusedShared claims are checked before writing
A person changes a managed hook, instruction block, MCP server, or approvalApply or undo reports drift or conflict and preserves the changeLast-written values and prior values are recorded
The process stops during a file or MCP changeA pending transaction remainsrecover rolls back matching changes or reports the blocking conflict
The journal is missing while managed content remains on diskUndo refuses to claim successThe service checks for the owner marker and exact hook entries

Key files

FileWhy to read it
crates/…/lib.rsDefines the local MCP session, service forwarding, sign-in recovery, and tool interception.
crates/…/asset.rsDefines safe local asset selection, hashing, reservation parsing, and the key-only result.
crates/…/browser.rsDefines browser tools, framed relay messages, local socket access, and single-agent ownership.
crates/…/host_setup.rsDefines Chrome native-host registration and verified-engine launch behavior.
crates/…/presence.rsDefines connected-session records and the local running-agent view.
crates/…/Cargo.tomlShows that the native MCP layer depends on the common and account services and handles asset hashing.
crates/…/cli.rsDefines the external agent-service command boundary, validation, verbs, and result shape.
crates/…/lib.rsDefines request types, journal state, locking, and recovery boundaries.
crates/…/targets.rsShows which harness files are in scope and how status checks managed resources.
crates/…/resources.rsExplains apply, undo, resource claims, and shared-resource behavior.
crates/…/render.rsShows how hooks, instructions, Codex features, and approvals map into harness files.
crates/…/fs_writer.rsDefines the safety boundary for file writes, deletes, symlinks, and concurrent edits.
crates/…/mcp.rsDefines MCP server discovery, synchronization, verification, and collision handling.
crates/…/tests.rsDemonstrates the end-to-end guarantees for rendering, recovery, sharing, status, drift, and undo.
crates/…/mcp.rsDemonstrates MCP collision, sharing, drift, verification, and removal behavior.