Portability Without Feature Parity

mksglu/context-mode is designed to move the same context dataflow across many AI coding hosts, but the host determines which boundaries can actually be enforced. This chapter compares the integration contracts behind that portability: JSON hooks, native TypeScript plugins, and MCP-only operation. The useful judgment is not how many clients appear on a support list. It is whether a particular host can route a tool before execution, capture work after it, snapshot state during compaction, restore it later, and identify the correct project and tool names.

The common layer and the host-specific contract

The portable part of context-mode is its MCP/tool surface. The same core operations can run code, process a file, gather commands, fetch and index a URL, search stored content, report statistics, diagnose an installation, upgrade the package, or purge stored data. Those tools define the dataflow described earlier: raw material can be processed or stored outside the conversation, and selected results can come back.

The non-portable part is the lifecycle around those tools. A host may offer a callback before a tool runs, a callback after it finishes, an event before compaction, a session-start injection channel, or none of these. It may expect a denial as a JSON field, an exit code, a thrown exception, or a host-specific object. It may allow a hook to modify arguments but not output. It may expose a session identifier under a different field or provide only a parent-process fallback. Context-mode’s adapters translate those contracts into a common routing and session model, but they cannot create a lifecycle event that the host does not expose.

The project groups its supported environments into three broad paradigms. In the JSON stdin/stdout paradigm, a host launches a hook command and passes an event as JSON. Context-mode parses the payload, makes a normalized decision, and formats the host’s expected response. In the native TypeScript plugin paradigm, context-mode runs in the host process and registers callbacks directly. In the MCP-only paradigm, the tools are available, but there is no programmatic hook layer to intercept native tools or capture every lifecycle transition.

These paradigms are not a ranking from good to bad. A JSON hook host can provide strong enforcement but have awkward response semantics. A native plugin can avoid a redundant MCP child but depend on experimental host APIs. An MCP-only client can still benefit from sandbox computation and searchable content while lacking automatic session continuity. The criterion is fit between the host’s actual contract and the guarantee the operator wants.

classDiagram class CoreTools { ctx_execute ctx_search ctx_fetch_and_index } class JSONHooks { beforeTool afterTool beforeCompact sessionStart } class NativePlugins { inProcessCallbacks hostLifecycleEvents } class MCPOnly { toolsOnly instructionGuidance } class Routing { denyOrModify redirectHighFloodCalls } class SessionState { capture snapshot restore } class HostCaveats { missingEvents responseDifferences versionGates } CoreTools --> JSONHooks : surrounded by CoreTools --> NativePlugins : embedded with CoreTools --> MCPOnly : exposed through JSONHooks --> Routing : can enforce NativePlugins --> Routing : can enforce JSONHooks --> SessionState : can capture NativePlugins --> SessionState : can capture MCPOnly ..> SessionState : limited or voluntary Routing --> HostCaveats : depends on host SessionState --> HostCaveats : depends on host

The adapter is therefore an interface boundary, not a second implementation of every tool. It preserves the core tool behavior while translating lifecycle events and response shapes. The arrows to host caveats are essential: routing and session continuity are properties of a combined system, not properties of the MCP server in isolation.

Where the same request changes meaning

Consider a WebFetch call. On a host with a working before-tool hook, context-mode can identify it and return a redirect to ctxfetchandindex or ctxexecute.