Agent Loom

Agent Loom is a local MCP server for routing multiple ChatGPT chats to multiple explicitly allowed workspaces through one endpoint and one token.

Agent Loom is derived from the MIT-licensed CodexPro connector. It exposes an OMP-native capability layer to ChatGPT Web, with direct workspace tools, OMP agents/skills/rules, and bounded one-shot Pi/Codex compatibility.

Why

ChatGPT Web can inspect and edit explicitly allowed local projects without exposing the rest of the host or relying on a per-chat launcher directory. Workspace selection is isolated per MCP session and remains explicit after reconnects.

Related MCP server: project-hub-mcp

MCP interface

Direct ChatGPT workspace tools

ChatGPT Web is the active coding agent; Agent Loom supplies the OMP capability model instead of starting a second model process. In the default standard mode it can directly use:

• read, write, edit, and apply_patch for files;

• tree, search, and view_image for inspection;

• bash for workspace-scoped verification commands;

• show_changes for Git status and diff review;

• omp to load OMP-native context, skills, and agent instructions into this ChatGPT conversation;

• agents to inspect OMP-compatible roles and model routing;

• task for one-shot compatibility workers.

Every file/shell tool accepts an explicit workspace_id or uses the workspace selected in the current MCP session. After a ChatGPT reconnect, Agent Loom deliberately refuses to fall back to the launcher root: reopen the requested project or pass its stable workspace_id. Default policy is write=workspace and bash=safe; trusted local deployments can opt into full Bash explicitly.

workspace

Each HTTP MCP connection has its own selected workspace. Different ChatGPT chats can therefore select different projects while sharing the same server URL and token.

{"action":"list"}

{"action":"use","workspace_id":"ws_..."}

Actions: list, discover, open, use, current.

discover finds bounded nested Git repositories under aggregate directories. open also returns repository candidates when the selected directory is not itself a Git root. Direct file tools can use either a repository or an allowed aggregate directory.

OMP-native ChatGPT Web runtime

omp is a capability bridge, not a model launcher. ChatGPT Web remains the active model and continues in the same conversation. No OMP/Pi/Codex model process is started by omp.

After selecting a workspace, call omp(action=status) to verify the mode, then omp(action=context) once. The context includes OMP SYSTEM.md, project/user rules, native agents, skills, prompt templates, slash-command definitions, and the OMP-native MCP tools available under the current Agent Loom policy. The native_tools field is intentionally an OMP-only subset; separate task, pi, codex, handoff, and session tools are not included.

{"action":"context","workspace_id":"ws_..."}

Load focused OMP instructions when needed:

{"action":"skill","workspace_id":"ws_...","skill_name":"debugging"}

{"action":"agent","workspace_id":"ws_...","agent_name":"reviewer"}

The loaded OMP instructions guide this ChatGPT conversation. File and shell operations still go through Agent Loom's guarded MCP tools; write, edit, and apply_patch follow AGENT_LOOM_WRITE_MODE, while bash follows AGENT_LOOM_BASH_MODE.

agents and generic task

agents(action=list) discovers project .omp/agents, user OMP agents, and bundled roles with first-wins precedence. agents(action=models) reports the selected backend's model inventory and configured roles. Built-in routing uses zai/glm-5.3-flash for @fast work and openai-codex/gpt-5.6-luna for @task/@review; set AGENT_LOOM_FAST_MODEL, AGENT_LOOM_TASK_MODEL, or AGENT_LOOM_REVIEW_MODEL to override selectors.

task(action=run) remains the one-shot compatibility workflow for bounded read-only workers. Choose agent=scout or agent=reviewer with mode=review for evidence, agent=security-reviewer for security review, or agent=task for implementation planning. Native workers run read-only inside a sanitized workspace mirror; apply approved changes through Agent Loom's guarded write/edit tools. mode=write is rejected. backend=auto selects OMP first, then Pi, then Codex. The persistent supervisor enforces global max_concurrency=1, queues up to eight generic tasks, and starts the next queued task after completion.

Native task launch requires Linux and the bwrap (bubblewrap) executable; other platforms fail closed rather than run an unguarded backend. Model inventory remains separate from task launch.

{"action":"run","agent":"reviewer","backend":"auto","workspace_id":"ws_...","mode":"review","task":"Review the current diff.","timeout_seconds":1200}

task(action=wait) and task(action=status) return structured metadata, output summary, bounded stdout_tail/stderr_tail, and the task artifact path. Each task directory contains task.json, worker.json, stdout.log, stderr.log, result.json, result.md, and the sanitized workspace mirror.

Direct pi and codex compatibility

The pi and codex tools remain available for callers that need an explicit backend. Their actions are run, wait, status, and stop; pi also supports models. Explicit compatibility calls do not queue behind another task and return a busy error when the one-task slot is occupied.

Native tasks are read-only. mode=write is rejected until a guarded native write adapter exists; use Agent Loom's direct guarded write/edit tools for authorized changes. Each task exits with fresh context; no pools, forums, agent worktrees, idle dispatchers, or h5i processes are created.

{"action":"run","workspace_id":"ws_...","mode":"review","model":"openai-codex/gpt-5.6-luna","task":"Review the current diff.","timeout_seconds":1200}

{"action":"wait","task_id":"...","wait_seconds":60}

One endpoint, many projects

Add the generated MCP URL to ChatGPT as a new connector named Agent Loom. Do not reuse or prompt for an older CodexPro connector: connector names and cached tool schemas belong to the ChatGPT connection, not to the local command. After an upgrade that changes tools or cards, refresh or recreate the Agent Loom connector.

npm install
npm run build

AGENT_LOOM_HTTP_TOKEN='use-at-least-24-random-bytes' \
node dist/http.js \
  --root /projects/default \
  --allow-root /projects/project-a \
  --allow-root /projects/project-b

Connect every ChatGPT chat to:

https://your-host.example/mcp?agent_loom_token=...

Each chat calls workspace({"action":"use", ...}) independently. A workspace path is accepted only when it is under a configured allowed root.

Local state

Do not run git init in $HOME. Agent Loom keeps launcher configuration under ~/.agent-loom/ and accesses only explicitly allowed workspace roots.

Requirements

• Node.js 20+

• Git

• Optional omp CLI, Bun, and Linux bwrap for the one-shot native OMP compatibility backend used by task(action=run).

Development

npm ci
npm run build
npm run smoke

Security

• One HTTP token gates the endpoint.

• Workspace roots are allowlisted before routing.

• File and Bash operations remain constrained by the configured write and Bash modes.

See SECURITY.md and docs/architecture.md.

License

MIT. Original CodexPro copyright and license notices are retained.