context-mode

Executes code in isolated subprocess sandboxes across 11 languages (Python, Node.js, Bash, Go, Rust, Java, C++, C#, Ruby, PHP, Kotlin) using runtime detection and language-specific execution pipelines. Only stdout is captured and returned to the context window, filtering stderr and side effects. The PolyglotExecutor spawns isolated processes, manages lifecycle, and enforces execution timeouts, reducing context bloat from 56 KB (raw output) to 299 B (filtered stdout).

Indexes code, documentation, and tool output into a SQLite FTS5 (Full-Text Search 5) database with BM25 ranking. The ContentStore abstracts indexing and retrieval, allowing agents to search indexed content via ctx_search and ctx_fetch_and_index tools. Search results are ranked by relevance and truncated to snippets, keeping retrieved data small (40 B vs. 60 KB raw). Supports incremental indexing and session-aware knowledge partitioning.

The security architecture includes configurable policies that filter or block tool calls based on rules (e.g., block execution of certain commands, restrict file access to specific directories, limit execution timeout). Policies are defined in platform-specific configuration files and enforced by the PreToolUse hook. Policy evaluation is synchronous and happens before tool execution. Policies support allow-lists (whitelist commands), deny-lists (blacklist commands), and resource limits (timeout, memory, file size).

The system tracks context window usage across tool calls and sessions, reporting metrics like total tokens consumed, context reduction percentage (98% claimed), and per-tool overhead. Analytics are collected via the event system and aggregated by ctx_stats. Reports show which tools consume the most context (before filtering) and how much context is saved by sandboxing and knowledge base queries. Enables data-driven optimization of tool usage and context management strategies.

Captures AI agent actions (tool calls, code edits, decisions) into a SessionDB (persistent SQLite store) as events. When the context window fills and compaction occurs, the PreCompact hook builds a priority-tiered snapshot of critical state (active files, pending tasks, resolved errors, user intent). On session resume, SessionStart hook restores the snapshot, allowing the agent to continue work without re-explaining context. Event system tracks file modifications, tool invocations, and decision points across session boundaries.

Provides four lifecycle hooks (PreToolUse, PostToolUse, PreCompact, SessionStart) that intercept AI agent execution at key points. Hooks are registered as TypeScript functions in platform-specific configurations and execute synchronously before/after tool invocations or session events. PreToolUse can filter or modify tool inputs; PostToolUse extracts structured data from tool outputs; PreCompact builds snapshots; SessionStart restores state. Hooks enable custom filtering, logging, and state management without modifying core MCP tools.

Abstracts platform-specific integration details (Claude Code, Gemini CLI, VS Code Copilot, Cursor, OpenCode, Codex CLI) behind a unified adapter interface. Each platform adapter handles hook registration, configuration file parsing, and MCP server lifecycle. Runtime platform detection identifies the active AI platform and loads the appropriate adapter. Adapters expose platform-specific features (e.g., Claude Code's plugin API, Cursor's native integration) while maintaining a consistent MCP tool interface across all platforms.

The ctx_batch_execute tool accepts a list of code snippets with optional dependency declarations and executes them in topologically-sorted order. Dependencies are resolved to ensure snippets that depend on earlier outputs execute after their dependencies complete. Execution is atomic per batch; if a dependency fails, dependent snippets are skipped. Output from each snippet is captured separately and returned as an array, allowing agents to run multi-step workflows (e.g., install dependencies, run tests, deploy) in a single tool call.

The ctx_execute_file tool executes code from a file path with working directory context preserved. The executor resolves the file path relative to the session's working directory, executes the code in that context, and captures stdout. This enables agents to run scripts that depend on relative imports, environment variables, or file system state without manually setting up context. Supports shebang-based language detection (#!/usr/bin/env python) and explicit language specification.

The ctx_index tool indexes files or directories into the FTS5 knowledge base, and ctx_fetch_and_index combines fetching remote content (e.g., GitHub issues, API responses) with indexing. Indexing is incremental; only new or modified files are re-indexed. The ContentStore tracks file modification times and skips unchanged files. Indexed content is partitioned by session, allowing multi-session knowledge reuse without context pollution. Supports batch indexing of large directories with progress tracking.

The ctx_search tool queries the FTS5 knowledge base using BM25 ranking and returns the top-K results as truncated snippets. Search is lexical (keyword-based), not semantic; results are ranked by term frequency and inverse document frequency. Snippets are truncated to 200-500 characters to keep retrieved data small. Search results include file paths, line numbers, and relevance scores, enabling agents to navigate to relevant code without loading full files. Supports filtering by file type or directory.

The ctx_doctor tool performs system diagnostics (checks MCP server health, hook registration, platform detection, file permissions, database integrity). The ctx_stats tool reports index size, session count, event count, and memory usage. The ctx_upgrade tool updates context-mode to the latest version and migrates database schemas. These tools enable operators to monitor system health, troubleshoot integration issues, and maintain the MCP server without manual inspection.