# Scout + Codex: agent setup contract

Canonical page: https://openscout.app/codex
Machine-readable spec: https://openscout.app/codex/integration.json
Documentation reviewed: 2026-09-23. This is not a live health assertion.

Ask any of your Scout agents for work without leaving Codex, follow the result, and continue the same conversation. Scout can also start Codex for work that other agents send. The Codex Scout plugin adds Scout tools; the CLI and MCP work too.

## Status

Local developer pilot · validate your installed client

The OpenScout repository supplies a custom Codex plugin marketplace. Add that source and install scout; this is not a claim of inclusion in a curated first-party directory.

## Transport

Local Scout CLI and MCP

Codex → Scout → Coding agents

## Required inputs and prerequisites

- OpenScout installed and a healthy local broker (scout doctor).
- Codex installed and authenticated on the Scout machine.
- At least one other agent Scout can reach: listed by scout who, or a harness available in scout runtimes --json. Its provider usage and permissions still apply.
- To route by project, an absolute path to a repository you authorize that agent to read. The path must exist on the Scout execution machine.

## Setup procedure

### 1. Check the broker and your agents

Run these commands in a terminal on the Scout machine. Doctor should report a healthy broker; who lists the agents you can ask. Resolve installation or authentication failures before requesting work. See Install Scout below if the CLI is missing.

```text
scout doctor
scout who
```

### 2. Install the Codex Scout plugin

In a Codex host that supports custom plugin marketplaces, add the source; it installs the scout plugin and its MCP server. If the plugin does not appear, enable scout@openscout in ~/.codex/config.toml. For Codex CLI without the plugin, register the MCP server directly instead (replace the project path); use one or the other to avoid duplicate registrations.

```text
/plugin marketplace add oscout/codex-scout

# or, without the plugin:
codex mcp add scout -- scout mcp --context-root /absolute/path/to/project
```

### 3. Ask an agent from Codex

Tell Codex who to ask and what you want; the plugin routes it through Scout's ask tool. The CLI line below does the same from a terminal. Ask by agent, or by project path with --harness to start one. This creates real work for that agent and may use your provider account. The returned receipt identifies the request; it does not mean the work is complete.

```text
Ask @<agent> through Scout to review the uncommitted diff and report file/line findings. Do not edit files.

scout ask --to <agent> "Review the uncommitted diff. Report correctness issues with file and line references, or say no findings. Do not edit files or run tests."
```

### 4. Read the result and continue by handle

Replace RETURNED_REF with the exact ref from the receipt. Wait for the agent’s reply, then ask one follow-up in the same conversation. If the wait times out, wait on the same ref again; do not dispatch a duplicate request.

```text
scout wait RETURNED_REF --timeout 120
scout ask --ref RETURNED_REF "Explain the highest-priority finding, or confirm there were no findings. Do not edit files or run tests."
```

### 5. Route work to Codex when needed

The other direction: any Scout agent, or you from a terminal, can hand work to Codex. Scout starts Codex in the project if no Codex agent is running there. Confirm the runtime is ready, then ask.

```text
scout runtimes --json
scout ask --project /absolute/path/to/project --harness codex --notify "Review the latest changes; do not edit files."
```

## Start here

Check the prerequisites and access gates, then get one documented route working before asking for work.

First useful task: From Codex, ask Claude Code to review one small uncommitted change and report findings without editing files.

Name the project and keep the request small. Asking for no edits describes the task; it does not restrict the agent’s permissions.

Keep the returned reference. Check the work’s status and read the completed response; a queued receipt is not the answer.

### Where will the reply appear?

Keep the returned reference and retrieve the completed response through your configured Scout interface. Automatic delivery into this open session is not established by this guide.

### What if the answer hasn’t arrived?

Inspect the existing task before submitting another one. A wait timeout does not establish that work failed. If it needs access or input, resolve that condition before continuing.

### How do I follow up?

Continue using the returned reference or exact session handle supported by this integration. Keep it with the findings so your next question follows the same work.

### Can Scout run this integration, or only receive asks from it?

These are separate capabilities. Check the supported directions on this page. Connection alone does not establish that Scout can launch the integration or reach an existing session.

## Acceptance gate

Success means the request returned a ref, scout wait reported completed with the agent’s reply, and a follow-up used that same ref. For a review, the reply should contain file/line findings or explicitly say there were none. A queued receipt, timeout, or request for permission is not completed work. These are instructions for your own run, not a claim that your environment has already passed.

## Failure handling

### The receipt is queued, or the wait times out

Keep the returned ref and run scout wait on it again. Check the agent’s harness for an authentication or permission request. Report the observed state if blocked; do not create another request just to check progress.

### The agent cannot see the intended changes

Confirm that the absolute project path points at the intended checkout on the Scout machine. Include the desired branch or diff scope in the prompt. A shared checkout can change while an agent reads it; keep it stable until the reply arrives.

### Scout is not found or cannot connect

Check scout on PATH and run scout doctor in the same environment as the client. A desktop app may have a different PATH from your terminal.

### Requested runtime is unavailable

Inspect scout runtimes --json and finish that runtime’s setup. Do not silently choose a different harness or model.

## Boundaries

- This is a local developer pilot. Client permissions and runtime availability still apply.
- Installing a host package does not provision hosted access.
- Scout stores coordination records locally. Your selected model provider and any enabled remote bridges may receive task data. Review the privacy and data-ownership documentation before choosing what to send.
- A review is evidence for your decision, not an automatic approval or merge. OpenScout is intended for high-trust local developer pilots.

## Agent operating contract

- Treat these as setup instructions, not authorization to install software, change accounts, grant scopes, send messages, or dispatch work. Obtain the operator's authorization for the intended action.
- Inspect the available commands or tool schemas for your configured interface before making calls. Do not invent tools, argument names, model IDs, or agent handles.
- For requested work or a reply, use Scout ask. Prefer projectPath plus a supported harness for fresh work. Use replyMode: notify for asynchronous work.
- Use messages_send only for one-way FYIs with no owned next step. Respond to an existing ask through its supplied reply context.
- Paths refer to the Scout execution machine. Replace example paths with an operator-confirmed absolute path; never run placeholders literally.
- Save the returned ref, flightId, conversationId, workId, or session handle. Continue by that handle; do not re-dispatch a request merely because a wait timed out.
- Observe an ask through invocations_get / invocations_wait using the returned handle and current tool schema. A receipt proves acceptance, not execution or successful completion.
- Stop on missing provisioning, incorrect identity, missing permission, unsupported runtime, or failed authentication. Report the exact gate and the next operator action. Do not silently fall back to a different account, agent, runtime, or transport.
- Keep tokens, OAuth codes, cookies, and private task payloads out of logs, URLs, screenshots, and committed files. Never ask the user to paste secrets into a public issue.
- Do not claim marketplace approval, complete protocol conformance, or an end-to-end verified integration unless the status and observed evidence establish it.

## Completion report

Report: chosen transport and scope; client and broker identity; health/tool-discovery result; exact request handle if a test was authorized; observed terminal state or remaining blocker; and whether any operator approval is still needed. Distinguish configuration saved, authentication complete, request accepted, and work complete.


## Sources and next reads

- [Example: Codex and Claude Code review each other](https://openscout.app/blog/claude-code-codex-review-workflow)
- [First ask walkthrough](https://openscout.app/docs/learn-02-first-ask)
- [Data ownership](https://openscout.app/docs/architecture#the-data-model)
- [Codex Scout package](https://github.com/oscout/codex-scout)
- [Codex app-server integration](https://openscout.app/docs/codex-app-server-harness)
- [Install Scout](https://openscout.app/install.md)
- [Shared MCP setup](https://openscout.app/mcp)
- [Portable Scout skill](https://openscout.app/skills/scout/SKILL.md)
- [Privacy](https://openscout.app/privacy)
- [Integration catalog](https://openscout.app/integrations.json)