ACP integration
The ACP (Agent Communication Protocol) runtime is Mogick's embedded mode. It communicates with a host over bidirectional JSON-RPC 2.0 on standard input and output (stdio), allowing an IDE, desktop application, or other host to use Mogick as its agent engine without launching the full-screen TUI. The host owns the user experience while reusing Mogick's runtime capabilities.
Start the ACP runtime:
| Startup method | Description |
|---|---|
mogick acp | Start ACP mode. Mogick takes over the process's standard input and output and communicates over bidirectional JSON-RPC 2.0. |
mogick acp is intended for integration developers. An IDE plugin or desktop application launches it as a subprocess, then exchanges JSON-RPC 2.0 messages with Mogick over stdio. End users typically do not run this command directly.
ACP compared with the TUI
The TUI and ACP serve different use cases. The TUI provides a complete interactive experience for terminal users, while ACP gives the host application control of the interface and session lifecycle.
| Dimensions | TUI | ACP Runtime |
|---|---|---|
| Interface | Full-screen terminal UI rendered by Mogick | Provided and rendered by the host |
| Communication | Keyboard input and terminal output | Bidirectional JSON-RPC 2.0 over stdio |
| Session management | Users create, switch, and delete sessions | The host controls sessions through protocol methods |
| Typical scenarios | Working with the agent directly in a terminal | IDE plugins, desktop applications, and automated pipelines |
In short, the TUI is a complete terminal application for people; ACP is an integration protocol for applications.
Protocol methods
ACP exposes standard methods and extension methods. Standard methods follow the shared agent protocol and are portable across implementations. Extension methods use the _mogick/ prefix for Mogick-specific capabilities. Standards-compliant clients can ignore extensions they do not recognize.
Standard methods
| Method | Description |
|---|---|
initialize | Negotiate protocol version and capability set supported by both parties |
session/new | Create a new conversation session |
session/load | Load an existing session and restore historical context |
session/list | List the currently persisted session summary |
session/prompt | Send a user prompt to the model and get the response |
session/cancel | Cancel the active agent run |
session/delete | Close the session and release runtime resources while preserving its history |
session/set_config_option | Dynamically update session-level configuration items at runtime |
session/set_mode | Switch session execution mode (Agent / Plan) |
session/set_model | Switch the model used by the session |
session/commands/refresh | Refresh the list of commands available to the host |
authenticate | Inject authentication credentials, such as an API key, from the host |
Extension methods
Extension methods cover Mogick-specific capabilities such as checkpoint management, session lifecycle operations, and multi-provider configuration. CRP (Copilot Runtime Protocol) is Mogick's internal runtime protocol. In 26.9.11, sessions export does not expose CRP trace export; conversation export is not a protocol trace.
| Prefix | Capabilities |
|---|---|
_mogick/session_checkpoint_* | Creation, listing, recovery and deletion of checkpoints |
_mogick/session_{close,reopen,archive,unarchive,delete,fork} | Session lifecycle operations; session_delete permanently deletes a session |
_mogick/model_provider/* | Multi-provider model configuration and switching |
_mogick/session_{attach,detach,lock_info,request_write,force_write,release_write} | Multiple client attachments and single writer locks |
_mogick/session_mcp_update | In-session MCP configuration hot update |
_mogick/workspace_update, _mogick/session_system_event, _mogick/session_plan_action | Host workspace and session state synchronization |
_mogick/skills_state_update | Skills status synchronization |
_mogick/session/updateMetadata | Session metadata update |
_mogick/changeset_traces, _mogick/changeset_patchsets, _mogick/execution_summary | Changeset and execution evidence query |
Host capability injection
During initialize, a host can declare that it provides selected capabilities. Mogick then delegates the corresponding requests to the host, enabling deeper integration.
| Capability | Behavior |
|---|---|
| FS | The host handles file operations such as reading, writing, listing, and deleting instead of Mogick's built-in file tools. |
| Terminal | Shell commands are sent to the host terminal first. If the host does not support terminal execution, Mogick falls back to its local shell. |
exitPlanApproval | When plan.write completes a Plan-mode turn, the host displays the plan approval UI instead of requiring the model to invoke an exit tool. |
Capability injection lets an IDE keep file operations inside its own sandbox and lets desktop applications manage terminal permissions consistently. This prevents Mogick from bypassing the host to access system resources directly.
Multi-client attachment
A single Mogick ACP process can attach multiple clients to the same session. A single-writer lock protects the write slot. Detect this capability through agentCapabilities._meta.mogick.multiAttach in the initialize response; no environment variable is required.
Design points for multi-client environments:
| Feature | Description |
|---|---|
| Single-writer lock | Only one client can send session/prompt at a time, preventing concurrent writes from corrupting session state. |
| Automatic lock release | If the client holding the write lock disconnects unexpectedly, Mogick releases the lock after a 30-second grace period so another client can take over. |
| State synchronization | Clients track session changes through monotonically increasing event revision numbers, keeping their views consistent. |
| Permission prompts | Permission requests from background sessions are suspended and presented again when the corresponding client returns to the foreground. |
If a client calls session/load before _mogick/session_attach, pass _meta.mogick.historyReplayCursor from the load response unchanged as replayAfterEntryId in the attach request. Mogick then replays only entries after that cursor, avoiding duplicate hydration of the same assistant response.
Mogick control-plane metadata injected by the ACP host is not forwarded to the underlying tool executor. Integrations must not rely on tools receiving these internal fields.