@minhpnq1807/contextos 0.5.11 → 0.5.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/DEMO.md +46 -13
  3. package/LAUNCH.md +93 -0
  4. package/README.md +113 -63
  5. package/bin/ctx.js +4 -1
  6. package/docs/contextos-demo-placeholder.svg +25 -0
  7. package/package.json +5 -2
  8. package/plugins/ctx/lib/workflow-discoverer.js +75 -4
package/CHANGELOG.md CHANGED
@@ -1,5 +1,16 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.5.13
4
+
5
+ - Reworks the README for launch: demo-first positioning, fear hook, one-line install, before/after, and quick command table.
6
+ - Adds a launch kit and concrete demo recording script for HN/X/GitHub/npm launch prep.
7
+ - Adds `ctx-codex` as a bin alias for npm package execution flows.
8
+
9
+ ## 0.5.12
10
+
11
+ - Makes `ctx sync --workflows` synchronize unique workflow files to global Claude, Codex, and Antigravity workflow roots.
12
+ - Adds `ctx sync --workflows --agents ...` and `--dry-run`, with workflow-name dedupe to avoid duplicated workflow suggestions across agents.
13
+
3
14
  ## 0.5.11
4
15
 
5
16
  - Adds Antigravity workflow discovery roots under `.gemini/workflows`, `.gemini/antigravity/workflows`, and `.gemini/antigravity-cli/workflows`.
package/DEMO.md CHANGED
@@ -1,24 +1,42 @@
1
1
  # ContextOS Demo Script
2
2
 
3
- Use this script to record the README demo GIF or terminal clip.
3
+ Use this to record the README GIF or a short terminal clip.
4
+
5
+ ## Goal
6
+
7
+ Show one thing clearly:
8
+
9
+ ```text
10
+ AGENTS.md rule buried in a long file -> ContextOS injects the relevant rule -> ctx report proves whether it was followed
11
+ ```
4
12
 
5
13
  ## Setup
6
14
 
7
15
  ```bash
8
16
  npm install -g @minhpnq1807/contextos
9
- ctx install
17
+ ctx setup --yes --agents codex
10
18
  ```
11
19
 
12
- Restart Codex after install.
20
+ Restart Codex after setup.
21
+
22
+ ## Fixture Rule
23
+
24
+ Use a repo whose `AGENTS.md` contains a rule like:
25
+
26
+ ```text
27
+ IMPORTANT: This project has a knowledge graph. Always use code-review-graph MCP tools before Grep/Glob/Read.
28
+ ```
29
+
30
+ The rule should be somewhere below the first screen of `AGENTS.md` so the demo makes the lost-in-the-middle problem obvious.
13
31
 
14
32
  ## Recording Flow
15
33
 
16
- 1. Open a project with an `AGENTS.md`.
17
- 2. Start Codex.
34
+ 1. Show the rule in `AGENTS.md`.
35
+ 2. Start Codex in the project.
18
36
  3. Submit:
19
37
 
20
38
  ```text
21
- kiểm tra flow kiểm duyệt upload
39
+ Recheck authen flow
22
40
  ```
23
41
 
24
42
  4. Show the `hook context` block:
@@ -28,30 +46,45 @@ kiểm tra flow kiểm duyệt upload
28
46
  ...
29
47
  ## Suggested files to check
30
48
  ...
49
+ ## Suggested workflow for this task
50
+ ...
31
51
  ```
32
52
 
33
- 5. Let the task finish so the Stop hook runs.
53
+ 5. Let the task finish so the Stop hook writes the report.
34
54
  6. Show:
35
55
 
36
56
  ```bash
57
+ ctx report
37
58
  ctx evidence
38
59
  ctx stats
39
60
  ```
40
61
 
41
- ## Expected Talking Points
62
+ ## Side-By-Side Clip
63
+
64
+ Record two short terminal panes:
65
+
66
+ | Left | Right |
67
+ | --- | --- |
68
+ | Codex without ContextOS. | Codex with ContextOS. |
69
+ | Agent starts by reading random files or grepping. | Hook context shows the relevant rule before work starts. |
70
+ | No evidence report. | `ctx report` shows followed/ignored/unknown. |
71
+
72
+ ## Talking Points
42
73
 
43
- - ContextOS does not replace Codex or wrap the CLI.
44
- - It runs as a Codex plugin with hooks plus `ctx-mcp`.
74
+ - ContextOS does not replace Codex, Claude Code, or Antigravity.
75
+ - It runs through native hooks plus a local `ctx-mcp` MCP server.
45
76
  - It uses local embeddings to bridge vocabulary mismatch such as `kiểm duyệt` and `moderation`.
46
- - It reports `followed`, `ignored`, and `unknown` outcomes after the task.
77
+ - Runtime history is isolated by project path and shared across supported agents.
78
+ - It reports what happened after the task instead of only hoping the agent remembered rules.
47
79
 
48
- ## Current Release Checks
80
+ ## Release Checks
49
81
 
50
- Run before recording:
82
+ Run before recording or posting:
51
83
 
52
84
  ```bash
53
85
  npm run validate:plugin
54
86
  npm test
55
87
  npm run test:mcp
56
88
  npm pack --dry-run
89
+ npm view @minhpnq1807/contextos version
57
90
  ```
package/LAUNCH.md ADDED
@@ -0,0 +1,93 @@
1
+ # ContextOS Launch Kit
2
+
3
+ ## Positioning
4
+
5
+ ContextOS fixes the practical problem where agents technically receive `AGENTS.md`, but task-critical rules are lost in the middle of a large context window.
6
+
7
+ One-line pitch:
8
+
9
+ ```text
10
+ ContextOS makes Codex, Claude Code, and Antigravity follow the right AGENTS.md rules by injecting task-relevant context before each task and reporting what was followed afterward.
11
+ ```
12
+
13
+ ## Hacker News
14
+
15
+ Title:
16
+
17
+ ```text
18
+ ContextOS - Codex ignores your AGENTS.md. This fixes it.
19
+ ```
20
+
21
+ Post:
22
+
23
+ ```text
24
+ I built ContextOS because I kept seeing agents miss important rules in AGENTS.md once the file got long.
25
+
26
+ The problem is not that agents cannot read the file. The problem is attention: the relevant rule is often buried in the middle of context.
27
+
28
+ ContextOS runs as native hooks plus a local MCP server. On each prompt it:
29
+
30
+ - scores AGENTS.md rules against the task
31
+ - injects the relevant rules at the start/end of the prompt context
32
+ - suggests likely files, skills, and workflows
33
+ - records runtime telemetry
34
+ - reports followed / ignored / unknown after the task
35
+
36
+ It supports Codex, Claude Code, and Antigravity. It is local-first and uses local MiniLM embeddings.
37
+
38
+ Install:
39
+
40
+ npm install -g @minhpnq1807/contextos && ctx setup
41
+
42
+ Repo: https://github.com/khovan123/contextOS
43
+ ```
44
+
45
+ ## X / Twitter
46
+
47
+ Short:
48
+
49
+ ```text
50
+ Codex can read AGENTS.md and still ignore the rule that matters.
51
+
52
+ ContextOS ranks rules per prompt, injects the important ones before work starts, then reports followed / ignored / unknown after the task.
53
+
54
+ npm install -g @minhpnq1807/contextos && ctx setup
55
+
56
+ https://github.com/khovan123/contextOS
57
+ ```
58
+
59
+ With GIF:
60
+
61
+ ```text
62
+ AGENTS.md is not enough when the important rule is buried in the middle.
63
+
64
+ ContextOS:
65
+ 1. scores rules against the prompt
66
+ 2. injects the relevant context
67
+ 3. suggests files/workflows
68
+ 4. reports what the agent followed
69
+
70
+ Demo below.
71
+ ```
72
+
73
+ ## GitHub Repo Description
74
+
75
+ ```text
76
+ Task-aware AGENTS.md context injection and compliance reports for Codex, Claude Code, and Antigravity.
77
+ ```
78
+
79
+ ## npm Description
80
+
81
+ ```text
82
+ Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.
83
+ ```
84
+
85
+ ## Launch Checklist
86
+
87
+ - [ ] README starts with problem, demo, install, before/after.
88
+ - [ ] Demo GIF or terminal clip recorded.
89
+ - [ ] `npm view @minhpnq1807/contextos version` matches latest tag.
90
+ - [ ] Fresh install tested in a separate project.
91
+ - [ ] GitHub repo description updated.
92
+ - [ ] HN post prepared.
93
+ - [ ] X post prepared with GIF.
package/README.md CHANGED
@@ -1,111 +1,155 @@
1
1
  # ContextOS
2
2
 
3
- ContextOS (`ctx`) is an agent companion for task-aware project context.
3
+ Codex ignores the middle of your `AGENTS.md`. ContextOS fixes that.
4
4
 
5
- It reads `AGENTS.md` guidance, scores the rules against the current prompt, suggests relevant files, records what context would have been injected, and reports lightweight compliance evidence after the task finishes.
5
+ It 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.
6
+
7
+ ```text
8
+ WITHOUT ContextOS
9
+ AGENTS.md is a long static blob
10
+ important rules drift into the middle
11
+ agent starts by grepping files and misses the repo contract
12
+
13
+ WITH ContextOS
14
+ prompt -> score relevant AGENTS.md rules
15
+ -> inject critical rules at top and bottom
16
+ -> suggest files, skills, workflows
17
+ -> report followed / ignored / unknown
18
+ ```
6
19
 
7
20
  Published package: [`@minhpnq1807/contextos`](https://www.npmjs.com/package/@minhpnq1807/contextos)
8
21
 
9
- ## Quick Start
22
+ ## Demo
23
+
24
+ ![ContextOS demo GIF placeholder](docs/contextos-demo-placeholder.svg)
25
+
26
+ Example hook context injected before the agent works:
27
+
28
+ ```text
29
+ ## Critical ContextOS rules
30
+ - IMPORTANT: This project has a knowledge graph. ALWAYS use code-review-graph MCP tools before Grep/Glob/Read.
31
+ - Use `query_graph` pattern="tests_for" to check coverage.
32
+
33
+ ## Suggested files to check
34
+ - services/content-service/test/unit/creator-only.policy.unit-spec.ts
35
+ - services/content-service/test/integration/resource-upload.integration-spec.ts
36
+
37
+ ## Suggested workflow for this task
38
+ - Primary Workflow: use for feature implementation, testing, review, and debugging
39
+ chain: planner -> tester -> code-reviewer
40
+ ```
41
+
42
+ After the task:
43
+
44
+ ```text
45
+ ContextOS report
46
+ Efficiency: 100%
47
+ Injected rules: 8
48
+ Rule outcomes: 8 followed, 0 ignored, 0 unknown
49
+ Runtime telemetry: code-review-graph, code-review-graph.query_graph_tool
50
+ ```
51
+
52
+ ## Install In One Line
10
53
 
11
54
  ```bash
12
- npm install -g @minhpnq1807/contextos
13
- ctx --version
14
- ctx setup
55
+ npm install -g @minhpnq1807/contextos && ctx setup
15
56
  ```
16
57
 
17
- `ctx setup` is the recommended first-run flow. It asks which agents to configure, whether prompt context injection should be enabled, whether to sync project rules/MCP through Ruler, and whether to sync skills through skillshare. It only runs when you explicitly invoke it; npm install does not run setup automatically.
58
+ No postinstall surprise: `npm install` only installs the CLI. Setup runs only when you call `ctx setup`.
18
59
 
19
- For scriptable installs, use:
60
+ Scriptable setup:
20
61
 
21
62
  ```bash
22
63
  ctx setup --yes
23
64
  ctx setup --yes --agents codex,claude,agy
24
65
  ```
25
66
 
26
- Restart your agent after setup, then use it normally. ContextOS runs through agent hooks and the `ctx-mcp` MCP server.
67
+ No global install:
27
68
 
28
- Codex-only install is still available:
69
+ ```bash
70
+ npm exec --yes --package=@minhpnq1807/contextos@latest -- ctx setup
71
+ npm exec --yes --package=@minhpnq1807/contextos@latest -- ctx-codex install
72
+ ```
73
+
74
+ Codex-only:
29
75
 
30
76
  ```bash
31
77
  ctx install
32
78
  ```
33
79
 
34
- Claude Code and Antigravity are supported through their native hook systems:
80
+ Claude Code and Antigravity:
35
81
 
36
82
  ```bash
37
83
  ctx install claude
38
84
  ctx install agy
39
85
  ```
40
86
 
41
- You can also run without a global install:
87
+ Restart the agent after setup. Then use the agent normally.
42
88
 
43
- ```bash
44
- npx @minhpnq1807/contextos@latest install
45
- npx @minhpnq1807/contextos@latest setup
46
- npx @minhpnq1807/contextos@latest install claude
47
- npx @minhpnq1807/contextos@latest install agy
48
- ```
89
+ ## Why
49
90
 
50
- ## Demo Flow
91
+ Developers 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.
51
92
 
52
- Use this flow for a 60-second demo recording:
93
+ The 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.
53
94
 
54
- ```bash
55
- ctx install
56
- codex
57
- ```
95
+ ## What ContextOS Does
58
96
 
59
- Prompt the agent:
97
+ | Layer | What happens |
98
+ | --- | --- |
99
+ | Hooks | Codex, Claude Code, and Antigravity hooks run before/after each task. |
100
+ | Scoring | Local MiniLM embeddings plus heuristics rank AGENTS.md rules by the prompt. |
101
+ | Injection | Critical rules are placed with primacy + recency, not buried in the middle. |
102
+ | Discovery | Relevant files, skills, and workflows are suggested before work starts. |
103
+ | Sync | Rules/MCP via Ruler, skills via skillshare, workflows via ContextOS. |
104
+ | Evidence | Stop hooks report `followed`, `ignored`, `unknown`, and runtime telemetry. |
60
105
 
61
- ```text
62
- Recheck authen flow
63
- ```
106
+ ## Quick Commands
64
107
 
65
- Expected result:
108
+ | Command | Use it for |
109
+ | --- | --- |
110
+ | `ctx setup` | Recommended first-run install flow. |
111
+ | `ctx debug -- "Recheck authen flow"` | Preview what ContextOS would inject. |
112
+ | `ctx report` | Show the last task's compliance summary. |
113
+ | `ctx evidence` | Show why each rule was marked followed/ignored/unknown. |
114
+ | `ctx stats` | Show workspace-level usage and effectiveness metrics. |
115
+ | `ctx benchmark -- "task"` | Compare raw AGENTS.md ordering vs ContextOS scheduling. |
116
+ | `ctx sync --rules` | Sync AGENTS/Ruler/MCP config across agents. |
117
+ | `ctx sync --skills` | Sync skills across agents through skillshare. |
118
+ | `ctx sync --workflows` | Sync workflow markdown across Claude/Codex/Antigravity. |
66
119
 
67
- - `UserPromptSubmit` injects relevant AGENTS.md rules.
68
- - ContextOS suggests auth/authentication files.
69
- - `Stop` prints a ContextOS report with rule outcomes.
70
- - `ctx evidence` shows the specific evidence behind the last report.
120
+ ## 60-Second Demo Script
71
121
 
72
- ## Before / After
122
+ 1. Start in a repo with an `AGENTS.md` that contains a rule like:
73
123
 
74
- Without ContextOS, Codex receives the full AGENTS.md context passively and can miss task-relevant rules in large context windows.
124
+ ```text
125
+ Always use code-review-graph MCP tools before reading files.
126
+ ```
75
127
 
76
- With ContextOS, each prompt gets a compact block:
128
+ 2. Install:
77
129
 
78
- ```text
79
- ## Critical ContextOS rules
80
- - Use code-review-graph before reading files.
81
- - Recheck authentication flow before editing auth code.
130
+ ```bash
131
+ npm install -g @minhpnq1807/contextos
132
+ ctx setup --yes --agents codex
133
+ ```
82
134
 
83
- ## Suggested files to check
84
- - services/auth-service/src/auth.controller.ts
85
- - services/auth-service/src/auth.service.ts
135
+ 3. Restart Codex and submit:
136
+
137
+ ```text
138
+ Recheck authen flow
86
139
  ```
87
140
 
88
- ## What It Does
141
+ 4. Show the injected `hook context`.
89
142
 
90
- - Hooks into Codex `UserPromptSubmit`, `SessionStart`, and `Stop`.
91
- - Hooks into Claude Code `UserPromptSubmit`, `SessionStart`, and `Stop`.
92
- - Hooks into Antigravity `PreInvocation` and `Stop` through the `agy` adapter.
93
- - Registers a `ctx-mcp` MCP server that owns model loading and semantic scoring.
94
- - Reads the active `AGENTS.md` chain for the current workspace.
95
- - Scores rules by relevance to the user prompt.
96
- - Scans project/global `.codex/skills`, `.claude/skills`, and Antigravity `.gemini/**/skills`, ranks skill descriptions by task relevance, and injects top skill hints.
97
- - Filters host/session setup rules such as "run commands as user X" or `sudo -u user` because they are environment instructions, not project guidance.
98
- - Finds likely relevant files with a hybrid retriever:
99
- - first, local prompt/file heuristics create seed candidates;
100
- - then, if `.code-review-graph/graph.db` exists, ContextOS queries `code-review-graph` semantic search and re-ranks graph-backed matches;
101
- - if no graph exists or graph lookup times out, it falls back to local heuristics.
102
- - Stores scheduled context and hook telemetry per workspace under `~/.ctx/contextos/workspaces/<workspace-id>`.
103
- - Reports rule outcomes as `followed`, `ignored`, or `unknown`, using runtime telemetry for tool/command rules when available.
104
- - Injects `additionalContext` into Codex by default.
143
+ 5. Let the task finish, then run:
105
144
 
106
- By default, ContextOS runs in injection mode. It adds task-relevant rules and files to the model context so the agent has the right project guidance at the moment it starts working.
145
+ ```bash
146
+ ctx report
147
+ ctx evidence
148
+ ```
107
149
 
108
- ## Install
150
+ 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.
151
+
152
+ ## Detailed Install
109
153
 
110
154
  From the package:
111
155
 
@@ -216,10 +260,12 @@ After this, `ctx debug -- "task"` and prompt hooks can suggest skills from `~/.c
216
260
 
217
261
  ## Workflow Discovery
218
262
 
219
- ContextOS can also index Claude/Codex workflow markdown files and suggest the right workflow for the current task:
263
+ ContextOS can also sync Claude/Codex/Antigravity workflow markdown files and suggest the right workflow for the current task:
220
264
 
221
265
  ```bash
222
266
  ctx sync --workflows
267
+ ctx sync --workflows --agents codex,claude,agy
268
+ ctx sync --workflows --dry-run
223
269
  ```
224
270
 
225
271
  It scans project workflows first, then global workflows:
@@ -239,6 +285,8 @@ It scans project workflows first, then global workflows:
239
285
 
240
286
  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.
241
287
 
288
+ `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.
289
+
242
290
  ## Modes
243
291
 
244
292
  Injection mode is the default:
@@ -384,7 +432,9 @@ This warning comes from a transitive dependency in the local embedding/WASM stac
384
432
  | `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. |
385
433
  | `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. |
386
434
  | `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`. |
387
- | `ctx sync --workflows` | Indexes agent workflow markdown files for prompt-time workflow suggestions. | You use `.claude/workflows/` or `.codex/workflows/` and want ContextOS to suggest the best workflow chain for each task. | Scans project/global workflow folders, parses headings and agent chain mentions, warms workflow embeddings, and makes `ctx debug`/prompt hooks show relevant workflow hints. |
435
+ | `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. |
436
+ | `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. |
437
+ | `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. |
388
438
  | `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`. |
389
439
  | `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. |
390
440
  | `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. |
package/bin/ctx.js CHANGED
@@ -63,6 +63,8 @@ Usage:
63
63
  ctx sync --rules --no-import-codex-mcp
64
64
  ctx sync --skills
65
65
  ctx sync --workflows
66
+ ctx sync --workflows --agents codex,claude,agy
67
+ ctx sync --workflows --dry-run
66
68
  ctx sync --skills --dry-run
67
69
  ctx sync --skills --no-collect
68
70
  ctx sync --skills --agents codex,claude,antigravity
@@ -571,7 +573,8 @@ try {
571
573
  await syncWorkflows({
572
574
  cwd: process.cwd(),
573
575
  dataDir: contextOSDataDir(),
574
- allowRemote: !isModelCacheReady(contextOSDataDir())
576
+ allowRemote: !isModelCacheReady(contextOSDataDir()),
577
+ args: args.slice(1)
575
578
  });
576
579
  } else if (args.includes("--skills")) {
577
580
  await syncSkills({
package/docs/contextos-demo-placeholder.svg ADDED
@@ -0,0 +1,25 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720" role="img" aria-labelledby="title desc">
2
+ <title id="title">ContextOS demo placeholder</title>
3
+ <desc id="desc">A terminal-style before and after preview for ContextOS.</desc>
4
+ <rect width="1280" height="720" fill="#101418"/>
5
+ <rect x="64" y="54" width="1152" height="612" rx="14" fill="#161c22" stroke="#303944"/>
6
+ <text x="96" y="105" fill="#f4f1e8" font-family="Inter, Arial, sans-serif" font-size="38" font-weight="700">ContextOS</text>
7
+ <text x="96" y="142" fill="#a7b0ba" font-family="Inter, Arial, sans-serif" font-size="20">Codex ignores the middle of AGENTS.md. ContextOS moves the right rules into the prompt.</text>
8
+
9
+ <rect x="96" y="190" width="520" height="356" rx="10" fill="#1d252d" stroke="#3a4552"/>
10
+ <text x="126" y="232" fill="#ffcf70" font-family="Inter, Arial, sans-serif" font-size="24" font-weight="700">Before</text>
11
+ <text x="126" y="278" fill="#cbd5df" font-family="SFMono-Regular, Consolas, monospace" font-size="18">AGENTS.md loaded as a long blob</text>
12
+ <text x="126" y="316" fill="#7f8b97" font-family="SFMono-Regular, Consolas, monospace" font-size="18">... rule buried in the middle ...</text>
13
+ <text x="126" y="354" fill="#e97979" font-family="SFMono-Regular, Consolas, monospace" font-size="18">agent starts with grep/read</text>
14
+ <text x="126" y="392" fill="#e97979" font-family="SFMono-Regular, Consolas, monospace" font-size="18">repo contract missed</text>
15
+
16
+ <rect x="664" y="190" width="520" height="356" rx="10" fill="#1d252d" stroke="#3a4552"/>
17
+ <text x="694" y="232" fill="#8ed8a3" font-family="Inter, Arial, sans-serif" font-size="24" font-weight="700">After</text>
18
+ <text x="694" y="278" fill="#cbd5df" font-family="SFMono-Regular, Consolas, monospace" font-size="18">prompt -&gt; score rules</text>
19
+ <text x="694" y="316" fill="#cbd5df" font-family="SFMono-Regular, Consolas, monospace" font-size="18">inject critical context</text>
20
+ <text x="694" y="354" fill="#8ed8a3" font-family="SFMono-Regular, Consolas, monospace" font-size="18">suggest files + workflow</text>
21
+ <text x="694" y="392" fill="#8ed8a3" font-family="SFMono-Regular, Consolas, monospace" font-size="18">report followed / ignored / unknown</text>
22
+
23
+ <rect x="96" y="588" width="1088" height="44" rx="8" fill="#0f151a" stroke="#303944"/>
24
+ <text x="120" y="616" fill="#f4f1e8" font-family="SFMono-Regular, Consolas, monospace" font-size="18">npm install -g @minhpnq1807/contextos &amp;&amp; ctx setup</text>
25
+ </svg>
package/package.json CHANGED
@@ -1,10 +1,11 @@
1
1
  {
2
2
  "name": "@minhpnq1807/contextos",
3
- "version": "0.5.11",
3
+ "version": "0.5.13",
4
4
  "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.",
5
5
  "type": "module",
6
6
  "bin": {
7
- "ctx": "bin/ctx.js"
7
+ "ctx": "bin/ctx.js",
8
+ "ctx-codex": "bin/ctx.js"
8
9
  },
9
10
  "files": [
10
11
  "bin/",
@@ -12,6 +13,8 @@
12
13
  ".agents/",
13
14
  "README.md",
14
15
  "DEMO.md",
16
+ "LAUNCH.md",
17
+ "docs/",
15
18
  "LICENSE",
16
19
  "CHANGELOG.md"
17
20
  ],
package/plugins/ctx/lib/workflow-discoverer.js CHANGED
@@ -8,6 +8,7 @@ const DEFAULT_LIMIT = 2;
8
8
  const MIN_WORKFLOW_BYTES = 100;
9
9
  const MAX_DESCRIPTION_CHARS = 500;
10
10
  const DEFAULT_EMBEDDING_CANDIDATES = 40;
11
+ const DEFAULT_SYNC_AGENTS = ["claude", "codex", "agy"];
11
12
  const KNOWN_AGENT_NAMES = new Set([
12
13
  "planner",
13
14
  "tester",
@@ -42,6 +43,29 @@ export function workflowSearchRoots({ cwd = process.cwd(), home = os.homedir() }
42
43
  ];
43
44
  }
44
45
 
46
+ export function workflowGlobalRoots({ home = os.homedir(), agents = DEFAULT_SYNC_AGENTS } = {}) {
47
+ const normalizedAgents = parseWorkflowAgents(agents);
48
+ const roots = [];
49
+ if (normalizedAgents.includes("claude")) roots.push(path.join(home, ".claude", "workflows"));
50
+ if (normalizedAgents.includes("codex")) roots.push(path.join(home, ".codex", "workflows"));
51
+ if (normalizedAgents.includes("agy")) {
52
+ roots.push(path.join(home, ".gemini", "workflows"));
53
+ roots.push(path.join(home, ".gemini", "antigravity", "workflows"));
54
+ roots.push(path.join(home, ".gemini", "antigravity-cli", "workflows"));
55
+ }
56
+ return roots;
57
+ }
58
+
59
+ export function parseWorkflowAgents(value = DEFAULT_SYNC_AGENTS) {
60
+ const raw = Array.isArray(value) ? value : String(value || "").split(",");
61
+ const agents = raw
62
+ .map((agent) => String(agent || "").trim().toLowerCase())
63
+ .map((agent) => agent === "antigravity" ? "agy" : agent)
64
+ .filter(Boolean);
65
+ const known = agents.filter((agent) => DEFAULT_SYNC_AGENTS.includes(agent));
66
+ return [...new Set(known.length ? known : DEFAULT_SYNC_AGENTS)];
67
+ }
68
+
45
69
  export function scanWorkflows({ cwd = process.cwd(), roots = workflowSearchRoots({ cwd }) } = {}) {
46
70
  const workflows = [];
47
71
  const seen = new Set();
@@ -148,20 +172,67 @@ export async function syncWorkflows({
148
172
  cwd = process.cwd(),
149
173
  dataDir,
150
174
  allowRemote = true,
175
+ args = [],
176
+ home = os.homedir(),
151
177
  logger = console.log
152
178
  } = {}) {
153
- const workflows = scanWorkflows({ cwd });
154
- logger("ContextOS workflow index");
155
- logger(`Found workflows: ${workflows.length}`);
179
+ const options = parseSyncWorkflowArgs(args);
180
+ const agents = parseWorkflowAgents(options.agents);
181
+ const workflows = scanWorkflows({ cwd, roots: workflowSearchRoots({ cwd, home }) });
182
+ const targets = workflowGlobalRoots({ home, agents });
183
+
184
+ logger("ContextOS workflow sync");
185
+ logger(`Agents: ${agents.join(", ")}`);
186
+ logger(`Found unique workflows: ${workflows.length}`);
156
187
  if (workflows.length) {
157
188
  for (const workflow of workflows) {
158
189
  logger(`- ${workflow.relativePath || workflow.path} (${workflow.chain.join(" -> ") || "no chain"})`);
159
190
  }
160
191
  }
192
+ const syncResult = syncWorkflowFiles({ workflows, targets, dryRun: options.dryRun, logger });
161
193
  const result = await warmWorkflowEmbeddings({ cwd, dataDir, allowRemote, workflows });
194
+ logger(`Synced workflows: ${syncResult.copied}${options.dryRun ? " planned" : ""}`);
195
+ logger(`Skipped duplicates: ${syncResult.duplicates}`);
162
196
  logger(`Indexed workflows: ${workflows.length}`);
163
197
  if (result.cachePath) logger(`Cache: ${result.cachePath}`);
164
- return { workflows, embeddings: result };
198
+ return { workflows, embeddings: result, sync: syncResult };
199
+ }
200
+
201
+ function parseSyncWorkflowArgs(args = []) {
202
+ const agentsFlag = args.indexOf("--agents");
203
+ return {
204
+ agents: agentsFlag >= 0 ? args[agentsFlag + 1] : DEFAULT_SYNC_AGENTS,
205
+ dryRun: args.includes("--dry-run")
206
+ };
207
+ }
208
+
209
+ function syncWorkflowFiles({ workflows = [], targets = [], dryRun = false, logger = console.log } = {}) {
210
+ let copied = 0;
211
+ let duplicates = 0;
212
+ const seenNames = new Set();
213
+ for (const workflow of workflows) {
214
+ if (seenNames.has(workflow.name)) {
215
+ duplicates += 1;
216
+ continue;
217
+ }
218
+ seenNames.add(workflow.name);
219
+ for (const targetRoot of targets) {
220
+ const targetPath = path.join(targetRoot, `${workflow.name}.md`);
221
+ const sourceRealPath = safeRealpath(workflow.path) || path.resolve(workflow.path);
222
+ const targetRealPath = safeRealpath(targetPath) || path.resolve(targetPath);
223
+ if (sourceRealPath === targetRealPath) continue;
224
+ if (!dryRun) {
225
+ fs.mkdirSync(targetRoot, { recursive: true });
226
+ fs.copyFileSync(workflow.path, targetPath);
227
+ }
228
+ copied += 1;
229
+ }
230
+ }
231
+ if (targets.length) {
232
+ logger(`Target roots: ${targets.length}`);
233
+ for (const target of targets) logger(` -> ${target}`);
234
+ }
235
+ return { copied, duplicates, targets: targets.length };
165
236
  }
166
237
 
167
238
  function stripFrontmatter(content) {