PIDEX

PIDEX is my personal LLM pipeline automation project. To be clear, I am heavily assisted by LLMs while building it, and I have invested most of my time over the last months trying to improve every aspect. It is experimental, constantly changing, and shaped by lessons learned from real local projects. The LLM world moves fast, and I try to filter what is worth trying and what is not. The number of new tools and open-source projects emerging every day is enormous; no one can try everything, so deciding what to test is not easy. PIDEX is my way of trying ideas directly, measuring what happens, and keeping the parts that seem to help.

Metrics are a useful way to test what works and what does not, so PIDEX includes a local dashboard for pipeline state, quality signals, provider usage, and project context. PIDEX also follows the LLM Wiki direction: durable project knowledge should be explicit, reviewable, and close to the source instead of hidden behind opaque retrieval machinery. I tried RAG too, but for this project I prefer fewer dependencies and more explicit context.

The pipeline is self-improving through rules. Every project can split refinements into global PIDEX rules and project-specific rules. If you have refinements you think would help, feel free to add them in a PR.

Like many devs, I was initially driven by the excitement of creating things with little effort. Over time, that feeling had to give way to a more disciplined process, so most of the refinement now happens at the user-llm level. Having an orchestrator question you in detail is the most important step. You can use the grill-me or grill-with-docs skill for that, or rely on the predefined orchestrator instructions.

Current status

PIDEX is an experimental direct-mode MVP. Direct mode is the supported path today.

The main active work is PIDEX’s self-improvement loop: collecting quality evidence from real pipeline runs, improving PDQ reports, and using those signals to decide which rules, prompts, and workflow changes actually help. Quality Rule Learning is now in validation/hardening: PDQ reports include operator contracts, valid operator-decision evidence, trace normalization, dashboard quality views, and a disabled-by-default background contract governor for local expectation corrections. The next memory-hygiene work is being shaped as PDQ-adjacent operational-memory consistency checks, not as a separate autonomous cleanup loop.

Detailed feature docs

More detailed documentation for complex features lives in readme/:

• Dashboard
• Provider limits and profiles
• Global Git security hook
• Wiki hygiene
• Optional parallel agents
• Automatic quality reports
• Quality governance
• PIDEX modules
• Project session memory
• Project context
• Windows status

Project/process docs:

• Security policy
• Contributing
• Changelog

Prerequisites

PIDEX currently supports Linux/direct mode and includes experimental Windows bootstrap support.

Linux / WSL2 recommended prerequisites:

• Git
• Node.js >=22.19.0
• npm (for Pi/npm bootstrap)
• pnpm 10.33.0 (Corepack may provide it, or install standalone with npm install -g pnpm@10.33.0)
• Pi CLI installed globally:

  npm install -g @earendil-works/pi-coding-agent
  

• local Pi/Codex/provider authentication configured outside PIDEX

Windows prerequisites for the experimental PowerShell bootstrap:

• Git for Windows, including Git Bash
• Node.js >=22.12.0
• npm (for Pi/npm bootstrap)
• pnpm 10.33.0 (Corepack may provide it, or install standalone with npm install -g pnpm@10.33.0)
• Pi CLI installed globally:

  npm install -g @earendil-works/pi-coding-agent
  

See Windows status for support boundaries and the PowerShell bootstrap.

Install

PIDEX v0.1 requires the canonical runtime checkout at exactly ~/pidex on Linux/WSL2, or $HOME\pidex for the Windows bootstrap. Other runtime paths are not supported yet.

Install modes

Mode	Command	Result
Full checkout	git clone https://github.com/d-trattner/pidex.git ~/pidex && cd ~/pidex && ./install.sh	Creates the canonical runtime checkout directly. Best for servers, development, and dashboard use.
Pi package bootstrap	pi install npm:@d-trattner/pidex, then /pidex-init-home in Pi	Installs lightweight Pi commands first, then initializes the canonical ~/pidex checkout.

Full checkout install

Linux / WSL2:

git clone https://github.com/d-trattner/pidex.git ~/pidex
cd ~/pidex
./install.sh
# simulate without changing Pi settings:
./install.sh --dry-run

install.sh installs dashboard dependencies when needed, runs validation checks, runs pi install ~/pidex, and may optionally install the global Git security hook and optional browser-smoke QA support after interactive prompts. Non-interactive installs skip optional features unless requested.

Useful Linux/WSL2 install flags:

./install.sh --skip-dashboard-deps
./install.sh --install-global-git-hook
./install.sh --skip-global-git-hook
./install.sh --with-browser-smoke
./install.sh --with-browser-smoke --with-browser-smoke-system-deps
./install.sh --skip-browser-smoke

The same controls also exist as environment variables for automation, but flags are preferred for manual use.

Browser-smoke support is optional Playwright/Chromium-based QA for real browser checks (rendering, styles, console errors, and basic interactions). The normal browser-smoke install is PIDEX-local under runtime state/cache directories; it does not use npm-global Playwright and does not mutate user projects. On minimal Linux servers, actually launching Chromium may also require host-level packages. Use --with-browser-smoke-system-deps only when you accept that PIDEX may run Playwright's install-deps chromium, which uses apt, requires root/passwordless sudo, and modifies system packages.

Pi package bootstrap install

PIDEX can also be installed as a lightweight Pi bootstrap package:

pi install npm:@d-trattner/pidex

The npm package provides the Pi commands/skills only. It does not replace the canonical ~/pidex runtime checkout, and it is not the dashboard/runtime distribution. After installing the package, run this in Pi:

/pidex-init-home

That command clones PIDEX into the canonical runtime checkout, runs the platform installer, removes the bootstrap package registration when possible, and asks you to run /reload. On Linux/WSL2 it uses ~/pidex and install.sh; on native Windows it uses $HOME\pidex and install.windows.ps1. Normal /pidex and /pd pipeline runs require the canonical checkout and will stop with setup guidance if it is missing.

Runtime installation requires pnpm@10.33.0. Corepack may provide it, or install standalone with:

npm install -g pnpm@10.33.0

Keep npm's role narrow: npm installs Pi and the lightweight PIDEX bootstrap package; pnpm installs/checks the PIDEX runtime workspace.

Windows experimental bootstrap

Windows experimental bootstrap:

irm https://raw.githubusercontent.com/d-trattner/pidex/master/install.windows.ps1 | iex

Useful Windows install flags when running a downloaded script locally:

.\install.windows.ps1 -SkipDashboardDeps
.\install.windows.ps1 -DryRun

For the one-line irm ... | iex form, use the defaults unless you specifically need an advanced automation override.

In the detailed docs, <pidex-root> means the canonical runtime checkout: ~/pidex for Linux/WSL2 and $HOME\pidex for the Windows bootstrap.

Uninstall:

cd ~/pidex
./uninstall.sh
# simulate without changing Pi settings:
./uninstall.sh --dry-run

Quick start

After a first install in a new Pi session, PIDEX resources should be available immediately. If Pi was already open during install, run /reload once.

In Pi:

/pidex Work on ~/my-project

/pd is available as a short alias. The orchestrator routes work through Codex-oriented pidex-* specialist agents.

Project session memory:

/pdmem optional note

/pdmem writes to <project-root>/wiki/session-memory/. See Project session memory.

Repo scope

• agents/ – role prompts
• rules/ – role-specific rules
• templates/ – artifact/checklist templates
• extensions/pidex/ – Pi extension entrypoint (pidex_agent)
• config/agents.json – default agent routing configuration
• config/profiles/*.json – provider/profile presets, including Spark/no-Spark variants
• scripts/delegate/ – codex delegate/auth wrapper
• pidex.analysis-metrics-history module – analytics, metrics, history helpers
• pidex.memory-wiki-hygiene module – wiki hygiene audit/cadence module
• dashboard/ – local analytics UI
• readme/ – detailed feature docs

Smoke checks

cd ~/pidex
bash scripts/doctor.sh
pnpm run check
bash scripts/smoke-test.sh
node scripts/modules/run-check.mjs --capability memory-wiki-hygiene.check --agent pidex-wiki-hygienist --phase maintenance --project ~/pidex

Dashboard

Linux / WSL2:

cd ~/pidex/dashboard
./start.sh

Windows has experimental PowerShell install/dashboard/uninstall entrypoints:

.\install.windows.ps1
cd $HOME\pidex\dashboard
.\start.windows.ps1
cd $HOME\pidex
.\uninstall.windows.ps1

See Windows status. The Linux shell launchers are not the Windows entrypoints.

The dashboard provides Overview, Live, Runs, Quality, Usage, Wiki, Context, and Settings sections. See Dashboard.

Provider limits and profiles

PIDEX tracks provider-native Codex quota windows, including Spark/no-Spark profile behavior and automatic no-Spark fallback when Spark is exhausted. See Provider limits and profiles.

Global Git security hook

PIDEX can optionally install a global Git pre-commit security hook for this Linux user. The hook saves/restores any previous global core.hooksPath and does not chain old hooks. See Global Git security hook.

Wiki hygiene

Run a read-only wiki hygiene audit with /pdwiki after /reload, or directly with node scripts/modules/run-check.mjs --capability memory-wiki-hygiene.check --agent pidex-wiki-hygienist --phase maintenance --project <project-root>. Reports are written to agents.output/wiki-hygiene/; cadence state is tracked in pidex/state/wiki-hygiene.json. Project-specific PIDEX rules live under pidex/rules/. See Wiki hygiene.

Project context

PIDEX stores project domain context in <project-root>/pidex/context/. The dashboard Context page lets users review and edit CONTEXT.md glossary entries produced by agents. For existing projects, /pidex may use grill-with-docs to challenge plans against code/docs/context before planner handoff. See Project context.

Optional parallel agents

PIDEX can define optional secondary lanes in config/parallel-agents.json. They are disabled by default, editable in Settings, and non-blocking. When enabled, configured critic/reviewer lanes run automatically at matching pipeline triggers unless the user requests a minimal single-lane run. Runtime warnings live in state/parallel-agents/status.json. See Optional parallel agents.

Automatic quality reports

Terminal pipeline lifecycle events can trigger automatic PDQ quality reports. Disable with:

PIDEX_AUTO_PDQ=0

See Automatic quality reports and Quality governance.