How mksglu/context-mode works
Purpose and Entry Points
Context Mode is a local Node.js/Bun context-management system for AI coding clients. It exposes MCP sandbox, indexing/search, statistics, diagnostics, upgrade, and purge tools; captures session state through client hooks; and restores concise working state after compaction or resume. Primary executable paths are src/cli.ts, start.mjs, and the MCP server in src/server.ts; distributable bundles are cli.bundle.mjs and server.bundle.mjs.
CLI, MCP Server, and Tool Execution
The CLI dispatches terminal commands, hook invocations, and MCP startup. The server publishes the ctx_* tool surface and routes requests into execution, search, session, and lifecycle services. Sandboxed execution runs code in subprocesses and returns bounded stdout rather than raw artifacts; batching/pooling supports concurrent work.
• src/cli.ts
• src/server.ts
• src/executor.ts
• src/runPool.ts
Cross-Client Adapter Boundary
Adapters isolate client-specific configuration paths, protocol shapes, hook registration, platform detection, and installation behavior behind common adapter types. Supported clients include Claude Code, Codex, Gemini, Cursor, Copilot variants, OpenCode/Kilo, Pi/OMP, OpenClaw, Kimi, Kiro, Qwen, Zed, and Antigravity. This boundary prevents core context/session semantics from depending on a particular agent runtime.
• src/adapters/base.ts
• src/adapters/detect.ts
• src/adapters/client-map.ts
• src/adapters/types.ts
Hook Routing and Event Capture
Client hook shims normalize lifecycle events—pre-tool routing/security decisions, post-tool capture, prompt submission, compaction, session start, and stop—into shared behavior. Pre-tool routing blocks or redirects high-output/raw-data operations where host capabilities permit; post-tool and prompt hooks generate structured session events. Platform bridges and formatters adapt each host’s stdin/stdout payload and response contract.
• hooks/run-hook.mjs
• hooks/pretooluse.mjs
• hooks/posttooluse.mjs
• hooks/core/routing.mjs
• hooks/platform-bridge.mjs
Session Continuity Pipeline
Structured tool and prompt events are persisted per project/session, classified, and later condensed into snapshots. On compaction or continuation, snapshots and relevant event history are reconstructed into a session directive rather than replaying raw transcripts. Analytics/pricing derive usage, cost, and savings reports from this same persisted state.
• src/session/db.ts
• src/session/event-emit.ts
• src/session/extract.ts
• src/session/snapshot.ts
• src/session/analytics.ts
Local Knowledge Store and Retrieval
The knowledge subsystem indexes local content and fetched pages into project-scoped SQLite FTS5 stores. Unified retrieval combines porter and trigram search, applies ranking/reranking and snippets, and limits repeated searches with a flood guard. URL fetches use a TTL cache; raw fetched content stays local while searches return selected excerpts.
• src/store.ts
• src/search/unified.ts
• src/search/auto-memory.ts
• src/fetch-cache.ts
Runtime, Storage, and Security
The runtime selects Bun SQLite, Node node:sqlite, or better-sqlite3; storage roots are adapter/project-aware. Security applies Claude-style allow/deny policies to sandbox commands, constrains file processing to project boundaries, and hardens network fetch targets. Native/plugin integrations run in-process where supported, notably OpenCode/Kilo, Pi/OMP, and OpenClaw.
• src/runtime.ts
• src/db-base.ts
• src/security.ts
• src/store-directory.ts
• src/adapters/openclaw/plugin.ts
Distribution and Integrations
Client-specific installable bundles, rules, skills, and hook manifests live under configs/ and plugin directories. OpenClaw has a dedicated gateway plugin, while Pi ships an extension. The optional static web/ content is informational/dashboard-facing, not the product’s primary runtime; all context data processing and SQLite persistence remain local.
• configs/
• .openclaw-plugin/index.ts
• .pi/extensions/context-mode/index.ts
• web/worker.js
Main entry points: server.ts MCP server · run-hook.mjs Hook shims · db.ts Session database · base.ts Adapter contract
Components 20
Entry & MCP
- CLI dispatcher · Dispatches commands, hooks, and MCP startup.
src/cli.ts - MCP server · Publishes the ctx_* tool surface.
src/server.ts - Sandbox executor · Returns bounded command output.
src/executor.ts - Execution pool
src/runPool.ts
Client Integration
- Adapter contract · Keeps core semantics client-independent.
src/adapters/base.ts - Client detection
src/adapters/detect.ts - Hook shims · Normalizes client lifecycle payloads.
hooks/run-hook.mjs - Pre-tool routing · Blocks or redirects high-output operations when supported.
hooks/core/routing.mjs - Platform bridge
hooks/platform-bridge.mjs - OpenClaw plugin
src/adapters/openclaw/plugin.ts - Client bundles & manifests
Context Pipeline
- Session event capture · Emits tool and prompt events per project/session.
src/session/event-emit.ts - Session database
src/session/db.ts - Snapshots & directives · Condenses history and reconstructs resume context.
src/session/snapshot.ts - Usage analytics · Derives cost and savings from session state.
src/session/analytics.ts
Knowledge Retrieval
- Project knowledge store · Indexes local content and fetched pages.
src/store.ts - Unified search · Combines search, ranking, snippets, and flood control.
src/search/unified.ts - Fetch cache
src/fetch-cache.ts
Local Platform
- Runtime & DB selection · Selects Bun SQLite, node:sqlite, or better-sqlite3.
src/runtime.ts - Security policy · Applies command, project-boundary, and fetch restrictions.
src/security.ts
Connections 23
- CLI dispatcher → MCP server: starts MCP
- CLI dispatcher → Client detection: selects client
- MCP server → Sandbox executor: runs sandbox tools
- Sandbox executor → Execution pool: uses
- Security policy → Sandbox executor: authorizes commands
- MCP server → Unified search: serves retrieval tools
- MCP server → Snapshots & directives: serves continuity tools
- Client detection → Adapter contract: instantiates
- Adapter contract → Hook shims: registers hooks
- Hook shims → Platform bridge: normalizes payloads
- Hook shims → Pre-tool routing: pre-tool decisions
- Hook shims → Session event capture: captures lifecycle events
- Session event capture → Session database: persists
- Session database → Snapshots & directives: history source
- Snapshots & directives → Session event capture: continuation directive
- Session database → Usage analytics: usage data
- Unified search → Project knowledge store: queries FTS indexes
- Fetch cache → Project knowledge store: cached pages indexed
- Security policy → Fetch cache: hardens fetch targets
- Runtime & DB selection → Session database: provides SQLite backend
- Runtime & DB selection → Project knowledge store: provides SQLite backend
- Client bundles & manifests → Adapter contract: installs client assets
- OpenClaw plugin → Adapter contract: native adapter integration