@ascenda-one/codex-hooks 0.1.28 → 0.1.34

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.
package/README.md CHANGED
@@ -4,16 +4,21 @@ OpenAI Codex hooks adapter for Ascenda AI workload telemetry.
4
4
 
5
5
  Part of [ai-engineer-tools](../). Event mapping: [docs/CODEX_MAPPING.md](./docs/CODEX_MAPPING.md). Codex hooks reference: [developers.openai.com/codex/hooks](https://developers.openai.com/codex/hooks).
6
6
 
7
- ## Role in workload detection
7
+ ## What it sends
8
8
 
9
- Third agent producer after the IDE extensions and [Claude Code hooks](../ascenda-claude-code-hooks/). Contributes the same AI interaction load signals — prompts, correction loops, tool calls, verification runs, compaction pressure, long agent turns — from Codex sessions, into the shared canonical event catalog.
9
+ Metadata only. It doesn't send prompts, responses, code, file names,
10
+ repository names, branch names or terminal output. [Privacy defaults](#privacy-defaults)
11
+ has the detail.
10
12
 
11
- | Workload input | How this adapter contributes |
13
+ It records the same signals as the [Claude Code hooks](../ascenda-claude-code-hooks/),
14
+ from Codex sessions:
15
+
16
+ | Signal | What the hook records |
12
17
  | --- | --- |
13
- | AIInteractionLoad | Prompts, tool calls, correction loops, compaction |
14
- | FocusDuration | Session starts, long turns (`agent_loop_long`, measured locally) |
15
- | Workflow friction | Tool failures, context pressure |
16
- | Verification load | shell test/lint/build → `editor_verification_activity` / `compile_error` |
18
+ | Agent interaction | That a prompt, correction loop or compaction happened, and for each tool call the tool's name (`shell`, `apply_patch`) |
19
+ | Long agent runs | Session starts, and that a turn ran long (`agent_loop_long`, measured locally) |
20
+ | Friction | Tool failures and context pressure |
21
+ | Verification | A test, lint or build command ran (`editor_verification_activity` / `compile_error`) |
17
22
 
18
23
  Identity: Codex rides the canonical `cli_agent` toolType/source (the backend registry has no codex value yet); events carry `metadata.host: "codex"` for later disaggregation.
19
24
 
@@ -33,7 +38,7 @@ Codex **awaits** command hooks and treats **exit code 2 as blocking** the user's
33
38
  One command pairs Codex, installs the hook binary, and registers the hooks:
34
39
 
35
40
  ```bash
36
- npx -y @ascenda-one/codex-hooks setup --scope user
41
+ npx -y @ascenda-one/codex-hooks setup
37
42
  ```
38
43
 
39
44
  It prints a 6-digit code — confirm it in the Ascenda app under
@@ -48,23 +53,29 @@ credentials file, which is per agent — so pairing Codex cannot disturb a
48
53
  Claude Code or Cursor pairing on the same machine, and a Codex hook launched
49
54
  from the Dock with an empty environment still names itself correctly.
50
55
 
51
- `--scope user` registers machine-wide. Omit it and hooks land in
52
- `<cwd>/.codex/hooks.json`, instrumenting that project only — which is the
53
- default, so pass the flag unless you mean one repo.
56
+ Hooks register machine-wide by default. `--scope project` puts them in
57
+ `<cwd>/.codex/hooks.json` instead, for that project only. Each hook runs
58
+ through a small launcher at `~/.ascenda/bin/ascenda-codex-hook` that finds
59
+ Node 20 or newer itself, so hooks keep working when Codex starts without
60
+ your shell's PATH. `--no-pair` installs without pairing: the screen saver
61
+ and live view work, and nothing is sent.
54
62
 
55
63
  ### 2. Check it
56
64
 
57
65
  ```bash
58
- npx @ascenda-one/codex-hooks status --scope user
66
+ npx @ascenda-one/codex-hooks status
67
+ ~/.ascenda/bin/ascenda-codex-hook doctor
59
68
  ```
60
69
 
61
- Names the pairing, the binary and how many of the 7 events are registered.
62
- Exits non-zero when something is missing, so it can gate a CI step.
70
+ `status` names the pairing, the Node the hooks will run, the last hook Codex
71
+ ran and how many events are registered. It exits non-zero when something is
72
+ missing, so it can gate a CI step. `doctor` also checks the live signal, and
73
+ pings the Waterline screen saver when it is running.
63
74
 
64
75
  To undo everything it wrote:
65
76
 
66
77
  ```bash
67
- npx @ascenda-one/codex-hooks uninstall --scope user
78
+ npx @ascenda-one/codex-hooks uninstall
68
79
  ```
69
80
 
70
81
  ### 3. Restart Codex and review hooks