ContextOS

Same prompt. Same model. Different context.

ContextOS stops coding agents from ignoring repo rules, guessing the wrong path, and reading random files.

Prompt:
Fix deployment

Raw Agent:
❌ Vercel
❌ Docker
❌ Railway

ContextOS:
✅ EAS
✅ Mobile Deployment
✅ GitHub Actions

ContextOS reads the repo before the agent starts: project rules, repo evidence, suggested files, skills, workflows, and post-task proof.

Published package: @minhpnq1807/contextos

Hallucination Leaderboard

Offline deterministic benchmark:

System	Correct context choice
Raw heuristic baseline	10.0%
ContextOS evidence benchmark	80.0%

ctx leaderboard --hallucination

This means ContextOS improves deterministic context routing from 10% to 80% on the offline hallucination task set. It does not claim ContextOS beats Codex, Gemini, Claude Code, or Cursor in live runs.

Live agent benchmark support exists, but results are pending an external environment with working CLI auth/session access:

ctx leaderboard --hallucination --live --agent codex
ctx leaderboard --hallucination --live --agent gemini

If a CLI cannot run in the current environment, the command reports SKIPPED or an agent error instead of blocking launch.

Live benchmark tracking:

• Run Codex live benchmark
• Run Claude Code live benchmark
• Run Gemini CLI live benchmark
• Run Cursor live benchmark

Why People Star ContextOS

• Agents ignore AGENTS.md.
• Agents choose the wrong deployment path.
• Agents grep random files before understanding the repo.
• ContextOS fixes all three before coding starts.

Demo

ctx skills doctor -- "fix deployed"

Repo evidence	What ContextOS tells the agent
eas.json, expo, react-native	eas, mobile-deployment, github-actions-ci-cd
vercel.json, next, GitHub workflow	vercel-deployment, github-actions-ci-cd, env-secret-management
ContextOS repo with no app deploy evidence	no deployment skill selected

More 10-second demo:

Demo	GIF
AGENTS.md Lost In The Middle	docs/demo/agents-lost-middle.gif

What The Agent Sees

ContextOS injects a compact brief before the agent works:

## Critical ContextOS rules
- IMPORTANT: This project has a knowledge graph. Use it before broad file search.
- Use `query_graph` pattern="tests_for" to check coverage.

## Suggested files to check
- services/content-service/test/unit/creator-only.policy.unit-spec.ts
- services/content-service/test/integration/resource-upload.integration-spec.ts

## Suggested workflow for this task
- Primary Workflow: use for feature implementation, testing, review, and debugging
  chain: planner -> tester -> code-reviewer

After the task:

ContextOS report
Efficiency: 100%
Injected rules: 8
Rule outcomes: 8 followed, 0 ignored, 0 unknown
Runtime evidence: project graph was used before file search

Regenerate the GIFs from real local ctx command output:

npm run demo:capture

Internal Benchmark

Skill selection fixture benchmark:

Metric	Result
Cases	52
Top-1 Accuracy	94.2%
Top-3 Recall	94.2%
False Positive Rate	0.0%
Confidence Calibration	100.0%
Negative Gate Accuracy	100.0%

This is an internal fixture benchmark, not an external real-world benchmark. It is designed to prove that ContextOS changes its suggestions from repo evidence across controlled Expo/EAS, Next/Vercel, Docker, Railway/Render, Firebase, auth, database, testing, mobile, and adversarial negative cases.

Quick Install

Install in 30 seconds:

npm install -g @minhpnq1807/contextos
ctx setup

No postinstall surprise: npm install only installs the CLI. Setup runs only when you call ctx setup.

Scriptable setup:

ctx setup --yes
ctx setup --yes --agents codex,claude,agy
ctx setup --yes --generate-project-context

If ctx doctor reports missing project skills/workflows, generate starter project context explicitly:

ctx doctor --fix

No global install:

npm exec --yes --package=@minhpnq1807/contextos@latest -- ctx setup
npm exec --yes --package=@minhpnq1807/contextos@latest -- ctx-codex install

Codex-only:

ctx install

Claude Code and Antigravity:

ctx install claude
ctx install agy

Restart the agent after setup. Then use the agent normally.

What ContextOS Does

Agent failure	ContextOS behavior
Ignores project rules	Shows the relevant rules at the start of the task.
Picks the wrong tool or deployment path	Suggests skills only when the repo has supporting evidence.
Reads random files first	Suggests the likely files and workflows before exploration starts.
Claims compliance without proof	Reports which rules were followed, ignored, or unknown after the task.
Needs to work across agents	Supports Codex, Claude Code, and Antigravity with the same project context.

Comparison

Approach	What it gives the agent	Main gap
Plain AGENTS.md	Static repo instructions.	Important rules get buried or ignored when the task changes.
Generic RAG	Related files or snippets.	It usually does not choose skills/workflows or prove rule compliance.
ContextOS	Task-specific rules, files, skills, workflows, and evidence.	Requires local setup and prepared indexes for best results.

Safety Model

ContextOS is designed to be OSS-friendly and low-friction:

Guarantee	Behavior
Standalone by default	ctx setup works without code-review-graph, codegraph, or agent-memory.
Optional adapters	Graph and memory backends add signal when available; missing adapters contribute score 0.
Fail-open hooks	Prompt hooks return local context or nothing instead of blocking the agent when optional runtime pieces are unavailable.
Local-only telemetry	Reports, prompt history, evidence, and telemetry stay under ~/.ctx/contextos/.
No hook network calls	Prompt and stop hooks do not call external services. Install/warm commands may prepare local indexes when explicitly run.
No postinstall surprise	npm install only installs the CLI. Setup runs only when you call ctx setup.

Positioning: ContextOS works standalone and gets smarter when project graph or memory adapters are available.

Roadmap

ContextOS is not heading toward a dashboard-first product. The next work is focused on making the existing local behavior more visible and reusable:

Next	Why
Hallucination Leaderboard	Compare raw agent guesses vs ContextOS evidence-based recommendations across the same repos and tasks.
Agent Replay	Turn telemetry into a readable post-task narrative: prompt, selected skills, followed rules, suggested files, touched files, efficiency.
Community Skill Packs	Let contributors PR ContextOS-ready skills with triggers, evidence, negative gates, and workflows before building a larger hub.
ContextOS Ready	Define a repository readiness badge for AGENTS.md, skills, workflows, and evidence quality.
Auto Skill Extraction	Research ctx skill generate so ContextOS can detect reusable skills from a repo and propose publishable skill packs.

See docs/roadmap.md for the current roadmap notes.

Community Skill Packs

ContextOS starts the community loop with community-skills/ instead of a hosted marketplace. The seed packs are eas, vercel, prisma, redis, oauth-google, and jwt-auth.

Each pack contains a model-visible SKILL.md plus skill.yaml metadata with prompt triggers, project evidence, negative triggers, and a short workflow. Contributors can PR new packs by copying community-skills/_template/.

ContextOS Ready

ctx doctor scores whether a repository is ready for ContextOS-style agent guidance:

ctx doctor

Repository Score

Rules: 92
Skill Coverage: 88
Project Skill Overrides: 0
Workflows: 84

Overall:
ContextOS Ready Silver

The score checks project AGENTS.md rules, global/community skill coverage, optional project skill overrides, and project workflows. Shared project context should live under .agents/skills/ and .agents/workflows/; ContextOS can sync it to Codex, Claude Code, Gemini, and Antigravity agent roots. Use the badge only after ctx doctor reports Bronze, Silver, or Gold.

Quick Commands

Command	Use it for
ctx setup	Recommended first-run install flow.
ctx debug -- "Recheck authen flow"	Preview what ContextOS would inject.
ctx doctor	Score repository readiness for the ContextOS Ready badge.
ctx doctor --fix	Generate starter project skills and workflow when the repo is missing them.
ctx report	Show the last task's compliance summary.
ctx evidence	Show why each rule was marked followed/ignored/unknown.
ctx stats	Show workspace-level usage and effectiveness metrics.
ctx benchmark -- "task"	Compare raw AGENTS.md ordering vs ContextOS scheduling.
ctx benchmark --skills	Run the skill selection eval benchmark.
ctx leaderboard --hallucination	Run the offline deterministic hallucination benchmark.
ctx leaderboard --hallucination --live --agent codex	Run the live CLI benchmark when agent auth/session is available.
ctx leaderboard --agents codex,gemini	Legacy live CLI leaderboard form.
ctx sync --rules	Sync project rules across agents.
ctx sync --skills	Sync skills across agents through skillshare.
ctx sync --workflows	Sync workflow markdown across Claude/Codex/Antigravity.

60-Second Demo Script

1. Start in a repo with an AGENTS.md that contains a rule like:

Always use the project graph before reading files.

2. Install:

npm install -g @minhpnq1807/contextos
ctx setup --yes --agents codex

3. Restart Codex and submit:

Recheck authen flow

4. Show the injected hook context.

5. Let the task finish, then run:

ctx report
ctx evidence

The demo should show one idea: ContextOS puts the right rule in front of the agent before work starts, then proves whether the rule was followed.

Detailed 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.
7. Detects available project graph backends and prints the selected strategy. code-review-graph is active today; detected codegraph backends are reported as adapter-pending until the integration contract is implemented.
8. Refreshes local code-review-graph node embeddings when the project already has .code-review-graph/graph.db. This is best-effort: install still succeeds when the graph runtime is unavailable.

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.

ContextOS keeps the embedding model hot inside ctx-mcp. Prompt hooks never cold-load transformers; if the MCP bridge is unavailable or the model is still warming, hooks fail open with lightweight scoring. Current local smoke metrics:

MCP warm p95: 15-58ms observed
Hook lightweight fallback: 0.69s
MCP embedding hot startup: 477ms

Agents can call read-only ContextOS MCP tools directly:

ctx_health
ctx_score_context
ctx_debug_context
ctx_doctor_repo
ctx_skills_doctor
ctx_report_last_task
ctx_evidence_last_task
ctx_stats_workspace

Write commands such as ctx setup, ctx install, ctx refresh, and ctx sync are not exposed as MCP tools by default.

During install, ContextOS prints a 0-100 progress indicator. The longest stage is usually embedding warmup; if the model is already cached, install skips the download and only refreshes vectors.

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"

Skill Sync

Use skillshare when you want Codex, Claude Code, and Antigravity to share one skills catalog:

ctx sync --skills

ContextOS checks for skillshare, initializes it when needed, backs up existing skills before collection, runs skillshare collect --all unless --no-collect is provided, then runs skillshare sync. After sync, ContextOS rebuilds skill embeddings so prompt-time skill discovery can rank the shared source immediately.

The shared source is:

~/.config/skillshare/skills/

Useful variants:

ctx sync --skills --dry-run
ctx sync --skills --no-collect
ctx sync --skills --no-embeddings
ctx sync --skills --verbose
ctx sync --skills --agents codex,claude
ctx sync --skills --agents codex,claude,agy

After this, ctx debug -- "task" and prompt hooks can suggest skills from ~/.config/skillshare/skills/ plus agent-specific skill folders.

Workflow Discovery

ContextOS can also sync Claude/Codex/Antigravity workflow markdown files and suggest the right workflow for the current task:

ctx sync --workflows
ctx sync --workflows --agents codex,claude,agy
ctx sync --workflows --dry-run

It scans project workflows first, then global workflows:

.claude/workflows/
.codex/workflows/
.gemini/workflows/
.gemini/antigravity/workflows/
.gemini/antigravity-cli/workflows/
~/.claude/workflows/
~/.codex/workflows/
~/.gemini/workflows/
~/.gemini/antigravity/workflows/
~/.gemini/antigravity-cli/workflows/

Workflow files do not need YAML frontmatter. ContextOS reads the top # heading, section headings, and referenced agent names such as planner, tester, code-reviewer, and docs-manager, then warms semantic embeddings. Prompt hooks inject a Suggested workflow for this task section only when a workflow is relevant enough.

ctx sync --workflows reads every known project/global workflow root, keeps the first workflow for each filename/name according to root priority, then copies that unique set to the selected global agent roots. This prevents duplicate primary-workflow suggestions when the same workflow exists in Claude, Codex, and Antigravity directories.

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 agy (Antigravity). Ruler's official identifier is still antigravity, so ContextOS accepts both agy and antigravity and normalizes them before calling Ruler. You can target a subset:

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

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.

Upstream Passthrough

ContextOS exposes thin passthrough commands for Ruler and skillshare admin/debug workflows:

ctx ruler -- apply --agents codex,claude,antigravity
ctx ruler -- init
ctx skillshare -- status
ctx skillshare -- target list
ctx skillshare -- doctor

Everything after -- is forwarded unchanged to the upstream CLI. ContextOS does not reinterpret those args, and it preserves the upstream output and exit status. Use ctx sync --rules and ctx sync --skills for ContextOS-managed workflows; use passthrough when you need a native Ruler or skillshare command.

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 [email protected]

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 Codex setup after installing the npm package.	Same as ctx install codex. Standard installs sync the active Codex marketplace, rebuild file/import indexes, and refresh code-review-graph embeddings when available.
ctx install codex	Installs ContextOS into Codex.	You use the codex CLI.	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 claude	Installs ContextOS into Claude Code.	You use the claude CLI.	Copies a stable package root to ~/.ctx/contextos/agents/claude/contextos, merges hooks into ~/.claude/settings.json, and registers ctx-mcp in ~/.claude.json.
ctx install agy	Installs ContextOS into Antigravity.	You use the agy CLI or Antigravity app/editor.	Copies a stable package root to ~/.ctx/contextos/agents/agy/contextos, writes hooks to ~/.gemini/config/hooks.json, and registers ctx-mcp in Antigravity app, CLI, and legacy editor MCP config paths.
ctx install --agent <name>	Installs for a named agent.	You prefer explicit scripts.	Accepts codex, claude, or agy.
ctx install --quiet	Installs ContextOS in measurement-only mode.	You want reports and stats but do not want visible injected context.	Installs the same hooks, but prompt hooks return empty context.
ctx install --inject	Installs ContextOS with explicit injection mode.	You want to be explicit in scripts or docs.	Same runtime behavior as the default install mode; if combined with --quiet, --inject wins.
ctx install --copy	Copies only the plugin payload to $CODEX_HOME/plugins/ctx.	Legacy local development or manual plugin experiments.	Does not sync the active marketplace, rebuild indexes, register MCP, or install global hooks. Prefer ctx refresh for active local updates.
ctx setup	Runs the first-run setup wizard.	You want the recommended onboarding flow after npm install -g @minhpnq1807/contextos.	Installs selected agents, optionally syncs Ruler rules/MCP and skillshare skills, asks which prompt sections to show, then prints next steps.
ctx setup --yes	Runs setup with defaults non-interactively.	You want scriptable Codex setup.	Uses codex, enables injection, syncs rules, syncs skills, skips interactive community-skill installation when no TTY is available, and passes --yes to dependency setup prompts. Use --agents codex,claude,agy for multi-agent setup.
ctx setup --generate-project-context	Generates starter shared project skills and workflow during setup.	Your repo has rules but ctx doctor reports missing skills/workflows.	Creates .agents/skills/<detected-skill>/SKILL.md, matching skill.yaml, and .agents/workflows/primary.md without overwriting existing files. Run ctx sync --skills and ctx sync --workflows to push them to selected agents.
ctx setup --agents <list>	Runs setup for selected agents.	You want only part of the default set.	Accepts comma-separated codex, claude, agy, or antigravity.
ctx setup --no-rules	Skips Ruler sync during setup.	You only want hooks/MCP install and maybe skill sync.	Does not run ctx sync --rules.
ctx setup --no-skills	Skips skillshare sync during setup.	You do not want shared skills configured.	Does not run ctx sync --skills.
ctx setup --quiet	Runs setup in measurement-only mode.	You want reports/stats without visible injected prompt context.	Installs hooks with prompt context injection disabled.
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 health	Checks local ctx-mcp bridge/model/index readiness.	Hooks are falling back or suggestions look stale.	Prints bridge connection, model hot status, and whether local indexes exist.
ctx doctor	Scores repository ContextOS readiness.	You want to add or verify a ContextOS Ready badge.	Prints Rules, Skills, Workflows, Overall tier, evidence, and next recommendations.
ctx doctor --fix	Generates starter ContextOS project context.	ctx doctor says skills/workflows are missing and you want explicit local scaffolding.	Detects package/config evidence, creates up to three shared project skills plus .agents/workflows/primary.md, then prints the updated readiness score.
ctx report	Shows the last Stop-hook compliance report for the current workspace.	An agent task has finished and you want the summary again.	Prints sectioned tables for summary, rule outcomes, suggested files, and runtime telemetry from ~/.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, unknown, or unmeasurable.	Prints a compact evidence table plus per-rule detail tables.
ctx stats	Shows aggregate runtime metrics for the current workspace.	You want to know whether ContextOS is active and useful over time.	Prints sectioned tables for prompt/report counts, injection rate, efficiency, rule outcomes, hook events, last prompt, and last report.
ctx benchmark -- "task"	Compares baseline AGENTS.md ordering with ContextOS task-aware scheduling.	You want a before/after signal for lost-in-the-middle risk.	Prints tables for parsed/actionable/filtered rules, baseline middle-risk, scheduled high/mid rules, recency reminder status, and top scored rules.
ctx benchmark --skills	Runs the Skill Router eval benchmark.	You want evidence for skill routing accuracy and negative gates.	Prints top-1 accuracy, top-3 recall, false positive rate, confidence calibration, and negative gate accuracy across eval/skill-routing fixtures.
ctx leaderboard --hallucination	Runs the offline deterministic hallucination benchmark.	You want launch evidence for the wrong-context problem without depending on external agent auth.	Runs 20 fixture tasks across 10+ repo contexts and prints Raw heuristic baseline vs ContextOS evidence benchmark plus sample failures.
ctx leaderboard --hallucination --live --agent codex	Runs the hallucination benchmark through one installed agent CLI.	You want real agent output and have CLI auth/session available.	Calls the selected CLI with timeouts; missing, blocked, or unauthenticated CLIs are reported as skipped/errors instead of blocking.
ctx leaderboard --agents codex,gemini	Legacy live CLI leaderboard form.	You want to run multiple live agents at once.	Equivalent live-agent benchmark shape for comma-separated CLIs.
ctx sync --rules	Syncs project rules and MCP servers through Ruler.	You want Codex, Claude Code, and Antigravity to share one project rule/MCP source of truth.	Ensures .ruler/ruler.toml, injects ctx-mcp, imports existing MCP servers from Codex and project .mcp.json, runs ruler apply --agents codex,claude,antigravity, mirrors MCP servers to Antigravity MCP configs, and verifies generated config.
ctx sync --rules --agents <list>	Syncs only selected agents through Ruler.	You want to update one or two agents without touching the others.	Accepts comma-separated values such as codex, claude, agy, antigravity, or codex,claude,agy; agy is normalized to Ruler's antigravity.
ctx sync --rules --dry-run	Previews Ruler sync without writing files or running apply.	You want to inspect behavior before changing project config.	Prints the same flow with dry-run status.
ctx sync --rules --force	Rewrites ContextOS-owned Ruler sections.	You changed the ContextOS install path or need to refresh ctx-mcp.	Removes and re-adds ContextOS-owned mcp, mcp_servers.ctx-mcp, and selected agent sections.
ctx sync --rules --no-import-codex-mcp	Skips Codex MCP import.	You only want ContextOS' own ctx-mcp in Ruler.	Does not read ~/.codex/config.toml.
ctx sync --skills	Syncs agent skills through skillshare.	You want Codex, Claude Code, and Antigravity to share one skill source.	Installs or verifies skillshare, initializes it if needed, backs up and collects existing skills unless skipped, runs skillshare sync, and rebuilds ContextOS skill embeddings.
ctx sync --skills --agents <list>	Syncs skills only for selected agents.	You want to target a subset such as codex,claude or codex,claude,agy.	Runs skillshare sync --agents <list> with agy normalized to antigravity, then refreshes skill embeddings.
ctx sync --skills --dry-run	Previews skillshare sync.	You want to inspect behavior before changing skill directories.	Runs skillshare sync --dry-run and skips embedding rebuild.
ctx sync --skills --no-collect	Skips collecting existing agent skills into skillshare.	You already manage ~/.config/skillshare/skills and only want to push it out.	Initializes/syncs skillshare without running skillshare backup or skillshare collect --all.
ctx sync --skills --no-embeddings	Skips ContextOS skill embedding rebuild after skillshare sync.	You have a very large skill catalog and want sync to finish quickly.	Runs skillshare sync, then leaves embeddings to a later ctx embeddings warm -- "task" run.
ctx sync --skills --verbose	Shows native skillshare token budget warnings during sync.	You are diagnosing skillshare path overlap or always-loaded context size.	Omits ContextOS' default skillshare sync --quiet behavior.
ctx sync --workflows	Syncs and indexes agent workflow markdown files for prompt-time workflow suggestions.	You use .agents/workflows/, .claude/workflows/, .codex/workflows/, or Gemini/Antigravity workflow folders and want every agent to see the same deduped workflow set.	Scans project/global workflow folders, dedupes by workflow name, copies unique workflows to selected global agent roots, warms workflow embeddings, and makes ctx debug/prompt hooks show relevant workflow hints.
ctx sync --workflows --agents <list>	Syncs workflows only for selected agents.	You want a subset such as codex,claude or codex,claude,agy.	Accepts comma-separated codex, claude, agy, or antigravity; agy writes the Gemini/Antigravity workflow roots.
ctx sync --workflows --dry-run	Previews workflow sync without writing files.	You want to inspect source workflows and target roots first.	Prints planned sync/index output and skips copying target files.
ctx skills	Installs community skill libraries.	You want curated skills without running the full setup wizard.	Opens the community installer, uses a portable shell on Windows/Linux/macOS, repairs unsafe skill symlinks, and syncs installed skills to selected agents.
ctx embeddings warm -- "task"	Prepares local semantic embedding caches.	First install, CI smoke checks, or after changing AGENTS.md/project files/skills/workflows.	Loads/downloads Xenova/all-MiniLM-L6-v2 and writes rule, file-path, skill, and workflow vectors to ~/.ctx/contextos/embeddings.db.
ctx --config	Opens an interactive panel for prompt sections and suggestion limits.	You want to reduce ContextOS prompt output noise.	Toggles critical rules, suggested files, suggested skills, and suggested workflows globally under ~/.ctx/contextos/output-config.json, then lets you set suggestion counts for files, skills, and workflows.
ctx refresh	Refreshes the active Codex marketplace plugin and rebuilds local indexes.	Local development updates or stale file/skill retrieval indexes.	Copies the current package to $CODEX_HOME/marketplaces/contextos, rebuilds file-path embeddings, skill embeddings, import adjacency, and refreshes code-review-graph embeddings when available.
ctx ruler -- <args>	Forwards args to the installed ruler CLI.	You need native Ruler commands such as init, apply, or revert.	Preserves Ruler stdout/stderr and exit status.
ctx skillshare -- <args>	Forwards args to the installed skillshare CLI.	You need native skillshare commands such as status, target list, doctor, push, or pull.	Preserves skillshare stdout/stderr and exit status.
ctx --version	Prints the installed ContextOS CLI version.	You want to confirm which npm version is being executed.	Prints the version from package metadata.

Do not run ctx install --agent codex|claude|agy in a shell. The | character is a pipe, so the shell will run ctx install --agent codex, pipe its output into claude, then pipe that into agy. Pick one command per agent instead.

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 works standalone. The default path is local project rules, prepared file indexes, project skills, workflows, and evidence capture.

Project graph and memory backends are optional adapters:

Adapter	What it adds	Required?
code-review-graph	Blast radius, semantic node search, and test relationships.	No
codegraph	Symbol/call graph context once its MCP schema is stable.	No
agent-memory / agentmemory	Prior task history, decisions, and recurring bug-fix context.	No

ContextOS does not require code-review-graph, codegraph, or agent-memory to install or run. It gets smarter when those backends are available; when they are missing, the adapter scores stay at zero and the hook continues with local context.

For file suggestions, ContextOS uses prepared local indexes:

prompt
  -> read task-relevant AGENTS.md rules
  -> suggest prepared file candidates
  -> expand nearby imports
  -> add optional project-graph matches when available
  -> inject a compact list of files to check

This keeps the hook fast and local while still using project graph signal when available. When no graph adapter is available, file suggestions still use local file indexes and import expansion.

Prompt-time file suggestions do not walk the repository. ctx install and ctx embeddings warm rebuild the file index and one-hop import adjacency by walking source paths once; prompt hooks query those prepared indexes directly. Rules, files, skills, and workflows are resolved concurrently.

ctx embeddings warm automatically refreshes the active Codex marketplace payload before rebuilding indexes. Use ctx refresh when you want the same marketplace sync plus install-style file, skill, import, and code-review-graph embedding refresh in one command.

If a prompt has no usable context candidates, the hook fails open without emitting an empty hook context block, records emptyContextReason in the workspace runtime file, and starts a detached autowarm rebuild with a cooldown. That background rebuild refreshes prepared indexes for the next prompt while keeping repository walking out of the current prompt path.

If hooks fall back because ctx-mcp is unavailable or not hot yet, ContextOS still uses indexed text matches for files and lightweight evidence scoring for skills. It does not cold-load embeddings inside the prompt hook. Run ctx debug -- "task" to inspect retrieval mode, including bridge status, embedding status, file fallback, and skill fallback.

Use ctx --config to choose which prompt sections ContextOS injects and how many suggestions each section may show. Interactive ctx setup includes the same section picker and limit prompts, while ctx setup --yes keeps the current saved config for automation. The panel supports multiple selection with Space and persists the global choice in ~/.ctx/contextos/output-config.json. Defaults are five suggested files, five skills, and five workflows; caps are 20 files, 10 skills, and 5 workflows. Disabling rules hides both critical and additional relevant rule sections; compliance metadata remains available for reports.

Injected prompt sections are intentionally compact: rules show only detected rule text, files show a comma-separated inline list of basenames without paths, skills show unique plain skill names as a comma-separated inline list without descriptions, and workflows show names with their agent chain. ContextOS only keeps $skill-name syntax for skills the user explicitly requested, so automatic suggestions do not collide with native agent skill activation. Stop hooks persist reports silently; run ctx report or ctx evidence when you want the detailed compliance output.

Codex may flatten newlines in its UserPromptSubmit hook (completed) preview. The injected additionalContext payload remains multiline; this is a Codex preview display limitation.

Skill ranking uses Skill Router v2. ContextOS still starts with semantic retrieval, but final confidence is evidence-based:

final_score =
  semantic_score * 0.30
+ prompt_trigger_score * 0.20
+ project_evidence_score * 0.20
+ file_config_score * 0.10
+ import_graph_score * 0.10
+ external_graph_score * 0.05
+ memory_score * 0.05
- negative_penalty * 0.20

external_graph_score is supplied by optional project graph adapters such as code-review-graph or codegraph. memory_score is reserved for optional memory adapters such as agent-memory. Without those adapters, both scores are 0.

Skill metadata can live beside SKILL.md as skill.yaml:

id: eas
name: Expo EAS Deployment
positive_triggers:
  prompts: [eas, expo build, deployed, android, ios]
  files: [eas.json, app.json, app.config.ts]
  dependencies: [expo, eas-cli]
negative_triggers:
  dependencies: [next, vite]
  files: [vercel.json]
related_skills:
  - mobile-deployment
  - github-actions-ci-cd
  - env-secret-management

The project profile is built from bounded root/workspace package.json metadata, dependencies, scripts, detected languages, recent git files, and config files such as eas.json, app.json, vercel.json, and .github/workflows/*. ContextOS only gives high confidence to domain-specific skills when project evidence supports them. For example, fix deployed can rank eas highly in an Expo project with eas.json and expo, but a Next.js/Vercel project should route to Vercel and CI/CD deployment skills instead. Skill catalogs are deduplicated by normalized skill name before indexing and rendering.

Use ctx skills doctor -- "task" to inspect routing:

ctx skills doctor -- "fix deployed"

The doctor output shows semantic score, prompt triggers, dependency/file evidence, negative signals, and final confidence for each selected skill. Confidence is calibrated separately from ranking and includes a band:

high: >= 0.85
medium: 0.65-0.84
low: < 0.65

Use ctx benchmark --skills to run the local Skill Router benchmark. The eval lives in eval/skill-routing and currently covers 52 cases across deployment, auth, database, testing, mobile, and adversarial negative gates.

Current local benchmark:

Cases: 52
Top-1 Accuracy: 94.2%
Top-3 Recall: 94.2%
False Positive Rate: 0.0%
Confidence Calibration: 100.0%
Negative Gate Accuracy: 100.0%

The benchmark includes same-prompt/different-repo checks such as fix deployed in Expo/EAS, Next/Vercel, and ContextOS itself, plus adversarial cases like expo-with-vercel-json where eas is expected and vercel-deployment must be rejected.

After ctx refresh, ContextOS invalidates the private hook bridge socket so prompts fall back to direct scoring until Codex restarts the long-running ctx-mcp process. Hook clients also discard a same-inode socket if an older bridge revision is detected.

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_CONNECT_TIMEOUT_MS=500 stale ctx-mcp socket connect timeout
CONTEXTOS_MCP_BRIDGE_TIMEOUT_MS=5000 ctx-mcp hook bridge timeout
CONTEXTOS_MCP_AUTOSTART=1        auto-start ctx-mcp daemon when the private bridge socket is missing
CONTEXTOS_MCP_AUTOSTART_WAIT_MS=1500 max hook wait for auto-started ctx-mcp before fallback
CONTEXTOS_HOOK_DEADLINE_MS=8500 hard fail-open deadline for prompt hooks
CONTEXTOS_DIRECT_FALLBACK_TIMEOUT_MS=2500 direct scoring timeout when the bridge is unavailable
CONTEXTOS_HOOK_EMBEDDING_TIMEOUT_MS=500 rule embedding timeout during hook direct fallback
CONTEXTOS_EMBEDDING_TIMEOUT_MS=800 embedding scoring timeout inside ctx-mcp/debug
CONTEXTOS_HOOK_SKILL_EMBEDDING_TIMEOUT_MS=2000 skill retrieval timeout when embeddings are enabled
CONTEXTOS_SKILL_EMBEDDING_TIMEOUT_MS=2000 skill retrieval timeout inside ctx-mcp/debug
CONTEXTOS_FILE_EMBEDDINGS=0       disable file-path embedding retrieval
CONTEXTOS_HOOK_FILE_EMBEDDING_TIMEOUT_MS=500 file retrieval timeout during hook direct fallback
CONTEXTOS_FILE_EMBEDDING_TIMEOUT_MS=1000 file-path embedding retrieval timeout

Hook Flow

Codex prompt
  -> UserPromptSubmit hook
  -> auto-start ctx-mcp daemon if the private bridge socket is missing
  -> 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, command metadata, and ContextOS' own internal graph retrieval events. A rule like "use code-review-graph before reading files" can be marked followed when telemetry contains a matching code-review-graph signal, whether retrieval traveled through the MCP proxy or the local graph bridge.

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.

The local graph bridge calls code-review-graph.semantic_search_nodes directly for hook latency, so it bypasses the stdio proxy. ContextOS records these calls separately as InternalGraphRetrieval telemetry with source=graph-retriever. codegraph detection is already active, but the hybrid adapter remains pending until its MCP response schema is stable enough to merge symbol lookup context with code-review-graph blast-radius results.

Codex MCP config is parsed with smol-toml. ContextOS rewrites only the selected MCP server fields so comments, ordering, multiline arrays, and tool approval subsections are preserved.

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.
• File suggestions require local file-path embeddings or graph matches. ContextOS no longer falls back to filename heuristics when embedding caches are unavailable.
• codegraph detection is diagnostic only until the codegraph_context adapter contract is implemented.
• 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.