@minhpnq1807/contextos 0.5.12 → 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 (6) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/DEMO.md +46 -13
  3. package/LAUNCH.md +93 -0
  4. package/README.md +107 -63
  5. package/docs/contextos-demo-placeholder.svg +25 -0
  6. package/package.json +5 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
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
+
3
9
  ## 0.5.12
4
10
 
5
11
  - Makes `ctx sync --workflows` synchronize unique workflow files to global Claude, Codex, and Antigravity workflow roots.
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:
68
+
69
+ ```bash
70
+ npm exec --yes --package=@minhpnq1807/contextos@latest -- ctx setup
71
+ npm exec --yes --package=@minhpnq1807/contextos@latest -- ctx-codex install
72
+ ```
27
73
 
28
- Codex-only install is still available:
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
90
+
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.
92
+
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.
94
+
95
+ ## What ContextOS Does
96
+
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. |
105
+
106
+ ## Quick Commands
107
+
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. |
119
+
120
+ ## 60-Second Demo Script
121
+
122
+ 1. Start in a repo with an `AGENTS.md` that contains a rule like:
49
123
 
50
- ## Demo Flow
124
+ ```text
125
+ Always use code-review-graph MCP tools before reading files.
126
+ ```
51
127
 
52
- Use this flow for a 60-second demo recording:
128
+ 2. Install:
53
129
 
54
130
  ```bash
55
- ctx install
56
- codex
131
+ npm install -g @minhpnq1807/contextos
132
+ ctx setup --yes --agents codex
57
133
  ```
58
134
 
59
- Prompt the agent:
135
+ 3. Restart Codex and submit:
60
136
 
61
137
  ```text
62
138
  Recheck authen flow
63
139
  ```
64
140
 
65
- Expected result:
66
-
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.
71
-
72
- ## Before / After
141
+ 4. Show the injected `hook context`.
73
142
 
74
- Without ContextOS, Codex receives the full AGENTS.md context passively and can miss task-relevant rules in large context windows.
143
+ 5. Let the task finish, then run:
75
144
 
76
- With ContextOS, each prompt gets a compact block:
145
+ ```bash
146
+ ctx report
147
+ ctx evidence
148
+ ```
77
149
 
78
- ```text
79
- ## Critical ContextOS rules
80
- - Use code-review-graph before reading files.
81
- - Recheck authentication flow before editing auth code.
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.
82
151
 
83
- ## Suggested files to check
84
- - services/auth-service/src/auth.controller.ts
85
- - services/auth-service/src/auth.service.ts
86
- ```
87
-
88
- ## What It Does
89
-
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.
105
-
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.
107
-
108
- ## Install
152
+ ## Detailed Install
109
153
 
110
154
  From the package:
111
155
 
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.12",
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
  ],