# ContextOS

Same prompt. Same model. Different context.

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

[![npm version](https://img.shields.io/npm/v/@minhpnq1807/contextos.svg)](https://www.npmjs.com/package/@minhpnq1807/contextos)
[![CI](https://github.com/khovan123/contextOS/actions/workflows/ci.yml/badge.svg)](https://github.com/khovan123/contextOS/actions/workflows/ci.yml)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

```text
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`](https://www.npmjs.com/package/@minhpnq1807/contextos)

## Hallucination Leaderboard

Offline deterministic benchmark:

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

```bash
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:

```bash
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](https://github.com/khovan123/contextOS/issues/1)
- [Run Claude Code live benchmark](https://github.com/khovan123/contextOS/issues/3)
- [Run Gemini CLI live benchmark](https://github.com/khovan123/contextOS/issues/4)
- [Run Cursor live benchmark](https://github.com/khovan123/contextOS/issues/2)

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

![ContextOS demo: same prompt, different repo, correct skills](docs/demo/same-prompt-different-context.gif)

```bash
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](docs/demo/agents-lost-middle.gif) |

## What The Agent Sees

ContextOS injects a compact brief before the agent works:

```text
## 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:

```text
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:

```bash
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:

```bash
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:

```bash
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:

```bash
ctx doctor --fix
```

No global install:

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

Codex-only:

```bash
ctx install
```

Claude Code and Antigravity:

```bash
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](docs/roadmap.md) for the current roadmap notes.

## Community Skill Packs

ContextOS starts the community loop with [`community-skills/`](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/`](community-skills/_template/).

## ContextOS Ready

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

```bash
ctx doctor
```

```text
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:

```text
Always use the project graph before reading files.
```

2. Install:

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

3. Restart Codex and submit:

```text
Recheck authen flow
```

4. Show the injected `hook context`.

5. Let the task finish, then run:

```bash
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:

```bash
npm install -g @minhpnq1807/contextos
ctx install
```

Without a global install:

```bash
npx @minhpnq1807/contextos@latest install
```

From this repository during local development:

```bash
node bin/ctx.js install
```

Agent-specific installers:

```bash
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:

```text
~/.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:

```text
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:

```text
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:

```bash
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:

```bash
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:

```text
~/.config/skillshare/skills/
```

Useful variants:

```bash
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:

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

It scans project workflows first, then global workflows:

```text
.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:

```bash
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:

```bash
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:

```bash
ctx install --inject
```

Development copy mode:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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

| 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 budgets. | 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 keep adaptive `auto` budgets or set fixed 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:

```text
~/.ctx/contextos/
```

Runtime prompt/report files are isolated by workspace:

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

Important files:

```text
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:

```text
.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:

```text
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 use adaptive `auto` budgets: up to 15 files, 8 skills, and 3 workflows, with confidence drop-off and task complexity deciding the final count. Advanced users can still set fixed counts; hard 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.

Adaptive budgets keep small fixes compact and give larger feature prompts more context. Files are selected by task complexity plus path diversity, so a feature task can include route, component, service, test, and config candidates instead of five files from the same folder. Skills and workflows use confidence drop-off, so ContextOS may show only two strong skills or seven relevant skills instead of filling a fixed quota.

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 no longer treats `SKILL.md` as only unstructured text. It parses markdown sections into a lightweight MDAST-style tree, normalizes that into router schema, builds a skill graph from schema relationships, then uses embeddings as the final retrieval layer:

```text
SKILL.md / skill.yaml
  -> markdown sections
  -> Skill JSON schema
  -> Skill Graph
  -> focused embedding text
  -> evidence-based Skill Router
```

Final confidence is evidence-based:

```text
final_score =
  semantic_score * 0.25
+ prompt_trigger_score * 0.20
+ project_evidence_score * 0.25
+ file_config_score * 0.10
+ import_graph_score * 0.10
+ skill_graph_score * 0.10
+ source_boost_score * 0.05
+ external_graph_score * 0.03
+ memory_score * 0.02
- negative_penalty * 0.20
```

`skill_graph_score` comes from relationships such as `related_skills`, `depends_on`, `provides`, and `requires`. `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 adapter scores are `0`.

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

```yaml
id: eas
name: Expo EAS Deployment
intent: [deployment, mobile]
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]
provides:
  - mobile-deployment
requires:
  - app-config
depends_on:
  - github-actions-ci-cd
related_skills:
  - mobile-deployment
  - github-actions-ci-cd
  - env-secret-management
workflow:
  - Inspect EAS profiles, app config, package scripts, and CI workflow files.
```

If a skill has no `skill.yaml`, ContextOS still extracts useful schema from common markdown sections such as `## Triggers`, `## Evidence`, `## Files`, `## Related Skills`, `## Provides`, and `## Requires`.

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:

```bash
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:

```text
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:

```text
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:

```text
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

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

```text
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:

```bash
npm install
```

Run tests:

```bash
npm test
```

Run MCP protocol and warm performance smoke:

```bash
npm run test:mcp
```

Validate plugin schema:

```bash
npm run validate:plugin
```

Check the npm package contents:

```bash
npm pack --dry-run
```

Smoke test prompt hook:

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

Smoke test Stop hook:

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

## Project Layout

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