ContextOS

ContextOS (ctx) is an agent companion for task-aware project context.

It reads AGENTS.md guidance, scores the rules against the current prompt, suggests relevant files, records what context would have been injected, and reports lightweight compliance evidence after the task finishes.

Published package: @minhpnq1807/contextos

Quick Start

npm install -g @minhpnq1807/contextos
ctx --version
ctx install

Restart Codex after installing, then use Codex normally. ContextOS runs through Codex hooks and the ctx-mcp MCP server.

Claude Code and Antigravity are supported through their native hook systems:

ctx install claude
ctx install agy

You can also run without a global install:

npx @minhpnq1807/contextos@latest install
npx @minhpnq1807/contextos@latest install claude
npx @minhpnq1807/contextos@latest install agy

Demo Flow

Use this flow for a 60-second demo recording:

ctx install
codex

Prompt the agent:

Recheck authen flow

Expected result:

• UserPromptSubmit injects relevant AGENTS.md rules.
• ContextOS suggests auth/authentication files.
• Stop prints a ContextOS report with rule outcomes.
• ctx evidence shows the specific evidence behind the last report.

Before / After

Without ContextOS, Codex receives the full AGENTS.md context passively and can miss task-relevant rules in large context windows.

With ContextOS, each prompt gets a compact block:

## Critical ContextOS rules
- Use code-review-graph before reading files.
- Recheck authentication flow before editing auth code.

## Suggested files to check
- services/auth-service/src/auth.controller.ts
- services/auth-service/src/auth.service.ts

What It Does

• Hooks into Codex UserPromptSubmit, SessionStart, and Stop.
• Hooks into Claude Code UserPromptSubmit, SessionStart, and Stop.
• Hooks into Antigravity PreInvocation and Stop through the agy adapter.
• Registers a ctx-mcp MCP server that owns model loading and semantic scoring.
• Reads the active AGENTS.md chain for the current workspace.
• Scores rules by relevance to the user prompt.
• Filters host/session setup rules such as "run commands as user X" or sudo -u user because they are environment instructions, not project guidance.
• Finds likely relevant files with a hybrid retriever:
  • first, local prompt/file heuristics create seed candidates;
  • then, if .code-review-graph/graph.db exists, ContextOS queries code-review-graph semantic search and re-ranks graph-backed matches;
  • if no graph exists or graph lookup times out, it falls back to local heuristics.
• Stores scheduled context and hook telemetry per workspace under ~/.ctx/contextos/workspaces/<workspace-id>.
• Reports rule outcomes as followed, ignored, or unknown, using runtime telemetry for tool/command rules when available.
• Injects additionalContext into Codex by default.

By default, ContextOS runs in injection mode. It adds task-relevant rules and files to the model context so the agent has the right project guidance at the moment it starts working.

Install

From the package:

npm install -g @minhpnq1807/contextos
ctx install

Without a global install:

npx @minhpnq1807/contextos@latest install

From this repository during local development:

node bin/ctx.js install

Agent-specific installers:

ctx install codex
ctx install claude
ctx install agy
ctx install --agent codex
ctx install --agent claude
ctx install --agent agy

ctx install defaults to ctx install codex.

Codex

ctx install codex does these things:

1. Copies this package into $CODEX_HOME/marketplaces/contextos.
2. Registers and installs ctx@contextos through Codex plugin marketplace commands.
3. Downloads and caches the required local MiniLM embedding model under ~/.ctx/contextos/models.
4. Warms ~/.ctx/contextos/embeddings.db for AGENTS rules and project file paths.
5. Registers the ctx-mcp MCP server and merges ContextOS global hooks into $CODEX_HOME/hooks.json.
6. Wraps configured local MCP servers, except ContextOS' own ctx-mcp, with a transparent telemetry proxy so tools/call events can be measured. The original MCP command is preserved after the proxy separator and executed unchanged.

Restart Codex after installing.

Claude Code

ctx install claude copies this package into ~/.ctx/contextos/agents/claude/contextos, merges ContextOS hooks into ~/.claude/settings.json, and registers ctx-mcp as a user-scoped Claude Code MCP server in ~/.claude.json.

Claude Code receives prompt context through UserPromptSubmit using hookSpecificOutput.additionalContext, then ContextOS writes the same local workspace report files used by ctx report, ctx evidence, and ctx stats.

Restart Claude Code after installing.

Antigravity

ctx install agy copies this package into ~/.ctx/contextos/agents/agy/contextos, writes a contextos hook group into ~/.gemini/config/hooks.json, and registers ctx-mcp in Antigravity MCP config locations:

~/.gemini/antigravity/mcp_config.json
~/.gemini/antigravity-cli/mcp_config.json
~/.gemini/config/mcp_config.json

The third path supports older Antigravity editor builds where @mcp reads the legacy Gemini config directory.

Antigravity does not use UserPromptSubmit; ContextOS injects context through PreInvocation as an ephemeralMessage. The Stop adapter stores the report locally, so use ctx report or ctx evidence after the task to inspect outcomes.

Restart Antigravity or agy after installing.

The embedding model is mandatory. ctx install checks ~/.ctx/contextos/models first and downloads the MiniLM model only when the required local files are missing. It intentionally fails if the model cannot be prepared, because otherwise the first prompt hook would have to cold-load or download the model.

Verify the published package in any project:

npm exec --yes --package=@minhpnq1807/contextos@latest -- ctx --version
npm exec --yes --package=@minhpnq1807/contextos@latest -- ctx debug -- "Recheck authen flow"

Modes

Injection mode is the default:

ctx install

In injection mode, ContextOS analyzes each prompt, stores runtime data, and returns task-relevant additionalContext to Codex. Codex may display that injected context in the UI.

Quiet mode:

ctx install --quiet

Quiet mode analyzes and measures prompts but returns an empty additionalContext, so Codex does not show a hook context block.

Explicit injection mode is also accepted:

ctx install --inject

Development copy mode:

ctx install --copy

Copies only the plugin payload into $CODEX_HOME/plugins/ctx. This is mostly for local experiments.

Ruler Sync

Use Ruler when the project wants one rule/MCP source of truth for multiple agents:

ctx sync --rules

Default agents are codex, claude, and antigravity. You can target a subset:

ctx sync --rules --agents codex
ctx sync --rules --agents codex,claude

What it does:

1. Checks that ruler is installed. If it is missing, ContextOS asks before running npm install -g @intellectronica/ruler; use --yes for non-interactive installs.
2. Runs ruler init when .ruler/ruler.toml is missing.
3. Adds ctx-mcp to .ruler/ruler.toml under [mcp_servers.ctx-mcp].
4. Imports existing MCP servers from Codex ~/.codex/config.toml and project .mcp.json, such as code-review-graph, agentmemory, and mcp-rtk, into .ruler/ruler.toml.
5. Adds enabled Ruler agent entries for Codex, Claude Code, and Antigravity using merge strategy.
6. Runs ruler apply --agents ....
7. Mirrors the Ruler MCP server list into Antigravity app/CLI MCP configs because current Ruler versions do not emit every Antigravity MCP file consistently.
8. Verifies that generated agent config contains ctx-mcp.

Useful flags:

ctx sync --rules --dry-run
ctx sync --rules --force
ctx sync --rules --yes
ctx sync --rules --no-import-codex-mcp

ctx sync --rules is project-scoped. It writes .ruler/ruler.toml in the current project and lets Ruler generate agent files from that project source of truth. ContextOS runtime history still follows the project-path isolation model described below.

Troubleshooting

ctx-mcp bridge socket not found

Restart Codex after ctx install. The bridge socket is owned by the long-running ctx-mcp MCP server, so it exists only after Codex starts the server.

ContextOS model cache missing

Run:

ctx embeddings warm -- "Recheck authen flow"

Then restart Codex.

No report found

Run at least one Codex task with ContextOS enabled and let the task finish so the Stop hook can write last-report.json.

Average efficiency: unknown

ContextOS only reports efficiency when it has concrete evidence. Diff-based rules are measured from git diff/status. Runtime-only rules, such as tool usage order, are measured from local hook telemetry when Codex exposes tool or command metadata. If neither source proves the outcome, the rule remains unknown.

npm warn deprecated prebuild-install@7.1.3

This warning comes from a transitive dependency in the local embedding/WASM stack. It does not block installation or runtime commands. ContextOS still runs normally if npm exits with code 0.

Commands

Runtime Files

ContextOS writes shared caches to:

~/.ctx/contextos/

Runtime prompt/report files are isolated by workspace:

~/.ctx/contextos/workspaces/<workspace-id>/

Important files:

debug.log                 hook event log
ctx-mcp.sock              private hook bridge owned by ctx-mcp
last-prompt-context.json  latest scheduled context
last-report.json          latest compliance report
prompt-history.jsonl      prompt scheduling history
report-history.jsonl      report history
telemetry.jsonl           local runtime signals from hooks, tools, and commands

The workspace id is stored in the target repo at:

.contextos/workspace.json

ContextOS also adds .contextos/ to the repo .gitignore so the local marker is not pushed. If the marker cannot be written, ContextOS falls back to a deterministic id generated from the workspace real path.

Codex, Claude Code, and Antigravity all write prompt context, reports, evidence, stats, and telemetry through this same workspace id. The same project shares one ContextOS runtime history across agents; different project paths get different workspace directories. Claude Code hooks also use CLAUDE_PROJECT_DIR when the hook payload does not include cwd, and Antigravity uses workspacePath / workspacePaths when present.

These files are local telemetry only. Hooks do not make network calls.

Project Understanding

ContextOS does not try to replace code-review-graph. It uses it as the project-understanding layer when the target repo has already built a graph database.

For file suggestions, ContextOS now runs a local RAG-style retrieval pass:

prompt
  -> UserPromptSubmit hook calls ctx-mcp bridge
  -> ctx-mcp reads AGENTS.md and scores rules with local MiniLM
  -> run file-path embedding search against embeddings.db for semantic file candidates
  -> scan filenames for initial seed candidates
  -> expand candidates through relative import graph links
  -> query code-review-graph semantic_search_nodes with seed entity names
  -> merge graph matches with heuristic matches
  -> inject top suggested files with graph evidence reasons

This keeps the hook fast and local while still using graph semantics when available. The graph search path is visible in runtime data through file reasons such as graph:content-moderation.service.

Configuration:

CONTEXTOS_GRAPH_RETRIEVAL=0       disable graph-backed file retrieval
CONTEXTOS_GRAPH_TIMEOUT_MS=80     graph lookup timeout
CONTEXTOS_CRG_PYTHON=/path/python Python with code_review_graph installed
CONTEXTOS_EMBEDDINGS=0            disable embedding rule scoring
CONTEXTOS_MCP_BRIDGE_TIMEOUT_MS=1000 ctx-mcp hook bridge timeout
CONTEXTOS_EMBEDDING_TIMEOUT_MS=800 embedding scoring timeout inside ctx-mcp/debug
CONTEXTOS_FILE_EMBEDDINGS=0       disable file-path embedding retrieval
CONTEXTOS_FILE_EMBEDDING_TIMEOUT_MS=80 file embedding lookup timeout

Hook Flow

Codex prompt
  -> UserPromptSubmit hook
  -> call ctx-mcp through private bridge
  -> ctx-mcp scores rules and relevant files
  -> write last-prompt-context.json
  -> return additionalContext unless quiet mode is enabled
  -> Codex runs task
  -> Stop hook
  -> read git diff/status
  -> measure rule evidence
  -> write last-report.json and report-history.jsonl

Rule Outcomes

ContextOS uses heuristic evidence collection from git diff/status plus local runtime telemetry.

followed = evidence in the diff suggests the rule was applied
ignored  = evidence in the diff suggests the rule was violated
unknown  = the rule was relevant, but the diff does not prove either way
unmeasurable = ContextOS lacks the required evidence source, such as git diff lines or runtime telemetry

For runtime-only rules, ContextOS also checks telemetry.jsonl for hook-visible tool names, MCP server names, and command metadata. A rule like "use code-review-graph before reading files" can be marked followed when telemetry contains a matching code-review-graph signal.

ctx install wraps configured stdio MCP servers with a transparent proxy. Codex will show node .../proxy.js as the launched command because that is how stdio can be intercepted, but the original MCP command is kept after -- and executed unchanged, including RTK-managed commands. The proxy forwards MCP JSON-RPC unchanged and records tools/call requests such as code-review-graph.detect_changes_tool to workspace telemetry.

Host/session setup rules such as "run shell commands as user X", sudo su - user, sudo -i -u user, and sudo -u user are filtered before scoring. They are not injected and do not count toward unknown outcomes because they describe the agent runtime environment rather than project behavior.

Development

Install dependencies:

npm install

Run tests:

npm test

Run MCP protocol and warm performance smoke:

npm run test:mcp

Validate plugin schema:

npm run validate:plugin

Check the npm package contents:

npm pack --dry-run

Smoke test prompt hook:

printf '%s' '{"prompt":"Recheck authen flow","cwd":"'$PWD'","hook_event_name":"UserPromptSubmit"}' \
  | node plugins/ctx/bin/on-prompt.js

Smoke test Stop hook:

printf '%s' '{"cwd":"'$PWD'","hook_event_name":"Stop"}' \
  | node plugins/ctx/bin/on-stop.js

Project Layout

bin/ctx.js                         CLI
plugins/ctx/hooks.json             plugin hook declaration
plugins/ctx/bin/                   hook entrypoints
plugins/ctx/mcp/server.js          ctx-mcp MCP server and hook bridge
plugins/ctx/lib/reader.js          AGENTS.md reader
plugins/ctx/lib/analyzer.js        rule/file scoring
plugins/ctx/lib/embedding-scorer.js local embedding rule scoring
plugins/ctx/lib/score-context.js   shared MCP scoring pipeline
plugins/ctx/lib/ctx-mcp-client.js  hook bridge client
plugins/ctx/lib/import-graph.js      relative import graph traversal
plugins/ctx/lib/graph-retriever.js code-review-graph retrieval bridge
plugins/ctx/lib/scheduler.js       context layout
plugins/ctx/lib/measure.js         diff-based compliance checks
plugins/ctx/lib/reporter.js        report/evidence formatting
plugins/ctx/lib/stats.js           runtime stats
plugins/ctx/lib/global-hooks.js    Codex global hook installer
test/                              unit tests
contextos-plan.jsx                 implementation plan/reference

Limitations

• Codex and Claude Code get prompt context through additionalContext; Antigravity gets prompt context through PreInvocation ephemeralMessage.
• Antigravity Stop hooks store reports locally, but they do not display the full report inline unless Antigravity adds a non-continuing Stop message surface.
• Local marketplace plugin hooks may not fire reliably in current Codex builds, so ctx install also installs global hooks.
• Injection mode may show a visible hook context block in some agents.
• Quiet mode does not inject context into the model; it only records and measures.
• Compliance is heuristic and mostly based on git diff/status.
• Some rules can only be unknown unless ContextOS records richer telemetry such as tool calls or shell command metadata.