Set up OMP Tandem

Separate three concerns: install the external executables once, let the MCP launcher prepare its Python runtime, and have the user authenticate their chosen provider in OMP. Do not read credential files, copy tokens, infer an account, change global settings without permission, or run a paid diagnostic without the user's request. Explain changes and get user consent before installing tools, preparing dependencies explicitly, or adding/removing client registrations.

OMP Tandem is MIT-licensed in the public Flyozzzz/omp-tandem-public repository. Local plugins require a host that can run local stdio MCP subprocesses on macOS/Linux or WSL. Installing this package in a web-only client does not deploy a server there. Optional hooks use a POSIX shell; Claude watchdog hooks also use the existing uv prerequisite with an offline cached Python interpreter.

The first-run goal is one useful task, not learning every MCP tool. Guide the user through installation/provider setup → correct project and local diagnosis → first read-only review. A separate paid live check is optional and requires explicit approval; do not force it before an already requested useful provider task.

Shared cards need no autonomous service. Claim/submit require the bound root itself to be a Git repository with HEAD; task cwd cannot repair a parent-directory launch. Never initialize an unintended repository to silence a diagnostic. Detached work requires explicit operator project/tool/shell/time/launch/cost limits; diagnosis never grants autonomy, resumes a terminal or installs a service.

Before operator setup, retrieve shared tasks and authorization and controlled review checks. Use the package's prepared Python, not an assumed global module. Preview is not authority/readiness; fresh review-check grants authorize supervisor-owned declared container commands, not reviewer shell. No automatic image pull, host fallback or permission expansion.

Teams use only available openai-codex subscription models; Jev's OpenRouter key enables advice, not API workers. Inspect tandem_scope.team and paged tandem_team(action="models"); missing models are a blocker, not permission to switch providers. model_selection="coordinator" avoids team-summary export. Three ordinary execution slots plus one think-only coordination slot share the global four-slot pool; managed/team work cannot use the reserved lane.

Jev recommendation/routing/focus shipped in 3.12.0, but inspect loaded capabilities. Never fetch credentials, self-enable, infer export consent or restart active work for advice. Recommendation previews are keyless; sending requires approved bytes/hash. Routing is shadow-only and needs its own operator pool/policy. Focus needs separately approved data classes and explicit current-turn consent; required rules and permissions stay fixed. Exact policy/setup: recommendation, routing, focus.

1. Inspect without changing state

Determine the actual package directory from this skill's installed location: it is two directories above skills/setup/. Do not confuse a cached installation with the user's working project. In the examples, replace the path with that package directory:

TANDEM_ROOT='/absolute/path/to/omp-tandem'
command -v uv
command -v omp

If an existing Python 3.12 or newer is available, use it for a dependency-free diagnostic:

python3 -I "$TANDEM_ROOT/server.py" --doctor

If using uv instead, note that uv may first download a compatible Python interpreter; obtain consent for that provisioning when needed:

uv run --no-project --python '>=3.12' python -I "$TANDEM_ROOT/server.py" --doctor

--doctor reports executable/dependency prerequisites without installing application dependencies or probing provider authentication. Do not mistake an executable's presence for working provider credentials. The prerequisite diagnostic handler only checks whether uv and omp are on PATH; separate Claude session handlers establish and invalidate watchdog ownership without calling a model.

Loaded runtime and operator recovery

Inspect connected runtime_identity, not only disk files: loaded package/build/schema, checkout, requested/effective/observed models and grant provenance are different facts. Updating a checkout does not replace a loaded server. Editable/unverifiable builds remain unknown; do not interrupt sessions or migrate grants during diagnosis.

Use tandem_overview for a bounded read-only inbox and follow exact current read/repair descriptors. It grants no authority, recovers no lease and restarts nothing. Task/review details=true remains bounded; use tandem_read_result readers and exact digest-bound continuation arguments. Artifact readers retain character cursors. For compact work views, current evidence, report-only claim recovery and application receipts read compact contracts.

Wrong roots, unresolvable commits, expired grants and uncertain effects are not repaired by reinstalling, changing cwd, inventing consent or replaying execution. Independent clarification needs a new agreed snapshot, not author free text or live files. Stop confirmation is not absence of external effects. Only the operator may reconcile, transition, authorize or apply; model reports and old receipts cannot substitute.

Retrieve the exact existing procedures when needed:

• Plan transitions: pending proposal versus active revision, inventory/teardown, checkpoint preservation and explicit capture-loss acknowledgment.
• Repository handover: stop/dispose, correct-scope successor card, cancel/link provenance; no transferred grants or acceptance.
• Operator blocker resolution: exact current revision/operation ID and evidence; unblock does not resume or authorize.
• Runtime pinning and candidate isolation: prepared-generation selection, private candidate state and intentional schema upgrade. Old binaries cannot be assumed to enforce newer gates.

Keep provider refusal facts and failed-run evidence. Recovery is not policy reformulation; historical compatibility reports apply only to their recorded builds. Acceptance, application and publication remain separate.

2. Install missing external tools once

Present the appropriate official method and run only the user's chosen method after approval. Do not execute every alternative. No Bun installation is required for the Homebrew or standalone OMP options.

With an existing Homebrew installation:

brew install uv
brew install can1357/tap/omp

Official standalone installers for macOS/Linux (review downloaded scripts before executing if desired):

curl -LsSf https://astral.sh/uv/install.sh | sh
curl -fsSL https://omp.sh/install | sh

With Bun already installed at a version supported by OMP:

bun install -g @oh-my-pi/pi-coding-agent

Do not install Bun merely to run that alternative when Homebrew or standalone installation is suitable. Use the official uv installation guide and OMP installation instructions for other platforms and current requirements. Ensure the client process, not just an interactive shell, inherits a PATH containing uv and omp; restart it after changing the environment.

3. Prepare Python dependencies

Normal MCP startup automatically prepares the frozen package runtime. For explicit preparation before connecting the client:

uv run --no-project --python '>=3.12' python -I "$TANDEM_ROOT/server.py" --prepare

This may download Python and install locked dependencies. The command prints a JSON preparation result. The runtime is a non-editable installation cached outside the plugin code directory, under the client-provided PLUGIN_DATA or CLAUDE_PLUGIN_DATA, or otherwise ~/.cache/omp-tandem. Different source/build inputs get separate runtime identities. Preparing dependencies does not configure OMP providers or move project data into the runtime cache. A preparation performed outside the client may use a different cache base than that client's later launch.

4. Let the user choose and authenticate a provider

Have the user run OMP interactively:

omp setup
omp

Inside OMP, /login handles supported provider sign-in and /model selects the model/role. Follow the chosen provider's actual setup requirements; some providers use API keys, some account sign-in, and some local servers. The user should enter secrets directly in OMP or its documented secure setup path, not paste them into the MCP conversation.

OMP supports multiple providers and custom compatible endpoints; this is not a guarantee that every arbitrary model can execute this workflow. Choose an OMP-supported provider/model with adequate tool calling and instruction following for the requested work. Do not assume that the MCP host's account authenticates OMP, or impose a particular provider, model, or subscription. Confirm any billable model smoke request with the user separately from executable/dependency diagnostics. See OMP provider configuration.

5. Choose one registration route per client

Before adding anything, inspect the client's existing plugin/MCP registrations and keep one OMP Tandem registration. A plugin includes the MCP server; do not also add it manually under another name. Removing an old registration requires consent and must preserve unrelated configuration and project data.

Claude Code plugin

For the public GitHub repository:

claude plugin marketplace add Flyozzzz/omp-tandem-public
claude plugin install omp-tandem@omp-tandem

Or register a local checkout as the marketplace, then install the same plugin identity:

claude plugin marketplace add "$TANDEM_ROOT"
claude plugin install omp-tandem@omp-tandem

Select the appropriate installation scope and follow the client's reload/restart instructions. Use /omp-tandem:setup or /omp-tandem:tandem. Review optional hooks through the client's normal controls; do not bypass permissions or automatically enable model trust. The Claude manifest loads its own MCP and hook configs, not the portable MCP config.

Codex / Agent Plugins

Use current Codex with portable Agent Plugins 1.0 support:

codex plugin marketplace add Flyozzzz/omp-tandem-public
codex plugin add omp-tandem@omp-tandem --json

For a local checkout, replace the first command with:

codex plugin marketplace add "$TANDEM_ROOT"

Alternatively open /plugins in Codex, select the omp-tandem marketplace and install omp-tandem. Start a new session. Other Agent Plugins clients discover root plugin.json, mcp.json, and skills/ according to their supported installation flow. Only OpenAI clients interpret extensions.com.openai; no legacy .codex-plugin shim is required.

Codex users may review the optional diagnostic hook with /hooks. Installing the plugin does not trust hooks automatically, and untrusted/disabled hooks must not prevent MCP use. Do not use hook-trust bypass flags. Portable MCP subprocesses default to the plugin directory under the standard: that directory is not the user's project. Check tandem_scope in the intended project and use the launch/workspace-binding instructions in the package README; never fix an unbound instance by passing a task cwd, inventing a session-root placeholder, or storing a shared last-project value.

Manual stdio MCP, without a plugin

From the intended project, configure executable uv with arguments run, --no-project, --python, >=3.12, python, -I, and the absolute package path to server.py. Isolated Python prevents project/PYTHONPATH modules from replacing bootstrap imports; it does not sandbox OMP. For Claude Code, one local registration is:

claude mcp add --scope local --transport stdio omp-tandem -- uv run --no-project --python '>=3.12' python -I "$TANDEM_ROOT/server.py"

For Codex without the plugin:

codex mcp add omp-tandem -- uv run --no-project --python '>=3.12' python -I "$TANDEM_ROOT/server.py"

A typical JSON client configuration is:

{
  "mcpServers": {
    "omp-tandem": {
      "command": "uv",
      "args": ["run", "--no-project", "--python", ">=3.12", "python", "-I", "/absolute/path/to/omp-tandem/server.py"]
    }
  }
}

Use the client's documented stdio schema and workspace-binding mechanism. Do not copy ${PLUGIN_ROOT} or ${CLAUDE_PLUGIN_ROOT} into a client that does not expand them. Leave the caller's intended working directory intact; never set it to the package directory to make imports work. The canonical launcher handles dependencies and package imports itself. Manual MCP does not install skills or hooks; the tools remain fully usable without either.

Optional one-command Claude launch

For a user who wants the webhook without retyping environment variables and channel flags, follow the claude-tandem shell-function instructions in docs/guide.md#one-command-launch (localized guides are available). Explain and get consent before editing their shell configuration. This is currently manual setup, not an automatically installed launcher. Use the development-plugin channel identity for a custom channel; do not confuse it with the standalone server or an allowlisted plugin. Do not add --dangerously-skip-permissions by default, replace the ordinary claude command, or claim a hook can enable parent-process Channels.

6. Confirm the right boundary before using a model

After reconnecting, discover the actual namespaced tandem_scope tool and check its project identity from the intended workspace. It must not refer to a plugin cache or an unrelated project. Data isolation is not an OS sandbox; additional work directories do not grant access to another project's MCP history. Keep legacy migration copy-only and use explicit export/import for authorized context sharing.

Use tandem_diagnose() for current-client local diagnostics. If the user requests a live check, call tandem_diagnose(live=true, expected_project=...); explain that it starts one short provider request and may incur a charge. Continue inspecting its returned task ID if still running. Do not rerun paid diagnostics just to confirm a channel probe. Actual model/authentication, channel receipt and independently armed watchdog are separate observations.

Once setup is ready, ask for a concrete review requirement and whether the material is staged or working content. Use tandem_review_run for the first read-only review, with a stable request key and explicitly needed context paths. Follow run status until terminal, report complete answers and current applicability, and explain known peer cost versus unmeasured coordinator cost. Do not silently grant work, execute test commands or apply changes. Remind the user that closing the owning MCP session stops active work.

For binary/protocol compatibility, use the separately documented scripts/verify_omp.py check in docs/compatibility.md: a real checksum-pinned OMP binary with an isolated localhost test provider, not the user's paid account. This verifies the recorded binary/SDK combination, not arbitrary models or a claimed version range.

The Claude plugin includes a bounded PostToolUse asyncRewake watchdog plus session lifecycle handlers. Review/enable these through ordinary client controls. Confirm only a watchdog token delivered by a real hook wake, separately from the real channel probe. delivery=push without live watchdog coverage still requires bounded polling. The hook uses offline uv and cached Python; unavailable hooks/interpreter leave polling available. Do not interpret its control exit 2 as a failed OMP task or substitute ordinary async=true.

If startup fails, distinguish a missing executable, interpreter/dependency preparation failure, a client registration error, and an unavailable workspace binding. Report the actual error without exposing credentials. Do not repair by changing provider accounts, disabling isolation, or sharing project state. Consult the package README for the launch options supported by this installed version.

References: Claude plugins, Claude marketplaces, Agent Plugins 1.0, OpenAI packaging, and Codex hooks.