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 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.

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

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
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":"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.