{"id":50492454,"url":"https://github.com/khovan123/contextos","last_synced_at":"2026-06-02T04:01:24.480Z","repository":{"id":360202825,"uuid":"1249092678","full_name":"khovan123/contextOS","owner":"khovan123","description":"Task-aware AGENTS.md context injection and compliance reports for Codex, Claude Code, and Antigravity.","archived":false,"fork":false,"pushed_at":"2026-06-01T20:44:15.000Z","size":1128,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T22:22:40.022Z","etag":null,"topics":["agents-md","ai-agents","antigravity","claude-code","codex","developer-tools","mcp"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/khovan123.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-25T10:46:50.000Z","updated_at":"2026-06-01T20:44:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/khovan123/contextOS","commit_stats":null,"previous_names":["khovan123/contextos"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/khovan123/contextOS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khovan123%2FcontextOS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khovan123%2FcontextOS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khovan123%2FcontextOS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khovan123%2FcontextOS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/khovan123","download_url":"https://codeload.github.com/khovan123/contextOS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khovan123%2FcontextOS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33805341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents-md","ai-agents","antigravity","claude-code","codex","developer-tools","mcp"],"created_at":"2026-06-02T04:01:23.560Z","updated_at":"2026-06-02T04:01:24.425Z","avatar_url":"https://github.com/khovan123.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ContextOS\n\nCodex ignores the middle of your `AGENTS.md`. ContextOS fixes that.\n\nIt ranks your project rules against the current prompt, injects the right ones at the moment the agent starts work, suggests relevant files/skills/workflows, and reports what the agent actually followed after the task.\n\n```text\nWITHOUT ContextOS\n  AGENTS.md is a long static blob\n  important rules drift into the middle\n  agent starts by grepping files and misses the repo contract\n\nWITH ContextOS\n  prompt -\u003e score relevant AGENTS.md rules\n         -\u003e inject critical rules at top and bottom\n         -\u003e suggest files, skills, workflows\n         -\u003e report followed / ignored / unknown\n```\n\nPublished package: [`@minhpnq1807/contextos`](https://www.npmjs.com/package/@minhpnq1807/contextos)\n\n## Demo\n\n![ContextOS actual terminal demo](docs/demo/contextos-demo.gif)\n\nExample hook context injected before the agent works:\n\n```text\n## Critical ContextOS rules\n- IMPORTANT: This project has a knowledge graph. ALWAYS use code-review-graph MCP tools before Grep/Glob/Read.\n- Use `query_graph` pattern=\"tests_for\" to check coverage.\n\n## Suggested files to check\n- services/content-service/test/unit/creator-only.policy.unit-spec.ts\n- services/content-service/test/integration/resource-upload.integration-spec.ts\n\n## Suggested workflow for this task\n- Primary Workflow: use for feature implementation, testing, review, and debugging\n  chain: planner -\u003e tester -\u003e code-reviewer\n```\n\nAfter the task:\n\n```text\nContextOS report\nEfficiency: 100%\nInjected rules: 8\nRule outcomes: 8 followed, 0 ignored, 0 unknown\nRuntime telemetry: code-review-graph, code-review-graph.query_graph_tool\n```\n\n## Quick Install\n\n```bash\nnpm install -g @minhpnq1807/contextos\nctx setup\n```\n\nNo postinstall surprise: `npm install` only installs the CLI. Setup runs only when you call `ctx setup`.\n\nScriptable setup:\n\n```bash\nctx setup --yes\nctx setup --yes --agents codex,claude,agy\n```\n\nNo global install:\n\n```bash\nnpm exec --yes --package=@minhpnq1807/contextos@latest -- ctx setup\nnpm exec --yes --package=@minhpnq1807/contextos@latest -- ctx-codex install\n```\n\nCodex-only:\n\n```bash\nctx install\n```\n\nClaude Code and Antigravity:\n\n```bash\nctx install claude\nctx install agy\n```\n\nRestart the agent after setup. Then use the agent normally.\n\n## Why\n\nDevelopers put real operating instructions in `AGENTS.md`: use this graph tool before reading files, run these tests, follow this architecture boundary, avoid this migration path.\n\nThe problem is not that agents cannot read `AGENTS.md`. The problem is that large context windows bury the important rule in the middle, where attention is weak. ContextOS turns a static rules file into task-aware runtime context.\n\n## What ContextOS Does\n\n| Layer | What happens |\n| --- | --- |\n| Hooks | Codex, Claude Code, and Antigravity hooks run before/after each task. |\n| Scoring | Local MiniLM embeddings plus heuristics rank AGENTS.md rules by the prompt. |\n| Injection | Critical rules are placed with primacy + recency, not buried in the middle. |\n| Discovery | Relevant files, skills, and workflows are suggested before work starts. |\n| Sync | Rules/MCP via Ruler, skills via skillshare, workflows via ContextOS. |\n| Evidence | Stop hooks persist `followed`, `ignored`, `unknown`, and runtime telemetry for explicit reports. |\n\n## Quick Commands\n\n| Command | Use it for |\n| --- | --- |\n| `ctx setup` | Recommended first-run install flow. |\n| `ctx debug -- \"Recheck authen flow\"` | Preview what ContextOS would inject. |\n| `ctx report` | Show the last task's compliance summary. |\n| `ctx evidence` | Show why each rule was marked followed/ignored/unknown. |\n| `ctx stats` | Show workspace-level usage and effectiveness metrics. |\n| `ctx benchmark -- \"task\"` | Compare raw AGENTS.md ordering vs ContextOS scheduling. |\n| `ctx sync --rules` | Sync AGENTS/Ruler/MCP config across agents. |\n| `ctx sync --skills` | Sync skills across agents through skillshare. |\n| `ctx sync --workflows` | Sync workflow markdown across Claude/Codex/Antigravity. |\n\n## 60-Second Demo Script\n\n1. Start in a repo with an `AGENTS.md` that contains a rule like:\n\n```text\nAlways use code-review-graph MCP tools before reading files.\n```\n\n2. Install:\n\n```bash\nnpm install -g @minhpnq1807/contextos\nctx setup --yes --agents codex\n```\n\n3. Restart Codex and submit:\n\n```text\nRecheck authen flow\n```\n\n4. Show the injected `hook context`.\n\n5. Let the task finish, then run:\n\n```bash\nctx report\nctx evidence\n```\n\nThe 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.\n\n## Detailed Install\n\nFrom the package:\n\n```bash\nnpm install -g @minhpnq1807/contextos\nctx install\n```\n\nWithout a global install:\n\n```bash\nnpx @minhpnq1807/contextos@latest install\n```\n\nFrom this repository during local development:\n\n```bash\nnode bin/ctx.js install\n```\n\nAgent-specific installers:\n\n```bash\nctx install codex\nctx install claude\nctx install agy\nctx install --agent codex\nctx install --agent claude\nctx install --agent agy\n```\n\n`ctx install` defaults to `ctx install codex`.\n\n### Codex\n\n`ctx install codex` does these things:\n\n1. Copies this package into `$CODEX_HOME/marketplaces/contextos`.\n2. Registers and installs `ctx@contextos` through Codex plugin marketplace commands.\n3. Downloads and caches the required local MiniLM embedding model under `~/.ctx/contextos/models`.\n4. Warms `~/.ctx/contextos/embeddings.db` for AGENTS rules and project file paths.\n5. Registers the `ctx-mcp` MCP server and merges ContextOS global hooks into `$CODEX_HOME/hooks.json`.\n6. 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.\n7. 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.\n8. 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.\n\nRestart Codex after installing.\n\n### Claude Code\n\n`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`.\n\nClaude 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`.\n\nRestart Claude Code after installing.\n\n### Antigravity\n\n`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:\n\n```text\n~/.gemini/antigravity/mcp_config.json\n~/.gemini/antigravity-cli/mcp_config.json\n~/.gemini/config/mcp_config.json\n```\n\nThe third path supports older Antigravity editor builds where `@mcp` reads the legacy Gemini config directory.\n\nAntigravity 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.\n\nRestart Antigravity or `agy` after installing.\n\nThe 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.\n\nDuring 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.\n\nVerify the published package in any project:\n\n```bash\nnpm exec --yes --package=@minhpnq1807/contextos@latest -- ctx --version\nnpm exec --yes --package=@minhpnq1807/contextos@latest -- ctx debug -- \"Recheck authen flow\"\n```\n\n## Skill Sync\n\nUse skillshare when you want Codex, Claude Code, and Antigravity to share one skills catalog:\n\n```bash\nctx sync --skills\n```\n\nContextOS 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.\n\nThe shared source is:\n\n```text\n~/.config/skillshare/skills/\n```\n\nUseful variants:\n\n```bash\nctx sync --skills --dry-run\nctx sync --skills --no-collect\nctx sync --skills --no-embeddings\nctx sync --skills --verbose\nctx sync --skills --agents codex,claude\nctx sync --skills --agents codex,claude,agy\n```\n\nAfter this, `ctx debug -- \"task\"` and prompt hooks can suggest skills from `~/.config/skillshare/skills/` plus agent-specific skill folders.\n\n## Workflow Discovery\n\nContextOS can also sync Claude/Codex/Antigravity workflow markdown files and suggest the right workflow for the current task:\n\n```bash\nctx sync --workflows\nctx sync --workflows --agents codex,claude,agy\nctx sync --workflows --dry-run\n```\n\nIt scans project workflows first, then global workflows:\n\n```text\n.claude/workflows/\n.codex/workflows/\n.gemini/workflows/\n.gemini/antigravity/workflows/\n.gemini/antigravity-cli/workflows/\n~/.claude/workflows/\n~/.codex/workflows/\n~/.gemini/workflows/\n~/.gemini/antigravity/workflows/\n~/.gemini/antigravity-cli/workflows/\n```\n\nWorkflow 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.\n\n`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.\n\n## Modes\n\nInjection mode is the default:\n\n```bash\nctx install\n```\n\nIn 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.\n\nQuiet mode:\n\n```bash\nctx install --quiet\n```\n\nQuiet mode analyzes and measures prompts but returns an empty `additionalContext`, so Codex does not show a `hook context` block.\n\nExplicit injection mode is also accepted:\n\n```bash\nctx install --inject\n```\n\nDevelopment copy mode:\n\n```bash\nctx install --copy\n```\n\nCopies only the plugin payload into `$CODEX_HOME/plugins/ctx`. This is mostly for local experiments.\n\n## Ruler Sync\n\nUse Ruler when the project wants one rule/MCP source of truth for multiple agents:\n\n```bash\nctx sync --rules\n```\n\nDefault 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:\n\n```bash\nctx sync --rules --agents codex\nctx sync --rules --agents codex,claude\nctx sync --rules --agents codex,claude,agy\nctx sync --rules --agents codex,claude,antigravity\n```\n\nWhat it does:\n\n1. Checks that `ruler` is installed. If it is missing, ContextOS asks before running `npm install -g @intellectronica/ruler`; use `--yes` for non-interactive installs.\n2. Runs `ruler init` when `.ruler/ruler.toml` is missing.\n3. Adds `ctx-mcp` to `.ruler/ruler.toml` under `[mcp_servers.ctx-mcp]`.\n4. 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`.\n5. Adds enabled Ruler agent entries for Codex, Claude Code, and Antigravity using merge strategy.\n6. Runs `ruler apply --agents ...`.\n7. Mirrors the Ruler MCP server list into Antigravity app/CLI MCP configs because current Ruler versions do not emit every Antigravity MCP file consistently.\n8. Verifies that generated agent config contains `ctx-mcp`.\n\nUseful flags:\n\n```bash\nctx sync --rules --dry-run\nctx sync --rules --force\nctx sync --rules --yes\nctx sync --rules --no-import-codex-mcp\n```\n\n`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.\n\n## Upstream Passthrough\n\nContextOS exposes thin passthrough commands for Ruler and skillshare admin/debug workflows:\n\n```bash\nctx ruler -- apply --agents codex,claude,antigravity\nctx ruler -- init\nctx skillshare -- status\nctx skillshare -- target list\nctx skillshare -- doctor\n```\n\nEverything 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.\n\n## Troubleshooting\n\n### `ctx-mcp bridge socket not found`\n\nRestart 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.\n\n### `ContextOS model cache missing`\n\nRun:\n\n```bash\nctx embeddings warm -- \"Recheck authen flow\"\n```\n\nThen restart Codex.\n\n### No report found\n\nRun at least one Codex task with ContextOS enabled and let the task finish so the `Stop` hook can write `last-report.json`.\n\n### `Average efficiency: unknown`\n\nContextOS 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`.\n\n### `npm warn deprecated prebuild-install@7.1.3`\n\nThis 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`.\n\n## Commands\n\n| Command | Meaning | Use when | Output / side effect |\n| --- | --- | --- | --- |\n| `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. |\n| `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. |\n| `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`. |\n| `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. |\n| `ctx install --agent \u003cname\u003e` | Installs for a named agent. | You prefer explicit scripts. | Accepts `codex`, `claude`, or `agy`. |\n| `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. |\n| `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. |\n| `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. |\n| `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. |\n| `ctx setup --yes` | Runs setup with defaults non-interactively. | You want scriptable all-agent setup. | Uses `codex,claude,agy`, enables injection, syncs rules, syncs skills, and passes `--yes` to dependency setup prompts. |\n| `ctx setup --agents \u003clist\u003e` | Runs setup for selected agents. | You want only part of the default set. | Accepts comma-separated `codex`, `claude`, `agy`, or `antigravity`. |\n| `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`. |\n| `ctx setup --no-skills` | Skips skillshare sync during setup. | You do not want shared skills configured. | Does not run `ctx sync --skills`. |\n| `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. |\n| `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`. |\n| `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/\u003cworkspace-id\u003e/last-report.json`. |\n| `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. |\n| `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. |\n| `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. |\n| `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. |\n| `ctx sync --rules --agents \u003clist\u003e` | 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`. |\n| `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. |\n| `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. |\n| `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`. |\n| `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. |\n| `ctx sync --skills --agents \u003clist\u003e` | Syncs skills only for selected agents. | You want to target a subset such as `codex,claude` or `codex,claude,agy`. | Runs `skillshare sync --agents \u003clist\u003e` with `agy` normalized to `antigravity`, then refreshes skill embeddings. |\n| `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. |\n| `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`. |\n| `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. |\n| `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. |\n| `ctx sync --workflows` | Syncs and indexes agent workflow markdown files for prompt-time workflow suggestions. | You use `.claude/workflows/`, `.codex/workflows/`, or 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. |\n| `ctx sync --workflows --agents \u003clist\u003e` | 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. |\n| `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. |\n| `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. |\n| `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`. |\n| `ctx --config` | Opens an interactive multi-select panel for prompt sections. | 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`. |\n| `ctx refresh` | Refreshes the active Codex marketplace plugin and rebuilds local indexes. | Local development updates or a stale file retrieval index. | Copies the current package to `$CODEX_HOME/marketplaces/contextos`, rebuilds file-path embeddings and import adjacency, and refreshes code-review-graph embeddings when available. |\n| `ctx ruler -- \u003cargs\u003e` | 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. |\n| `ctx skillshare -- \u003cargs\u003e` | 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. |\n| `ctx --version` | Prints the installed ContextOS CLI version. | You want to confirm which npm version is being executed. | Prints the version from package metadata. |\n\nDo 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.\n\n## Runtime Files\n\nContextOS writes shared caches to:\n\n```text\n~/.ctx/contextos/\n```\n\nRuntime prompt/report files are isolated by workspace:\n\n```text\n~/.ctx/contextos/workspaces/\u003cworkspace-id\u003e/\n```\n\nImportant files:\n\n```text\ndebug.log                 hook event log\nctx-mcp.sock              private hook bridge owned by ctx-mcp\nlast-prompt-context.json  latest scheduled context\nlast-report.json          latest compliance report\nprompt-history.jsonl      prompt scheduling history\nreport-history.jsonl      report history\ntelemetry.jsonl           local runtime signals from hooks, tools, and commands\n```\n\nThe workspace id is stored in the target repo at:\n\n```text\n.contextos/workspace.json\n```\n\nContextOS 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.\n\nCodex, 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.\n\nThese files are local telemetry only. Hooks do not make network calls.\n\n## Project Understanding\n\nContextOS does not try to replace `code-review-graph`. It uses it as the project-understanding layer when the target repo has already built a graph database.\n\nFor file suggestions, ContextOS now runs a local RAG-style retrieval pass:\n\n```text\nprompt\n  -\u003e UserPromptSubmit hook calls ctx-mcp bridge\n  -\u003e ctx-mcp reads AGENTS.md and scores rules with local MiniLM\n  -\u003e query the persisted file-vector index in embeddings.db for semantic file candidates\n  -\u003e expand candidates through relative import graph links\n  -\u003e query code-review-graph semantic_search_nodes with seed entity names\n  -\u003e merge and deduplicate semantic, import-graph, and code-review-graph matches\n  -\u003e inject top suggested files with graph evidence reasons\n```\n\nThis keeps the hook fast and local while still using graph semantics when available. The graph search path is visible in runtime data through file reasons such as `graph:content-moderation.service`.\n\nPrompt scoring does not walk the repository for file candidates or import expansion. `ctx install` and `ctx embeddings warm` rebuild the persisted file-vector index and one-hop import adjacency index by walking source paths once; prompt hooks query those indexes directly. Rules, files, skills, and workflows are scored concurrently with `Promise.all()`.\n\n`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/import index and code-review-graph embedding refresh in one command.\n\nIf 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 file vectors, skill/workflow vectors, import adjacency, and available code-review-graph node embeddings for the next prompt while keeping repository walking out of the current prompt hot path.\n\nUse `ctx --config` to choose which prompt sections ContextOS injects. Interactive `ctx setup` now includes the same multi-select step, 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`. Disabling rules hides both critical and additional relevant rule sections; compliance metadata remains available for reports.\n\nInjected prompt sections are intentionally compact: rules show only detected rule text, files show basenames without paths, skills show unique names as a comma-separated inline list without descriptions, and workflows show names with their agent chain. Stop hooks persist reports silently; run `ctx report` or `ctx evidence` when you want the detailed compliance output.\n\nCodex may flatten newlines in its `UserPromptSubmit hook (completed)` preview. The injected `additionalContext` payload remains multiline; this is a Codex preview display limitation.\n\nSkill ranking uses bounded project hints from root/workspace `package.json` files and known mobile config files such as `app.json`, `app.config.*`, and `eas.json`. This lets Expo/EAS tasks activate specialized skills without walking the source tree on every prompt.\n\nAfter `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.\n\nConfiguration:\n\n```text\nCONTEXTOS_GRAPH_RETRIEVAL=0       disable graph-backed file retrieval\nCONTEXTOS_GRAPH_TIMEOUT_MS=80     graph lookup timeout\nCONTEXTOS_CRG_PYTHON=/path/python Python with code_review_graph installed\nCONTEXTOS_EMBEDDINGS=0            disable embedding rule scoring\nCONTEXTOS_MCP_CONNECT_TIMEOUT_MS=100 stale ctx-mcp socket connect timeout\nCONTEXTOS_MCP_BRIDGE_TIMEOUT_MS=2000 ctx-mcp hook bridge timeout\nCONTEXTOS_HOOK_DEADLINE_MS=8500 hard fail-open deadline for prompt hooks\nCONTEXTOS_DIRECT_FALLBACK_TIMEOUT_MS=6000 direct scoring timeout when the bridge is unavailable\nCONTEXTOS_HOOK_EMBEDDING_TIMEOUT_MS=500 rule embedding timeout during hook direct fallback\nCONTEXTOS_EMBEDDING_TIMEOUT_MS=800 embedding scoring timeout inside ctx-mcp/debug\nCONTEXTOS_FILE_EMBEDDINGS=0       disable file-path embedding retrieval\nCONTEXTOS_HOOK_FILE_EMBEDDING_TIMEOUT_MS=500 file retrieval timeout during hook direct fallback\nCONTEXTOS_FILE_EMBEDDING_TIMEOUT_MS=1000 file-path embedding retrieval timeout\n```\n\n## Hook Flow\n\n```text\nCodex prompt\n  -\u003e UserPromptSubmit hook\n  -\u003e call ctx-mcp through private bridge\n  -\u003e ctx-mcp scores rules and relevant files\n  -\u003e write last-prompt-context.json\n  -\u003e return additionalContext unless quiet mode is enabled\n  -\u003e Codex runs task\n  -\u003e Stop hook\n  -\u003e read git diff/status\n  -\u003e measure rule evidence\n  -\u003e write last-report.json and report-history.jsonl\n```\n\n## Rule Outcomes\n\nContextOS uses heuristic evidence collection from git diff/status plus local runtime telemetry.\n\n```text\nfollowed = evidence in the diff suggests the rule was applied\nignored  = evidence in the diff suggests the rule was violated\nunknown  = the rule was relevant, but the diff does not prove either way\nunmeasurable = ContextOS lacks the required evidence source, such as git diff lines or runtime telemetry\n```\n\nFor 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.\n\n`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.\n\nThe 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.\n\nCodex 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.\n\nHost/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.\n\n## Development\n\nInstall dependencies:\n\n```bash\nnpm install\n```\n\nRun tests:\n\n```bash\nnpm test\n```\n\nRun MCP protocol and warm performance smoke:\n\n```bash\nnpm run test:mcp\n```\n\nValidate plugin schema:\n\n```bash\nnpm run validate:plugin\n```\n\nCheck the npm package contents:\n\n```bash\nnpm pack --dry-run\n```\n\nSmoke test prompt hook:\n\n```bash\nprintf '%s' '{\"prompt\":\"Recheck authen flow\",\"cwd\":\"'$PWD'\",\"hook_event_name\":\"UserPromptSubmit\"}' \\\n  | node plugins/ctx/bin/on-prompt.js\n```\n\nSmoke test Stop hook:\n\n```bash\nprintf '%s' '{\"cwd\":\"'$PWD'\",\"hook_event_name\":\"Stop\"}' \\\n  | node plugins/ctx/bin/on-stop.js\n```\n\n## Project Layout\n\n```text\nbin/ctx.js                         CLI\nplugins/ctx/hooks.json             plugin hook declaration\nplugins/ctx/bin/                   hook entrypoints\nplugins/ctx/mcp/server.js          ctx-mcp MCP server and hook bridge\nplugins/ctx/lib/reader.js          AGENTS.md reader\nplugins/ctx/lib/analyzer.js        rule/file scoring\nplugins/ctx/lib/embedding-scorer.js local embedding rule scoring\nplugins/ctx/lib/score-context.js   shared MCP scoring pipeline\nplugins/ctx/lib/ctx-mcp-client.js  hook bridge client\nplugins/ctx/lib/import-graph.js      relative import graph traversal\nplugins/ctx/lib/graph-retriever.js code-review-graph retrieval bridge\nplugins/ctx/lib/scheduler.js       context layout\nplugins/ctx/lib/measure.js         diff-based compliance checks\nplugins/ctx/lib/reporter.js        report/evidence formatting\nplugins/ctx/lib/stats.js           runtime stats\nplugins/ctx/lib/global-hooks.js    Codex global hook installer\ntest/                              unit tests\ncontextos-plan.jsx                 implementation plan/reference\n```\n\n## Limitations\n\n- Codex and Claude Code get prompt context through `additionalContext`; Antigravity gets prompt context through `PreInvocation` `ephemeralMessage`.\n- File suggestions require local file-path embeddings or graph matches. ContextOS no longer falls back to filename heuristics when embedding caches are unavailable.\n- `codegraph` detection is diagnostic only until the `codegraph_context` adapter contract is implemented.\n- Antigravity Stop hooks store reports locally, but they do not display the full report inline unless Antigravity adds a non-continuing Stop message surface.\n- Local marketplace plugin hooks may not fire reliably in current Codex builds, so `ctx install` also installs global hooks.\n- Injection mode may show a visible hook context block in some agents.\n- Quiet mode does not inject context into the model; it only records and measures.\n- Compliance is heuristic and mostly based on git diff/status.\n- Some rules can only be `unknown` unless ContextOS records richer telemetry such as tool calls or shell command metadata.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhovan123%2Fcontextos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkhovan123%2Fcontextos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhovan123%2Fcontextos/lists"}