coding-tools-mcp: Instructions file for Codex

Coding Tools MCP repository guide

This repository is a monorepo. Keep changes inside the narrowest owning subtree and avoid creating cross-component coupling unless the feature requires it.

Repository map

• coding_tools_mcp/: core Python MCP runtime and public server behavior.
• apps/desktop-client/: desktop client UI and desktop runtime integration.
• integrations/tunnels/: user-facing tunnel launchers for remote MCP access.
• infra/cloudflare/sandbox-control/: Cloudflare Worker control plane paired with .github/workflows/start-sandbox.yml.
• packages/npm-launcher/: thin npm launcher for the Python package.
• media/promo-video/: Remotion source for the project promo video.
• benchmarks/: benchmark runners and fixtures.
• reports/: generated/published benchmark and compliance results.
• docs/: user, contributor, architecture, and reference documentation.
• scripts/: repository maintenance, validation, installation, release, and report-generation scripts. Do not put user-facing runtime integrations here.

Agent execution context

• Local CLI agent: when the agent already has local filesystem, patch, and command execution on the host, use those native local tools. Do not route local development through ct.* merely because remote-agent examples exist.
• Remote ChatGPT agent through the ct plugin: use the available ct.* MCP tools, follow their schemas exactly, and use workspace-relative paths. The live MCP providing that connection is part of the agent's access path and must not be restarted or replaced from that same remote session.
• Tool-specific examples must be labeled for their execution context. Describe the required operation first; do not write a global rule that makes every agent call ct.* or assume unavailable local tools.

Standing rules

1. Preserve public CLI names, Python import paths, protocol schemas, and release behavior unless a task explicitly requires a breaking change.
2. Keep one authoritative home for each fact; link to it instead of copying long explanations between documents.
3. Changes to infra/cloudflare/sandbox-control/ and .github/workflows/start-sandbox.yml may form one interface contract. Update and validate them together.
4. Prefer subtree-specific instructions when present.
5. Run the narrowest relevant checks first, then broader checks when tooling is available.
6. For a remote agent using Coding Tools MCP command execution, prefer workspace-relative workdir/paths such as . instead of absolute workspace paths; the MCP sandbox may reject absolute working directories even when they point inside the configured workspace.
7. For GitHub pushes from this workspace, prefer the already-working SSH authentication path. If origin uses HTTPS and push fails because credentials are unavailable, verify SSH authentication and push via the equivalent [email protected]:<owner>/<repo>.git URL rather than repeatedly retrying unauthenticated HTTPS. Do not rewrite the configured remote unless the task requires it.
8. In a remote ct session, use ct.apply_patch for direct repository file modifications and treat each patch as atomic: if any hunk cannot be matched safely, the whole patch may be rejected. Do not bypass a rejected patch with shell redirection, inline scripts, editor commands, or another direct-write path. A local CLI agent should use its runtime's native patch facility instead.
9. Before applying a patch, read the current affected region and build patch context from the latest file contents. Use sufficiently unique anchors, especially in repetitive JavaScript, CSS, tests, task lists, and Markdown.
10. Keep each patch scoped to one coherent change. Avoid bundling unrelated implementation, tests, OpenSpec documents, and UI artifacts into one large patch merely to reduce tool calls; one stale or ambiguous hunk would reject the entire atomic patch.
11. After modifying a file, do not reuse stale patch context for that file. If a patch is rejected, re-read the affected region, determine whether the cause is stale or ambiguous context, and construct a new patch instead of retrying the same envelope unchanged.
12. When a target fragment occurs multiple times, anchor the patch with the nearest unique function name, CSS selector, Markdown heading, or surrounding semantic block rather than a short repeated line.
13. Remote ct agents must follow Coding Tools MCP tool schemas exactly. Do not guess parameter ranges or retry a schema-invalid call without correcting its arguments first.
14. Treat the MCP Server that is currently providing Coding Tools access for an active development session as protected infrastructure. Development, validation, preview, restart, systemd, process, listener, or port-management work MUST NOT stop, restart, replace, signal, rebind, or otherwise disturb that live MCP process, because losing it removes project read/write access. Before any operation that can affect services, processes, or listeners, identify the exact target PID/listener/unit and verify it is not the active MCP Server; do not assume a fixed PID or port. Use separate processes, ports, state directories, and service units for previews and destructive/restart validation. If install/restart/live-listener acceptance would sever a remote agent's ct connection, prepare the exact procedure and hand execution to an out-of-band local shell instead of touching the live access path.