context-mode

Executes code in isolated subprocess environments across 11 languages (Python, Node.js, Go, Rust, Java, C++, C#, Ruby, PHP, Bash, Deno) using PolyglotExecutor runtime detection. Only stdout is captured and returned to context; stderr, logs, and intermediate state remain sandboxed. Implements intent-driven filtering to reduce 56 KB Playwright snapshots to 299 B (99% reduction) by extracting only semantically relevant output lines rather than raw dumps.

Indexes arbitrary content (code files, documentation, API responses, logs) into a SQLite FTS5 (Full-Text Search 5) database with BM25 relevance ranking. Agents query the knowledge base via ctx_search to retrieve semantically relevant snippets (40 B average) instead of dumping entire 60 KB documents into context. Supports incremental indexing via ctx_index and batch fetch-and-index via ctx_fetch_and_index for GitHub issues, API responses, and file trees.

Provides ctx_doctor CLI command that runs comprehensive health checks on the context-mode installation, session database, knowledge base, and platform adapters. Checks include: verifying SQLite database integrity, validating hook registration with the platform, checking for orphaned sessions, detecting corrupted index entries, and verifying language runtime availability. For detected issues, ctx_doctor suggests remediation steps (e.g., 'run ctx_upgrade to fix schema version mismatch') or automatically applies fixes (e.g., removing orphaned sessions).

Implements a hook system that intercepts agent execution at four lifecycle points: PreToolUse (before tool execution), PostToolUse (after tool execution), PreCompact (before context compaction), and SessionStart (at session initialization). Each hook receives event data (tool call, tool output, context state) and can mutate state (filter output, inject snapshots, modify directives). PostToolUse hook includes event extraction logic that parses tool output and extracts semantic events (file edited, test passed, error resolved) for session continuity. Hooks are registered per-platform and can be chained (multiple hooks per lifecycle point).

Captures tool calls, code edits, and agent decisions into a SessionDB (persistent SQLite store) as timestamped events. When context window fills and compaction occurs, the PreCompact hook builds a priority-tiered snapshot (recent edits > active files > task state > resolved errors) that is restored at SessionStart, preserving working memory across context resets. Snapshots are serialized as structured directives that guide the agent to resume from the last known state without re-explaining context.

Provides platform-specific adapters for Claude Code, Gemini CLI, VS Code Copilot, Cursor, OpenCode, and Codex CLI. Each adapter implements the MCP server protocol and registers hooks (PreToolUse, PostToolUse, PreCompact, SessionStart) that intercept agent execution at key lifecycle points. Hooks allow context-mode to filter tool output before it enters the context window, extract events for session continuity, and inject snapshots at session start without modifying the underlying AI platform.

Executes multiple code snippets or files in sequence via ctx_batch_execute, with per-item error handling and optional retry logic. If one item fails, subsequent items continue executing (fail-fast disabled by default). Captures exit codes, stdout, and error messages for each item, allowing agents to identify which operations succeeded and which failed without stopping the entire batch. Useful for running test suites, migrations, or multi-step setup scripts where partial success is acceptable.

Executes code from files (ctx_execute_file) with automatic dependency resolution and working directory context. Detects the file's language, resolves imports/requires, and executes in the file's directory so relative paths and local dependencies work correctly. Supports executing partial file ranges (e.g., a single function or test case) without running the entire file, useful for testing individual components without side effects from module-level code.

Indexes arbitrary content (code files, documentation, API responses, logs) into the FTS5 knowledge base via ctx_index. Supports incremental updates — new content is added without re-indexing existing content. Automatically detects content type (code, markdown, JSON, plain text) and applies language-specific tokenization (e.g., camelCase splitting for code identifiers). Provides ctx_fetch_and_index for batch-indexing external content (GitHub issues, API docs, file trees) with automatic deduplication.

Provides ctx_stats and ctx_doctor tools that analyze context window usage and identify optimization opportunities. ctx_stats reports current session size (tokens, characters), breakdown by message type (code, conversation, tool output), and identifies the largest context consumers. ctx_doctor runs diagnostics (checks for unindexed large files, suggests content to move to knowledge base, identifies inefficient tool calls) and recommends optimizations (e.g., 'index this 50 KB file to save 49 KB context'). Helps agents and developers understand where context is being consumed and how to optimize.

Implements a security architecture that enforces configurable policies on code execution, file access, and tool usage. Policies are defined in a configuration file and include restrictions like 'allow only read-only file operations', 'block execution of shell scripts', 'restrict network access to whitelisted domains'. The PreToolUse hook intercepts tool calls and checks them against policies before execution, blocking disallowed operations. Supports role-based policies (e.g., 'agent' role has fewer permissions than 'user' role) and audit logging of all policy violations.

Provides ctx_upgrade and upgrade CLI command that migrates context-mode installations and session databases to new versions. Handles schema migrations (e.g., adding new columns to SessionDB), data transformations (e.g., re-indexing content with new tokenization), and compatibility checks (e.g., verifying that the platform adapter supports the new version). Allows users to upgrade without losing session history or knowledge base content.