Local AI collaboration walkthrough

For an application server connection, start with connect to a document server. This page is a development exercise. Its loopback URLs and journal setting are for the local demo.

This walkthrough connects one Codex MCP participant and the three browser editors to the same local Word-style document. A browser user and the AI keep separate actor IDs and separate undo histories. The server checks the AI's edit against the exact revision it read.

The commands use an isolated demo document. The demo server has no authentication; use it only on your own machine. This walkthrough disables the MCP journal for portability. Pending work and AI history are then lost if the MCP process exits. For durable macOS or Linux recovery, use a stable private journal directory instead; see recover a session.

1. Open the shared document

Start the product demo as shown in run the editor examples. Open:

http://127.0.0.1:5413/?profile=word&doc=mcp-walkthrough

Wait until all three panels are online. In the Slate panel, add HUMAN to the end of Opening text. Check that the other two panels show the same text.

2. Connect Codex to the MCP server

In Codex, configure a local stdio MCP server. The following TOML uses the Word-style schema exported by the checkout. Replace both /absolute/path/to/doc-sync paths with the absolute path to your checkout. Use the demo's printed port if it is not 5413.

[mcp_servers.doc_sync]
command = "node"
args = ["/absolute/path/to/doc-sync/apps/mcp/src/main.ts"]

[mcp_servers.doc_sync.env]
DOC_SYNC_URL = "http://127.0.0.1:5413/profiles/word"
DOC_SYNC_DOCUMENT = "mcp-walkthrough"
DOC_SYNC_ACTOR = "ai-walkthrough"
DOC_SYNC_SCHEMA = "/absolute/path/to/doc-sync/apps/demo/products/word-schema.mjs"
DOC_SYNC_JOURNAL = "off"

This is a configuration example, not a command that changes your settings. The host must launch Node 22.18 or later. Codex supports project-scoped or user-level configuration; see the official Codex MCP configuration guide. Restart or reload the host as required by your setup, and verify that the doc_sync tools are available. Follow your host's normal approval prompts for edit tools.

For more than one AI participant, use a unique DOC_SYNC_ACTOR for each process. With durable journals enabled, use a separate stable DOC_SYNC_JOURNAL_DIR for each independent actor and server.

3. Ask the AI to edit

In the same Codex session, ask:

Use only the doc_sync MCP tools. Read the document. Insert "AI: " at the start
of the paragraph that contains "Opening text". Read again and report the edit
status. This is a local test document.

The AI should call read_document, choose the path from that model and pass its returned revision as base to edit_document. A confirmed result means the server accepted the exact edit and its echo reached the session. The expected paragraph in all panels is AI: Opening text HUMAN. The text and whitespace depend on the prompt and your earlier browser input; inspect the model if they differ.

While the same MCP session remains open, ask the AI to call undo, read the document, call redo, and read again. Its undo should remove its own insertion and leave the browser user's HUMAN text. Redo should restore the AI insertion. Do not restart an ephemeral MCP session between these steps and expect its history to survive.

4. Try a stale revision

1. Ask the AI to call read_document, show its revision, and wait without editing.
2. In the browser, make another edit and wait until the panels converge.
3. Ask the AI to attempt an edit using the saved old revision.

The client or server can reject the stale base. Ask the AI to read again and decide whether a new edit is still appropriate. The version check prevents applying an edit against an outdated model; it does not determine the author's intent.

If an edit is unconfirmed, do not submit a replacement operation. While the session remains alive, use retry_edit for that exact request. If recovery is required after a restart, use recovery_status and retain the journal. unknown is not proof of failure. See troubleshooting.

What this example proves

The repository has exercised actual Codex MCP edits and browser editors together in a bounded local test. This exercise is not evidence of production authorization, real OS IME, reliable recovery with the journal disabled, or all possible concurrent editing intents. For the exact test scope and limits, see status and limits.

Automated collaboration scenarios

The repository also tests separate MCP processes against a local demo server and an independent user synchronization client. These are deterministic client scenarios, not autonomous model evaluations:

Scenario	Expected result
Three agents edit from the same revision	One edit is confirmed. The others read the latest revision before trying again. Each participant's undo preserves the others' edits.
Offline user and AI insert at the same position	Both insertions converge. Each participant can undo and redo its own insertion.
Offline user deletes text while AI applies bold	User undo reveals the text with bold. AI undo and redo change only the formatting.
Offline user splits a paragraph while AI inserts text	The split and text converge. Both participants' undo and redo preserve the other's change.
User deletes text inserted by AI	AI undo and redo do not reverse the user's deletion. User undo can restore the text.
User edit makes an AI revision stale	The old revision is rejected. An invalid batch applies no partial change; a fresh edit can then be confirmed.
AI process restarts with a protected journal	On supported macOS and Linux systems, its restored undo and redo history preserves a later user edit.

Run the scenarios from the repository root with Node 22.18 or later:

node --test apps/mcp/test/ai-scenarios.test.ts

The test uses actual MCP stdio servers and a simulated user client. The durable journal supports macOS and Linux. Linux requires /usr/bin/flock from util-linux. Check the current test receipt for the platform actually exercised; the older macOS-only checkpoint does not establish a Linux result. It does not prove power-loss recovery, production service behavior, or real OS IME behavior.

A separate local test used an actual Codex CLI session and a scripted user client. After the user changed the document, Codex's saved revision was rejected by the local session; Codex then read the new revision, edited, and confirmed its own undo and redo. This check does not simulate a person typing in a browser.

Show the agent's current position

In a host that can use set_presence, ask the agent to report the position it is working on. For example:

Read the document. Set your presence to the range you plan to inspect,
using your actual position and the revision you just read. After any edit,
read again and update your presence to your new position. When you finish,
hide your presence.

The Word-style product demo displays the agent's name, caret and selection in its three panels when the position can be resolved. The agent must call the tool explicitly; edits do not automatically move its reported caret. A sent result is best effort, not a delivery receipt. See show an agent's position for the tool arguments and limits.

Rust experiment

A native host can resume an agent session from a checkpoint, deliver pending changes, and then undo or redo its own edit. The SDK does not provide the Codex runner, MCP tools, or approval UI from this walkthrough.

Use the native SDK crate setup to run this complete Rust program.

use doc_sync_native_sdk::{Attributes, Document, EditOptions, Key, Result, SchemaPreset};

fn main() -> Result<()> {
    let mut doc = Document::new("walkthrough-agent", SchemaPreset::Text)?;
    let mut peer = Document::new("walkthrough-viewer", SchemaPreset::Text)?;
    let inserted = doc.insert_text(
        &Key::root(),
        "Hi",
        Attributes::new(),
        EditOptions::default(),
        0.0,
    )?;
    peer.apply_remote(&inserted.ops)?;
    let before = doc.model()?;
    let mut resumed = Document::restore(&doc.checkpoint()?)?;
    let undo = resumed.undo()?;
    peer.apply_remote(&undo.ops)?;
    assert_ne!(resumed.model()?, before);
    let redo = resumed.redo()?;
    peer.apply_remote(&redo.ops)?;
    assert_eq!(resumed.model()?, before);
    assert_eq!(peer.model()?, before);
    Ok(())
}

This example uses one of six fixed SchemaPreset values. A separate runtime schema API accepts limited Document/Graphic descriptors and custom sparse-sheet fields. Live schema changes, the full doc.edit() compiler, WASM, Node, HTTP, MCP and editor bindings are not included.

Raw protocol probe and reference checks

The walkthrough above runs through TypeScript. The private native driver can check one lower-layer undo case without an AI account: a human inserts text, then a bot formats it and undoes only that formatting.

Build the driver with Run the private experiment, then run this from the repository root:

experiments/rust-shadow/target/debug/doc-sync-rust-shadow <<'JSONL'
{"cmd":"new","replica":"bot","actor":"bot","schema":"flow-root-paragraph:boolean-marks:bold,italic:v1"}
{"cmd":"apply","replica":"bot","schema":"flow-root-paragraph:boolean-marks:bold,italic:v1","ops":[{"t":"text","id":{"lamport":1,"actor":"human"},"origin":{"lamport":0,"actor":"~root"},"units":[65]}]}
{"cmd":"history_record","replica":"bot","schema":"flow-root-paragraph:boolean-marks:bold,italic:v1","ops":[{"t":"set","at":{"lamport":3,"actor":"bot"},"ids":[{"lamport":1,"actor":"human"}],"key":"bold","value":true}],"options":{"caretBefore":"0@~root","caretAfter":"1@human"},"now":10}
{"cmd":"history_undo","replica":"bot"}
{"cmd":"history_redo","replica":"bot"}
JSONL

Undo keeps the human A; redo restores the bot bold mark. Each response includes the generated operations and History. This does not reproduce an actual Codex session, MCP tool calls, stale-revision rejection, or browser typing.

This uses the fixed base text schema. Rust has no production editor, bot, or MCP adapter. See the Rust engine guide for the separate v1 through v6 capabilities and limits.