ContextOS

ContextOS (ctx) is a Codex companion plugin 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.

You can also run without a global install:

npx @minhpnq1807/contextos@latest install

Demo Flow

Use this flow for a 60-second demo recording:

ctx install
codex

Prompt Codex:

kiểm tra flow kiểm duyệt upload

Expected result:

• UserPromptSubmit injects relevant AGENTS.md rules.
• ContextOS suggests upload/moderation 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.
- Check upload moderation flows before editing approval code.

## Suggested files to check
- services/content-service/src/infrastructure/services/content-moderation.service.ts
- webapp/src/features/dashboard/components/moderation-status-badge.tsx

What It Does

• Hooks into Codex UserPromptSubmit, SessionStart, and Stop.
• 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

ctx install does three 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 supported local MCP servers, currently code-review-graph and agentmemory, with a transparent telemetry proxy so tools/call events can be measured.

Restart Codex after installing.

The embedding model is mandatory. ctx install 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 -- "fix upload moderation 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.

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 -- "kiểm tra flow kiểm duyệt upload"

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

Command	Meaning	Use when	Output / side effect
ctx install	Installs ContextOS into Codex with prompt context injection enabled.	Normal setup after installing the npm package.	Copies the plugin into $CODEX_HOME/marketplaces/contextos, registers ctx@contextos, registers ctx-mcp, installs global hooks, downloads the embedding model, and warms caches.
ctx install --quiet	Installs ContextOS in measurement-only mode.	You want reports and stats but do not want a visible hook context block in Codex.	Installs the same plugin/hooks, but prompt hooks return empty additionalContext.
ctx install --inject	Installs ContextOS with explicit injection mode.	You want to be explicit in scripts or docs.	Same runtime behavior as ctx install.
ctx install --copy	Copies only the plugin payload to $CODEX_HOME/plugins/ctx.	Local development or manual plugin experiments.	Does not register marketplace, MCP, or global hooks.
ctx debug -- "task"	Runs the scheduler locally for a fake prompt.	You want to see which AGENTS.md rules and files ContextOS would inject before using Codex.	Prints rule scores, scoring reasons, suggested files, and final additionalContext.
ctx report	Shows the last Stop-hook compliance report for the current workspace.	A Codex task has finished and you want the summary again.	Reads ~/.ctx/contextos/workspaces/<workspace-id>/last-report.json.
ctx evidence	Shows detailed evidence behind the last report for the current workspace.	You want to inspect why a rule was marked followed, ignored, or unknown.	Prints rule text, source file, score, status, and evidence reason.
ctx stats	Shows aggregate runtime metrics for the current workspace.	You want to know whether ContextOS is active and useful over time.	Prints prompt count, report count, injected/quiet ratio, average prompt analysis time, efficiency, rule outcomes, hook events, and last suggested files for the current workspace only.
ctx embeddings warm -- "task"	Prepares local semantic embedding caches.	First install, CI smoke checks, or after changing AGENTS.md/project files.	Loads/downloads Xenova/all-MiniLM-L6-v2 and writes vectors to ~/.ctx/contextos/embeddings.db.
ctx --version	Prints the installed ContextOS CLI version.	You want to confirm which npm version is being executed.	Prints the version from package metadata.

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.

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

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 supported stdio MCP servers with a transparent proxy. The proxy forwards MCP JSON-RPC unchanged, but records tools/call requests such as code-review-graph.detect_changes_tool to workspace telemetry. This is what lets ContextOS prove runtime rules that cannot be seen in git diff.

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":"fix auth validation","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 CLI only.
• 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 Codex.
• 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.