context-mode · diff

v1.0.169 to v1.1.0

66 added, 174 removed. Audit A to A.

---

name: context-mode

description: >

Operate mksglu/context-mode, the Elastic License 2.0 MCP and hook/plugin

system for temporary-script subprocess execution (not an OS/security sandbox),

FTS5 indexing, context-savings telemetry, and session recovery. Use for install, inventory, verification,

diagnosis, or measurement on Claude Code, Codex CLI, Gemini, Copilot, Cursor,

OpenCode, KiloCode, OpenClaw, Pi, OMP, or another listed client. Also triggers

on context-mode, ctx_execute, ctx_search, ctx_doctor, ctx_stats, or MCP/hook

routing for this project.

allowed-tools: Bash Read Write Edit Glob Grep

compatibility: Requires Node.js >=22.5 or Bun for the current package; hook and plugin behavior is host-specific. Configuration and lifecycle writes require explicit approval.

license: Elastic-2.0

metadata:

- version: "1.0.169"

+ version: "1.1.0"

source: https://github.com/mksglu/context-mode

upstream_commit: abb104847cbb66c2182816a72bb69455bc778b5e

---

# Context Mode operator

- `context-mode` is a portable MCP server plus host adapters: large command, file, web,

- and session data stay in subprocesses/SQLite while selected stdout or FTS5 results return.

- It is not an OS/security sandbox, proxy, shell-output wrapper, workspace index, graph, or durable wiki;

- child code can retain normal user filesystem/network authority and can outlive the call when backgrounded.

- This skill is pinned to `abb104847cbb66c2182816a72bb69455bc778b5e` (package/plugin `1.0.169`).

- Hook capture can persist sensitive tool/session output: before enabling it, approve capture scope,

- data sensitivity, storage root/permissions, sharing, retention, and purge policy. Never index secrets,

- credentials, tokens, or private data without an explicit reviewed handling plan.

+ `context-mode` is a portable MCP server plus host adapters. It keeps selected command,

+ file, web, and session data in subprocesses/SQLite, then returns selected output or FTS5

+ results. It is **not** an OS/security sandbox, proxy, shell-output wrapper, workspace index,

+ graph, or durable wiki. Child code retains normal user filesystem/network authority, and a

+ background child can outlive the call.

+ Hook capture and `ctx_search` can retain sensitive tool/session output. Before enabling capture,

+ approve scope, sensitivity, storage root and permissions, sharing, retention, and purge policy.

+ Never index credentials, tokens, secrets, or private data without a reviewed handling plan.

## When to use this skill

- - Audit an install, MCP registration, hook/plugin lifecycle, storage root,

- runtime, duplicate configuration, or session recovery.

- - Plan or perform one explicitly approved install, upgrade, purge, or host config

- change; or measure a fixed workload honestly.

- - Explain supported clients and their hook, native-plugin, or MCP-only limits.

+ - Audit an install, runtime, MCP registration, host adapter, storage root, duplicate entry, or recovery path.

+ - Plan or perform one explicitly approved install, upgrade, purge, hook/config change, or fixed-workload measurement.

+ - Explain host-specific MCP, plugin, hook, routing, and no-hook limits.

## Route out

- - Proxy compression/persistent routing → `headroom`.

+ - Proxy compression or persistent routing → `headroom`.

- Shell output/token wrappers → `rtk`.

- Workspace hybrid/vector/BM25 search → `zvec-grep`.

- Code/corpus graph → `graphify`.

- Durable project memory/wiki → `opencontext` or `llm-wiki`.

- These are catalog entries in this checkout; do not combine their configuration or attribute

- one tool's savings to another.

## Instructions

- ### 1. Freeze target and prerequisites

+ ### 1. Freeze scope and read the right reference

- Record host, OS/architecture, and goal (**inventory**, **MCP-only**,

- **hooks/plugin**, **upgrade**, or **measurement**). Read the pinned package and

- platform matrix, not moving `main`, for version claims.

+ Record host, OS/architecture, and goal: `inventory`, `MCP-only`, `hooks/plugin`, `upgrade`, or

+ `measurement`. Read `references/upstream.md` when the branch needs the pinned runtime/storage

+ rules, host matrix, install commands, tool contract, cross-host postinstall, benchmark claims,

+ or source/license citations. Do not move `main` for version claims.

+ Run the non-mutating helper before any host inspection:

```bash

- node --version

- bun --version || true # optional; do not install it for this check

- if command -v context-mode >/dev/null; then

- context-mode --help

- fi

+ python3 .agent-skills/context-mode/scripts/preflight.py --json

+ python3 "$SKILLS_ROOT/context-mode/scripts/preflight.py" --json

```

- The pinned package requires Node `>=22.5.0`; Bun is supported. Linux Node >=22.5 uses `node:sqlite`,

- Bun uses `bun:sqlite`, and other paths use `better-sqlite3`; older glibc builds may need

- C++20/Make/Python/setuptools. OpenClaw needs Node 22+ and a gateway newer than `2026.1.29`;

- Codex hook behavior needs feature flags. Antigravity IDE and Zed have no hooks.

- ### 2. Inventory read-only before writes

- Inspect only relevant host config; record user/project scope and managed versus unmanaged ownership,

- mask secrets, and do not rewrite JSON/TOML.

- |---|---|---|---|

- `context-mode doctor` is the read-only diagnostic for runtimes, hooks, FTS5, versions, registration,

- and storage. A package/config/binary is not proof that the current session is connected.

- ### 3. Choose one approved install surface

- Never blanket-enable integrations. Installing, changing config, copying routing files, enabling

- hooks/features, adding a status line, or running `upgrade` is a scoped configuration write.

- - **Claude plugin:** `/plugin marketplace add mksglu/context-mode`, then

- `/plugin install context-mode@context-mode`; restart or `/reload-plugins`.

- Marketplace resolution is moving: inspect its resolved revision/version before activation and stop

- if it is not this pin; use the pinned npm MCP-only path when an exact revision cannot be proven.

- It registers 11 tools and six lifecycle hooks. MCP-only has no auto-routing.

- - **Global-package hosts:** after approval, `npm install -g context-mode@1.0.169`, then add only the

- named host's MCP/plugin and hook entries from pinned docs. The pinned `postinstall.mjs` may also

- mutate Claude state under `~/.claude/plugins/installed_plugins.json` and `~/.claude/settings.json`,

- heal cached plugin `mcpServers` args, remove stale cached `.mcp.json`, and create compatibility

- symlinks. Preview/back up those cross-host paths and approve them; do not call this host-local.

- - **OpenCode/KiloCode:** use native `plugin: ["context-mode"]`; do not retain a

- legacy `mcp.context-mode` duplicate without an approved migration.

- - **Codex:** prefer the marketplace plugin. Hooks are inactive until

- `[features].hooks = true` and gated `plugin_hooks = true` are enabled/trusted. Manual fallback is

- global npm plus `config.toml` and `$CODEX_HOME/hooks.json`; PreToolUse can deny but cannot rewrite

- args at this pin, and PreCompact is runtime-gated.

- - **OpenClaw:** `npm run install:openclaw` mutates runtime state and needs

- approval for installer, state directory, native rebuild, and gateway restart.

- - **No-hook clients:** Antigravity IDE and Zed have MCP plus model-guidance files

- only. Cursor rejects `sessionStart`; Kiro lacks `agentSpawn`.

- ### Safety and data boundary

- `ctx_execute` is arbitrary code execution, not a security sandbox: pinned `executor.ts` runs from

- the project root, preserves real `HOME` and most environment variables, and child processes retain

- normal user filesystem/network authority. `background: true` can leave a process running. Require

- explicit approval before arbitrary code, project/user file access, network activity, fetch/index,

- or background processes. `ctx_execute_file` reads a caller-selected file and requires file-access

- approval. Hook capture and `ctx_search` can expose retained sensitive output through a shared

- `CONTEXT_MODE_DIR`; approve scope, permissions, sharing, retention, and purge policy first.

- Never index credentials, tokens, secrets, or private data without a reviewed handling plan.

- ### 4. Know the contract and destructive boundaries

- Pinned `src/server.ts` registers 11 tools: `ctx_execute`, `ctx_execute_file`, `ctx_batch_execute`,

- `ctx_index`, `ctx_search`, `ctx_fetch_and_index`, `ctx_stats`, `ctx_doctor`, `ctx_upgrade`,

- `ctx_purge`, and `ctx_insight`.

+ The first command is for a repository checkout; the second is for an installed skill root.

+ The helper inventories Node/npm/npx/Bun/context-mode paths and host facts without executing

+ those tools or reading Claude/Codex settings, caches, sessions, credentials, or env files.

+ With `--repo PATH`, it may inspect only the public source shape and bounded local Git `HEAD`;

+ `--expect-commit FULL_SHA` requires `--repo` and is the only commit comparison pin.

+ It never invokes context-mode/npm, writes configuration, or makes network calls.

- `ctx_execute` exposes detected JavaScript/TypeScript, Python, Shell, Ruby, Go, Rust, PHP, Perl, R,

- Elixir, and C# runtimes. `ctx_index`/`ctx_search` use SQLite FTS5; `ctx_fetch_and_index` defaults

- to a 24-hour cache (`force: true`/`ttl: 0` refreshes); `ctx_batch_execute` is bounded and indexes

- output. `ctx_purge` permanently deletes indexed content. Session continuity is host-lifecycle-dependent

- (PreToolUse, PostToolUse, compaction, session start), not proof of MCP reachability. Native

- OpenCode/KiloCode tools are in-process. `CONTEXT_MODE_DIR` may set an absolute writable root;

- do not assume clients can safely share a database.

+ JSON output is one object with `skill`, `scope: "offline-preflight"`, `status` (`ok`, `blocked`,

+ or `error`), `checks`, and `runtime_verified: false`. Exit `0` means offline inventory checks

+ passed, `1` means missing or mismatched prerequisites, and `2` means invalid input. A status

+ `ok` is not proof of Node `>=22.5.0`, trusted hooks, host activation, readiness, or savings;

+ runtime versions remain explicitly unverified because the helper never executes host tools.

- `context-mode upgrade`/`ctx_upgrade` may write hooks/settings, migrate storage, repair plugin paths,

- and remove duplicate entries: preview the diff and obtain approval. `statusline` prints only;

- adding it to settings is another write. `ctx_purge` requires separate destructive approval.

+ ### 2. Inventory before writes

- ### 5. Verify in layers and measure honestly

+ Inspect only the relevant host surface, record user/project scope and managed versus unmanaged

+ ownership, mask secrets, and do not rewrite JSON/TOML. A package, config, or binary is not proof

+ that the current session is connected. Never blanket-enable integrations or keep duplicate native

+ plugin and legacy MCP entries without an approved migration.

- After an approved change, restart the named host and: (1) run `context-mode doctor` and record runtime,

- adapter, FTS5, version, and hook/plugin state; (2) check the host listing, verifying Codex hook trust

- separately because `ctx stats` proves MCP reachability, not hook execution; (3) run `ctx stats`; and

- (4) only with explicit code-execution approval, run this fixed no-file/no-network/no-background smoke:

- `ctx_execute(language: "javascript", code: "process.stdout.write(String(2 + 2))", timeout: 1000, background: false)`.

- If recovery matters, test compaction/resume and report partial or unsupported lifecycle events.

+ ### 3. Keep authority and consent explicit

- Do not confuse claims with evidence:

+ `ctx_execute` is arbitrary code execution, not a sandbox: child processes inherit normal user

+ filesystem/network rights. Require explicit approval before code execution, file access, network

+ fetch/index, background processes, hook/config/status-line writes, installs, upgrades, or purge.

+ The pinned npm postinstall can mutate cross-host Claude plugin/settings state, heal cached args,

+ remove stale cache files, and create symlinks; preview/back up and approve those paths as writes.

+ ELv2 permits redistribution only within its terms; substantial hosted/managed feature exposure,

+ license-key circumvention, and removing or obscuring protected notices are prohibited.

- | Statement | Classification |

- |---|---|

- | README says `~98%` with hooks and `~60%` without | upstream claim |

- | `BENCHMARK.md`: 21 scenarios, 376 KB raw → 16.5 KB context (96%) | upstream self-report |

- | Local `ctx_stats` for a fixed workload | observed runtime evidence |

- | Same raw inputs, captured bytes, and hook state before/after | measured local evidence |

+ ### 4. Verify in layers and report honestly

- For local measurement, freeze workload, raw bytes, returned bytes, cache hits, and hook state for both

- runs; report exact commands/session and limitations.

+ After an approved change, restart the named host, run its read-only doctor, inspect host

+ registration, and run `ctx stats` as separate gates. Verify Codex hook trust separately: stats

+ proves MCP reachability, not hook execution. Run the fixed no-file/no-network/no-background

+ JavaScript smoke only with code-execution approval. For measurements, freeze identical raw input,

+ returned bytes, cache hits, and hook state; label upstream claims separately from observed evidence.

## Examples

- ### Read-only inventory

+ ### Offline preflight

```bash

- if command -v context-mode >/dev/null; then

- context-mode --help

- context-mode doctor

- else

- echo "context-mode is not installed"

- fi

- ```

- Stop after recording output; do not call `upgrade` or edit hooks because a binary exists.

- ### Approved Claude plugin

- ```text

- /plugin marketplace add mksglu/context-mode

- /plugin install context-mode@context-mode

- # restart, then /context-mode:ctx-doctor

+ python3 .agent-skills/context-mode/scripts/preflight.py --json

```

- ### Approved MCP-only trial

+ ### Source checkout and caller-supplied pin

```bash

- claude mcp add context-mode -- npx -y context-mode@1.0.169

+ python3 .agent-skills/context-mode/scripts/preflight.py --repo /path/to/context-mode --expect-commit FULL_SHA --json

```

- This omits hooks and slash commands, so routing is not automatically enforced.

+ The helper reports unverified runtime versions honestly; it does not turn a path or package

+ presence into a readiness claim.

## Best practices

- - Keep one host, one install surface, and one hook owner; duplicate plugin/MCP

- entries are a known failure mode.

- - Use `doctor`, host listing, and session smoke as separate gates.

- - Treat routing files as guidance and hooks as enforcement; no-hook hosts lack the

- latter. Keep `CONTEXT_MODE_DIR` absolute, writable, and isolated.

- - Before hooks/capture, define retention, purge, permissions, and sharing; never index secrets,

- credentials, tokens, or private data without an approved handling plan.

- - Require scoped approval for installs, upgrades, hook/config writes, status-line

- edits, and purge. Never silently enable integrations.

- - Attribute savings to fixed-workload/`ctx_stats` evidence, never to badges,

- package versions, or a successful MCP handshake.

+ - Keep one host, one install surface, and one hook owner; duplicate registration is a known failure mode.

+ - Keep `CONTEXT_MODE_DIR` absolute, writable, and isolated; define capture retention and purge before hooks.

+ - Use doctor, host registration, session smoke, and measurement as separate evidence gates.

+ - Attribute savings only to a fixed workload with captured bytes and hook state, never to badges or handshakes.

+ - Keep host-specific commands and all pinned citations in [`references/upstream.md`](references/upstream.md).

## References

- Pinned to `abb104847cbb66c2182816a72bb69455bc778b5e`:

- - [README install matrix, commands, tools, benchmarks](https://github.com/mksglu/context-mode/blob/abb104847cbb66c2182816a72bb69455bc778b5e/README.md)

- - [Package metadata and engines](https://github.com/mksglu/context-mode/blob/abb104847cbb66c2182816a72bb69455bc778b5e/package.json)

- - [CLI and hook dispatch](https://github.com/mksglu/context-mode/blob/abb104847cbb66c2182816a72bb69455bc778b5e/src/cli.ts)

- - [MCP tools and storage](https://github.com/mksglu/context-mode/blob/abb104847cbb66c2182816a72bb69455bc778b5e/src/server.ts)

- - [Platform matrix](https://github.com/mksglu/context-mode/blob/abb104847cbb66c2182816a72bb69455bc778b5e/docs/platform-support.md)

- - [Claude routing](https://github.com/mksglu/context-mode/blob/abb104847cbb66c2182816a72bb69455bc778b5e/configs/claude-code/CLAUDE.md)

- - [Codex routing](https://github.com/mksglu/context-mode/blob/abb104847cbb66c2182816a72bb69455bc778b5e/configs/codex/AGENTS.md)

- - [Benchmark methodology](https://github.com/mksglu/context-mode/blob/abb104847cbb66c2182816a72bb69455bc778b5e/BENCHMARK.md)

- - [Elastic License 2.0](https://github.com/mksglu/context-mode/blob/abb104847cbb66c2182816a72bb69455bc778b5e/LICENSE)

- - [Postinstall and cross-host self-healing](https://github.com/mksglu/context-mode/blob/abb104847cbb66c2182816a72bb69455bc778b5e/scripts/postinstall.mjs)

- GitHub's API reports `Other`/`NOASSERTION`; the pinned `LICENSE` identifies Elastic License 2.0 (ELv2).

- Redistribution is licensed subject to ELv2 terms, but a hosted/managed service exposing a substantial

- set of features is prohibited; license-key circumvention and removing or obscuring protected

- functionality/notices are also prohibited. Check the full license before redistribution or hosting.

+ - [`references/upstream.md`](references/upstream.md) — pinned host matrix, install/tool/storage/version contract, safety boundaries, commands, benchmark classification, ELv2 notes, and source citations.

+ - Upstream commit: `abb104847cbb66c2182816a72bb69455bc778b5e` (package/plugin `1.0.169`).