At a glance · A personal tool-building project. I took features I found useful in the pi coding agent and the Qoder desktop app and CLI, and brought them to OpenAI Codex as add-on hooks, MCP servers and skills. Everything is additive: nothing is installed unless you copy it in.
| Component | What it adds | Count |
|---|---|---|
| Hooks | Shell-command rewriting (RTK), code-quality reminders, a static security check, and a pre-push security scan | 3 Codex hooks + 1 git hook |
| MCP servers | Knowledge-base wiki and warm-cache security scanning (built for this kit), plus setup for the third-party pi-lens code-quality server (16 tools) | 2 built + 1 integrated |
| Skills | Review, TDD, security audit, simplification and more | 20 (8 adapted from open-source projects, credited) |
Status (Oct 2026): several of these features now ship as official extensions, so the kit mainly documents the approach. Each part keeps its own install, verification and rollback steps.
Version: 1.2.0 — semver: each feat: → minor bump; breaking changes → major bump.
Portable, additive Codex enhancement kit migrated from the pi coding agent. Gives OpenAI Codex the same code-tightening, code-quality, and token-saving behavior — with zero linkage to ~/.pi and no forced installation.
Everything here is self-serve: browse the directory you need, follow its README, copy-paste. Nothing modifies your existing Codex environment unless you explicitly add it.
| I want... | Go to | What to do |
|---|---|---|
| Token-saving shell rewrites (RTK) + code-quality reminders | hooks/ |
Copy .mjs files to ~/.codex/hooks/, add entries to hooks.json |
| pi-lens code-quality MCP server (16 tools) | mcp-servers/ |
npm install, paste TOML block into config.toml |
| Review / TDD / security / simplification skills | skills/ |
Copy skill folders to ~/.cc-switch/skills/ or ~/.codex/skills/ |
Each directory has its own README with step-by-step instructions, verification, and rollback.
- Node.js on PATH (v18+)
- git on PATH
- rtk binary on PATH or
~/.local/bin/rtk[.exe](for the RTK hook only; override withRTK_BIN) - cc-switch (optional, for skill distribution + cloud sync)
pi-codex-kit/
├── README.md ← this file
├── .gitignore
├── hooks/
│ ├── README.md ← install instructions
│ ├── rtk-pretooluse.mjs ← PreToolUse: rewrites shell cmds via rtk
│ ├── lens-reminder.mjs ← PostToolUse: nudges pi-lens analysis
│ ├── security-l1.mjs ← PostToolUse: L1 static security check
│ └── pre-push ← git hook: L3 semgrep scan before push
├── mcp-servers/
│ ├── README.md ← server catalog + install
│ ├── SECURITY.md ← trust-boundary vetting (pi-lens)
│ ├── wiki-server/ ← persistent knowledge-base (SQLite + embeddings)
│ └── semgrep-server/ ← warm-cache security scanning
└── skills/
├── README.md ← skill catalog + install instructions
├── simplify/
├── audit-code/
├── develop-tdd/
└── ... (20 skills total)
Optional: append the section below to your
AGENTS.md(e.g. via cc-switch prompt manager) so the agent knows how to use this kit. Do not replace existing AGENTS.md content.
This environment has standalone tooling that keeps generated code tight and future-proof while saving tokens. Use it as follows:
- Shell commands are transparently rewritten through RTK (Rust Token Killer) by a PreToolUse hook — e.g.
git statusruns asrtk git statuswith compact output. No action needed; just be aware command output is deliberately condensed. - For deliberately large raw output, prefix a command with
RTK_DISABLED=1.
- pi-lens runs entirely locally — file contents never leave your machine. See
mcp-servers/SECURITY.mdfor the full trust boundary. - After modifying source files, run the pi-lens MCP tool
pilens_analyzeon each changed file before declaring a task done, and resolve any blocking diagnostics it reports. - For broader checks use
pilens_diagnostics(session/project diagnostic state) andpilens_project_scan(cheap project-wide scan). - At the start of a substantial coding session, consider
pilens_session_startto baseline diagnostics;pilens_turn_endaggregates incremental findings. - For structural search/refactor use
pilens_ast_grep_search/pilens_ast_grep_replace; for type-level navigation usepilens_lsp_navigationandpilens_lsp_diagnostics.
- Before finishing a coding task or committing, run the
simplifyskill on the current diff. It scopes review to changed lines only. - Apply its principles: preserve functionality (tests must pass), follow this project's conventions, enhance clarity (reduce complexity/nesting, kill redundancy, better names, no nested ternaries), and maintain balance (readability over fewer lines; don't over-simplify or remove helpful abstractions).
Aligned with Qoder Security tiers:
| Tier | Mechanism | When | Cost |
|---|---|---|---|
| L1 Static Check | hooks/security-l1.mjs (PostToolUse) |
Automatically after every code edit | Near-zero (regex) |
| L2 Lightweight Scan | security-gate skill (agent-elicited) |
End of coding task | Low (semgrep diff-scoped) |
| L3 Deep Scan | hooks/pre-push + security-gate skill |
Before push/deploy | Medium (semgrep cross-file) |
- L1 fires automatically — catches eval, hardcoded secrets, SQL injection, XSS, disabled TLS.
- L2 is recommended at task end — the agent (or lens-reminder hook) nudges when appropriate.
- L3 blocks
git pushon HIGH findings — bypass withgit push --no-verify.
- Prefer small, single-responsibility functions with descriptive names.
- Delete dead code and redundant abstractions rather than commenting them out.
- Keep comments that explain why (design rationale, business rules, non-obvious behavior); remove noise comments that restate the code.
- Do not change public APIs or refactor outside the scope of the current task unless explicitly asked.
| Check | Pass criterion |
|---|---|
| RTK hook | echo '{"tool_name":"Bash","tool_input":{"command":"git status"}}' | node ~/.codex/hooks/rtk-pretooluse.mjs → prints updatedInput.command = "rtk git status" |
| pi-lens MCP | Codex /mcp shows pi-lens connected with 16 tools |
| config integrity | diff config.toml vs its backup → only the [mcp_servers.pi-lens] block added |
| skills | Codex /skills lists your installed skills; $simplify on a dirty tree runs scoped review |
| no pi linkage | no ~/.pi references anywhere in ~/.codex/ |
- Pre-existing
~/.codex/config.tomlparse error (not caused by this kit): line ~137review_model = "gpt-5.6-sol"— Codex CLI0.130.0-alpha.5expects a struct (AgentRoleToml) there, socodex mcp list/addfails. Use the manual TOML append described inmcp-servers/README.mdinstead of thecodex mcpCLI. - rtk has no native Codex hook yet in any stable release (PRs #2198/#2234/#2973 open). The custom
rtk-pretooluse.mjsfills the gap; when a stablertk hook codexships, swap the onehooks.jsoncommand.
This kit adapts and builds upon the following works:
| Component | Author / Source | License | What we adapted |
|---|---|---|---|
| pi-lens MCP server | Apostolos Mantzaris | MIT | Code-quality MCP integration (16 tools), hook reminder pattern |
| LLM Wiki pattern | Andrej Karpathy | Public gist | Wiki architecture (raw/wiki/schema layers, ingest/query/lint operations) |
| RTK (Rust Token Killer) | rtk-ai/rtk | Apache-2.0 | Token-saving shell rewrite concept, PreToolUse hook pattern |
| Deep modules / interface design | John Ousterhout, A Philosophy of Software Design | — | Vocabulary and principles in deepen-architecture and develop-tdd |
| Seam / working effectively | Michael Feathers, Working Effectively with Legacy Code | — | Seam concept in deepen-architecture |
| Clean Code heuristics (Ch 17) | Robert C. Martin, Clean Code | — | Audit checklist heuristics in audit-code |
| F.I.R.S.T test rubric | Tim Ottinger & Jeffrey Langr (via Uncle Bob) | — | Test quality enforcement in enforce-first |
| Semgrep | Semgrep / r2c | LGPL-2.1 | Security scanning engine wrapped by semgrep-server |
| transformers.js | Xenova / HuggingFace | Apache-2.0 | Local embedding model runtime for wiki-server |
| all-MiniLM-L6-v2 | Sentence-Transformers | Apache-2.0 | 384-dim embedding model for wiki vector search |
| differential-review, fp-check, variant-analysis skills | Trail of Bits | CC BY-SA 4.0 | Skill text and reference files (partly copied; folders keep CC BY-SA 4.0) |
| code-reviewer skill | Google Gemini CLI | Apache-2.0 | Skill copied unchanged |
| pi-lens-* skills | Apostolos Mantzaris | MIT | Four authoring and navigation skills, edited to use the MCP tools |
| Codebase-design and TDD skills | Matt Pocock | MIT | Module/interface/seam vocabulary and mocking examples in deepen-architecture and develop-tdd |
| Semver versioning convention | bigpowers by Daniel V. | — | Version policy (feat → minor, breaking → major, MVP → 1.0.0) |
| TDD vertical slices | Kent Beck, Test-Driven Development: By Example | — | Red-green-refactor workflow in develop-tdd |
The hooks, wiki-server, semgrep-server and 12 of the 20 skills were written for this kit. Eight skills are copied or closely adapted from the projects above and keep their original licenses; see THIRD_PARTY_NOTICES.md and the NOTICE.md in each of those folders. Ideas taken from the books are paraphrased, not copied.
context-mode, pi-subagents, pi-dynamic-workflows, pi-hermes-memory, pi-permission-system — pi-internal APIs with no clean Codex equivalent.
My own code and documentation are licensed under the MIT license. Folders adapted from other projects keep their original licenses: CC BY-SA 4.0 (differential-review, fp-check, variant-analysis), Apache-2.0 (code-reviewer) and MIT with the original copyright (pi-lens-*; parts of deepen-architecture and develop-tdd). See THIRD_PARTY_NOTICES.md.