YeonGyu-Kim
659342d627
Rewrite # Task Tracking from a single soft paragraph to a strict
update_plan covenant: mandatory for any 2+ step work, exactly one
in_progress, no batched completions, plan closure required, promise
discipline (do not commit to follow-up work you will not finish in
this turn). Pins the {step, status} schema with the pending /
in_progress / completed enum, and adds the explicit failure-mode
verdict that improvising past step 2 without an update_plan call is
itself a defect.
Add # Subagents section documenting that Codex's spawn_agent returns
immediately, runs in parallel, and should be fired 2-5 at a time via
multi_tool_use.parallel for independent investigations. Names the four
bundled roles (explorer / librarian / plan / codex-ultrawork-reviewer),
pins the four-field CONTEXT / GOAL / DOWNSTREAM / REQUEST spawn prompt
template, and instructs the model to call wait_agent sparingly only
when the next critical-path step is strictly blocked.
Compress the three repeated 'omo-codex LSP MCP diagnostics tool
(auto-runs on every edit via the lsp component, but you may also
invoke it explicitly)' phrasings to plain lsp_diagnostics, with the
auto-inject context defined once in # Parallelize aggressively. Saves
about 290 chars and defends the new sections' growth per the
prompt-engineering entropy gate.
The Hephaestus baseline is now 16578 chars; the prior 14627-char
version was already being silently truncated by the per-rule cap.
That truncation is fixed in the companion commit that bypasses the
cap for plugin-bundled rules, so the full discipline now lands on
every Codex session.
codex-rules
Codex plugin that injects local project rule files into model context through lifecycle hooks.
It ports the pi-rules rule injector to Codex:
SessionStartandUserPromptSubmitload static project instructions once per session.PostToolUsewatches Codexapply_patchby default, then injects matching file-specific rules as additional context.PostCompactclears the per-session injection cache after manual or automatic compaction so relevant rules can be reintroduced into the compacted conversation.- Session-level deduplication prevents the same rule from being repeated after it has been injected.
PostToolUse output is context-only: it emits hookSpecificOutput.additionalContext and does not rewrite tool output.
The runtime has no npm production dependencies, so a clean Codex marketplace copy can run without a follow-up npm install.
Rule Sources
Project-level sources:
AGENTS.mdCLAUDE.mdCONTEXT.md.omo/rules/**/*.md.claude/rules/**/*.md.cursor/rules/**/*.md.github/instructions/**/*.md.github/copilot-instructions.md
User-home sources are also supported by the ported engine when available.
Markdown rule files may use frontmatter such as:
---
description: TypeScript defaults
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---
Prefer strict TypeScript and keep runtime imports ESM-compatible.
Install Locally
From the marketplace workspace:
codex plugin marketplace add /Users/yeongyu/local-workspaces/codex-plugins
node /Users/yeongyu/local-workspaces/codex-plugins/scripts/install-local.mjs /Users/yeongyu/local-workspaces/codex-plugins
The local installer builds the plugin and copies a clean cache entry to:
~/.codex/plugins/cache/code-yeongyu-codex-plugins/omo/0.1.0
It also enables:
[features]
plugins = true
plugin_hooks = true
[plugins."omo@code-yeongyu-codex-plugins"]
enabled = true
Configuration
Use CODEX_RULES_* environment variables:
| Variable | Values | Default |
|---|---|---|
CODEX_RULES_DISABLED |
1, true, yes, on |
unset |
CODEX_RULES_MODE |
both, static, dynamic, off |
both |
CODEX_RULES_MAX_RULE_CHARS |
positive integer | 12000 |
CODEX_RULES_MAX_RESULT_CHARS |
positive integer | 40000 |
CODEX_RULES_ENABLED_SOURCES |
comma-separated source names | auto |
For migration from pi-rules, equivalent PI_RULES_* variables are accepted as fallbacks.
Debugging
Enable hook phase timing with NODE_DEBUG=codex-rules:
NODE_DEBUG=codex-rules node dist/cli.js hook post-tool-use < fixture.json
Debug lines go to stderr and hook JSON stays on stdout. The log includes PostToolUse phases such as extract, fingerprint, load, persist, elapsed ms, target counts, pending counts, rule counts, and output bytes. It does not log rule bodies or tool response contents.
The default PostToolUse hook matcher is intentionally strict: it matches only Codex's canonical apply_patch hook tool name. Read tools, MCP filesystem tools, shell commands, and Claude-style Write/Edit aliases are not registered by default.
Development
npm install
npm test
npm run check
npm run typecheck
npm pack --dry-run
Performance smoke test:
npm run bench
Benchmark timings depend on the local machine. Use the relative counters and repeat-output checks when comparing runs.
Hook smoke test:
npm run build
printf '%s\n' '{"session_id":"s","transcript_path":null,"cwd":"/path/to/project","hook_event_name":"SessionStart","model":"gpt-5.5","permission_mode":"default","source":"startup"}' \
| PLUGIN_DATA=/tmp/codex-rules-data node dist/cli.js hook session-start
Privacy
codex-rules runs locally. It reads local rule files and Codex hook payloads, writes per-session deduplication state under the Codex plugin data directory, and does not make network requests.