Kontrol: Instructions file for Codex

Kontrol

This project exposes local development workspaces over MCP so ChatGPT, Claude, or another MCP-capable host can operate on this machine's approved development directories. It supports two complementary workflows:

• Direct MCP workspace operations, where the host calls tools that read files, edit files, search code, and run shell commands against an opened workspace.
• Delegated ACP worker runs, where Kontrol dispatches a bounded task to a registered local coding agent and routes completion through a human-reviewed Ralph/Nelson loop.

Pi's SDK is currently used as the backend adapter for mature local coding primitives such as read, edit, write, grep, find, ls, and bash. Kontrol wraps those primitives behind a remote Streamable HTTP MCP interface, suitable for use through a Cloudflare Tunnel.

Workspace records identify the shared project/root and checkpoint state; conversation-sensitive instruction discovery, skill activation, active work-session attribution, and UI selection belong to the owning MCP session context. A shared workspace ID must not cross that boundary.

The model-facing workflow is workspace based. MCP clients should call open_workspace once per local project directory or worktree, then reuse the returned workspaceId for subsequent tool calls in that same folder. Do not call open_workspace again for the same folder unless the workspaceId is rejected as unknown, the client switches folders/worktrees or checkout/worktree mode, or the user explicitly asks to reopen. AGENTS.md files are returned automatically by open_workspace and by later tool calls when the requested path enters a directory with instructions that have not been loaded for that workspace.

ACP review workflow:

• Reviewer tools and worker tools are separate. Workers must never approve their own work or operate on a work session they are not bound to.
• Reviewer and delegation routing: the active WebUI model is the primary reviewer, orchestrator, and inspector. Review, audit, diagnosis, architecture, and code-edit work starts directly in the opened workspace. ACP workers are optional bounded assistance only; call discover_agents before delegation, dispatch only a currently dispatchable healthy role: agent peer, and when optional assistance is unavailable return to direct workspace work without trying an alternate ACP path. When the caller platform is identifiable, prefer its healthy registered native harness (for example ChatGPT/OpenAI to Codex); otherwise use any healthy registered ACP peer. agentName is an explicit override. The platform hint affects routing only, never authority. A normal review must not enter supervised work. Ordinary non-Git directories are valid checkout workspaces; Git is required only for managed worktrees.
• Review checkpoints are backend-neutral: Git workspaces use immutable Git snapshots, while ordinary directories use content-addressed filesystem snapshots without initializing or mutating Git. Submissions, approval, and verification bind to snapshotKind plus snapshotRef; any patch is only a bounded presentation of that exact snapshot. Structured read-only read, grep, glob, and ls remain public even in codex tool mode.
• submit_to_coding_agent and supervised mission tools create durable work sessions. A worker submits changes with submit_for_review, then blocks on await_review_feedback.
• A reviewer provides approval, rejection, or structured change requests through the WebUI/MCP tools. Change requests create durable continuations; approval is bound to the exact submission hash, review epoch, and workspace snapshot.
• begin_supervised_work, inspect_supervised_work, continue_supervised_work, and approve_supervised_work are the mission control plane for acceptance-criterion-driven work.
• Cancellation is durable and must stop the logical work session, supersede pending continuations, and request cancellation from the remote worker. The record remains in cancelling until worker shutdown or a confirmed missing remote run, then becomes terminal; workspace leases stay fenced meanwhile.