https://github.com/krablante/pitlane-codex-plugin
Pitlane PreToolUse hook for token-efficient Codex code navigation
https://github.com/krablante/pitlane-codex-plugin
code-navigation codex codex-plugin developer-tools pitlane
Last synced: 1 day ago
JSON representation
Pitlane PreToolUse hook for token-efficient Codex code navigation
- Host: GitHub
- URL: https://github.com/krablante/pitlane-codex-plugin
- Owner: Krablante
- License: mit
- Created: 2026-05-15T23:03:38.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-17T21:04:45.000Z (24 days ago)
- Last Synced: 2026-06-17T23:08:19.408Z (24 days ago)
- Topics: code-navigation, codex, codex-plugin, developer-tools, pitlane
- Language: Python
- Size: 39.1 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
pitlane-codex-plugin
Keep Codex code navigation compact by routing safe source reads through Pitlane.
A small Codex-compatible PreToolUse plugin for token-efficient source browsing, symbol search, and repo outlines.
Install
·
Compatibility
·
Stack Fit
`pitlane-codex-plugin` adds a code-navigation `PreToolUse` hook for
Codex-compatible runtimes. It rewrites only narrow, safe shell reads into
host-local `pitlane` CLI calls:
- source `cat`, `head`, and simple `sed -n A,Bp` reads become `pitlane lines`;
- simple symbol-looking `rg`, recursive `grep`, `ls -R`, and `tree` commands
become Pitlane search or outline calls when the project has a Pitlane index,
with a cheap auto-index attempt for safe local worktrees;
- missed source-navigation opportunities, including broad `find` and
`git grep` shapes, can emit a small hint while leaving the original command
unchanged; compact telemetry for these misses is opt-in;
- exact-output, regex-like search, machine-readable, build, test, Docker, SSH,
data, and shell-control commands pass through unchanged.
There is no sidecar, container, SSH, wrapper, or gateway fallback path. If a
host-local `pitlane` executable is not available, the hook silently leaves the
original shell command alone.
## Part of the Codez stack
The Codez stack is modular. Each layer can be used on its own unless a higher
layer explicitly opts into it.
| Layer | Public surface | Responsibility | Dependency |
| --- | --- | --- | --- |
| [Codez](https://github.com/Krablante/codez) | Codex-compatible runtime | App Server v2, goal RPC, long-session hardening, prompt pruning, and plugin hooks | Does not require Teledex |
| [RTK Codex Plugin](https://github.com/Krablante/rtk-codex-plugin) | Optional Codex plugin | Shell/token safety through `rtk rewrite` and bounded output guarding | Requires a Codex-compatible plugin-hook runtime; does not require Teledex |
| [Pitlane Codex Plugin](https://github.com/Krablante/pitlane-codex-plugin) | Optional Codex plugin | Code-navigation/token-saving rewrites through a host-local `pitlane` CLI | Requires a Codex-compatible plugin-hook runtime and local `pitlane`; does not require Teledex |
| [Teledex](https://github.com/Krablante/teledex) | Telegram gateway/session layer | Topics, queues, live steer, `/goal` UX, and delivery/recovery around durable agent sessions | Full mode is optimized for Codez App Server v2; upstream `codex exec --json` is legacy compatibility only |
When RTK and Pitlane are both enabled, load RTK before Pitlane. RTK handles
general shell-output safety; Pitlane then wins only for the narrow
code-navigation commands it accepts.
## Why People Use It
- avoid dumping large source files into the model context for routine browsing
- replace broad source reads with bounded `pitlane lines`
- turn simple symbol and listing exploration into indexed Pitlane navigation
- keep exact output intact for tests, builds, JSON, Docker, SSH, and automation
- install as a small plugin instead of changing shell habits by hand
## Quick Start
Clone the plugin into the plugin cache used by your Codex-compatible runtime.
One common GitHub cache layout looks like this:
```bash
codex_home="${CODEX_HOME:-$HOME/.codex}"
git clone https://github.com/Krablante/pitlane-codex-plugin \
"$codex_home/plugins/cache/github/pitlane-codex-plugin/local"
```
Enable plugin hooks and the plugin key that matches your install location:
```toml
[features]
plugins = true
plugin_hooks = true
[plugins."pitlane-codex-plugin@github"]
enabled = true
```
Put `pitlane` in `PATH`, index a project, and run the focused test suite:
```bash
pitlane --version
pitlane index /path/to/project
make test
```
Read next:
- [Install](./docs/install.md)
- [Compatibility](./docs/compatibility.md)
- [Stack Fit](./docs/stack.md)
## Notes
- `pitlane` is required for rewrites; without it, the hook passes through.
- symbol and outline rewrites require a ready Pitlane index; safe local
worktrees can be auto-indexed with a short timeout.
- the plugin is intentionally shell-hook-only; gateway/session behavior belongs
in higher-level tools.