pix-mono

Monorepo of Pix, a distro of Pi Coding Agent.

⚠ Expect breaking changes. This project is under active development. Packages are regularly split, merged, renamed, or removed. The recommended upgrade path is to uninstall then reinstall the distro rather than incrementally updating individual packages. When in doubt, run the uninstall script first.

🐧 Linux and macOS tested. This project has been tested on Linux and used successfully on macOS. Some tools are designed around Linux/Unix utilities and may be less efficient on macOS. Windows is not tested and may not work correctly.

Packages

Core bundle

Bundled together by @dihak/pix-core — a single pi install npm:@dihak/pix-core pulls and activates all of these.

Libraries

Shared dependencies pulled in automatically — install directly only if you need them standalone.

Package	Description
@dihak/pix-data	Shared model data layer (modelgrep catalog + coding score), cached at ~/.cache/pi
@dihak/pix-pretty	Enhanced tool output rendering — syntax highlighting, icons, tree views, FFF, gate-overlay

Theme

Package	Description
@dihak/pix-themes	Theme pack — 7 dark themes

UI / UX extensions

Package	Description
@dihak/pix-welcome	ASCII π banner + startup health checks (version, auth, models, tools, skills, gitignore)
@dihak/pix-footer	Status bar — mode, git branch, model, tokens, cost, live TPS
@dihak/pix-models	/models — enhanced model picker with coding score/rank, context window, cost
@dihak/pix-update	/update — self-update Pi + all extensions, detects install method
@dihak/pix-commands	/clear slash command (flushes ~/.cache/pi)
@dihak/pix-nudge	Tools nudge + capability nudge hooks to steer model toward correct tools
@dihak/pix-diagnostics	Compact LSP diagnostic widget — recent files list, overrides pi-lens
@dihak/pix-display	Paste chip rendering ([paste image #1]) + leaked <think> tag → native thinking blocks
@dihak/pix-prompts	System-prompt injection — bundled AGENT.md baseline + repo directive files
@dihak/pix-skills	read_skills discovery and loader — names-only listing, description and full-instruction loading, reference reads, and safe bundled resource copies

Behaviour

Package	Description
@dihak/pix-optimizer	Caveman mode + RTK tool rewriting + jq/TOON JSON compression + ponytail lazy-dev mode (/optimizer overlay)
@dihak/pix-gate	Permission gate for dangerous bash + path commands — 4 severity tiers (block/critical/dangerous/risky) + sudo redirect, configurable
@dihak/pix-subagent	Sub-agent spawning — 3 tools (agent, agent_result, agent_steer), live model widget, work-splitting

Tool suite

Bundled by pix-core. Drop-in replacements for the tools Pi exposes to the model (read, write, edit, find, grep, ls, bash, todo, ask_user). Each registers under the same tool name as the Pi built-in, so the model calls them transparently — no prompt changes needed. The only difference is the rendered output: syntax highlighting, side-by-side diffs, icon trees, and FFF-accelerated search, all via pix-pretty. Install pix-core and the whole suite is active; the built-ins are shadowed.

Package	Description
@dihak/pix-bash	bash — shell execution with framed output block and exit-code summary
@dihak/pix-read	read — file read with syntax highlighting, image mime + size metadata
@dihak/pix-write	write — file write with split-diff rendering on overwrite
@dihak/pix-edit	edit — precise text replacement with side-by-side diff per edit
@dihak/pix-find	find — glob search with FFF acceleration and file icons
@dihak/pix-grep	grep — pattern search with FFF-prioritised results
@dihak/pix-ls	ls — directory listing as an indented icon tree
@dihak/pix-ask	ask_user — structured TUI questionnaire (multi-choice, multi-select, previews)
@dihak/pix-todo	todo — durable execution checklist, survives context compaction
@dihak/pix-todo-auto	auto-continues the agent while todo items remain unfinished (/todo-auto)

Standalone extensions (opt-in)

Not bundled by pix-core — install each only if you want it. These are deliberately kept out of the default distro because each carries a setup cost or a sensitive capability: a provider API key, root execution, or a manual tool-toggling UI. Install with pi install npm:@dihak/<name>.

Package	Why it's opt-in
@dihak/pix-9router	9Router LLM provider + fetch/search/transcribe tools — needs a 9Router API key, so only useful if you route through 9Router
@dihak/pix-sudo	sudo_run — root execution via a PAM password overlay; a privileged capability you opt into explicitly (blocked in non-interactive mode)
@dihak/pix-toolbox	/toolbox — fuzzy-search picker to enable/disable tools at runtime; a power-user utility, not needed for normal use

Roadmap — third-party extensions

Upstream Pi community extensions we currently lean on. The future-development goal is to fork or rewrite these as first-class @dihak/pix-* packages so they're maintained and bundled in-house.

Package	Description
pi-lens	Real-time code feedback — LSP navigation/diagnostics, linters, formatters, type-checking, structural (ast-grep) analysis
pi-mcp-adapter	MCP (Model Context Protocol) adapter — connect Pi to external MCP servers and call their tools

Install

One-shot installer — installs Pi, sets theme/tools, then installs the whole pix distro.

Straight from GitHub (no clone needed):

curl -fsSL https://raw.githubusercontent.com/dihak/pix-mono/main/scripts/install.sh | sh

Or from a local clones:

sh scripts/install.sh   # or: bun run distro:install

Uninstall

Removes all @dihak/pix-* packages from Pi. Also cleans up sub-packages from older installs that listed them individually.

curl -fsSL https://raw.githubusercontent.com/dihak/pix-mono/main/scripts/uninstall.sh | sh

Or from a local checkout:

sh scripts/uninstall.sh   # or: bun run distro:uninstall

Upgrade / clean reinstall

When upgrading across breaking changes, uninstall first:

curl -fsSL https://raw.githubusercontent.com/dihak/pix-mono/main/scripts/uninstall.sh | sh
curl -fsSL https://raw.githubusercontent.com/dihak/pix-mono/main/scripts/install.sh | sh

Development

bun install        # install all workspace deps
bun test           # run all tests
bun run typecheck  # tsc across all packages

Graph analysis

The graph analyzer reads graphify-out/graph.json, validates inferred call edges against TypeScript bindings, removes invalid hyperedges, repairs recoverable hyperedge IDs, and extracts repeated structural and semantic patterns.

bun run graph:analyze

It writes the following files without replacing the original graph:

Output	Description
graphify-out/graph.cleaned.json	Graph with unreliable inferred calls removed and source paths normalized
graphify-out/patterns.json	Machine-readable quality findings and extracted patterns
graphify-out/PATTERN_REPORT.md	Human-readable pattern and graph-quality report

Use the cleaned graph for subsequent queries:

graphify query "your question" --graph graphify-out/graph.cleaned.json

Publishing

bun run publish:dry   # verify what would be published
bun run publish:all   # publish every package to npm

Lineage

Several packages here originated as forks or merges of community Pi packages:

Upstream	Disposition
npm:pi-caveman	starting point for the pix-optimizer caveman-mode rewrite
npm:pi-rtk-optimizer	merged into pix-optimizer
git:github.com/DietrichGebert/ponytail	ruleset adapted as ponytail mode in pix-optimizer
npm:@heyhuynhgiabuu/pi-pretty	replaced by @dihak/pix-pretty
npm:@heyhuynhgiabuu/pi-diff	superseded (merged into pix-core)
npm:@juicesharp/rpiv-ask-user-question	rewritten as the ask-user skill in pix-skills
git:github.com/tintinweb/pi-subagents	spawn engine ported into pix-subagent
git:github.com/nicobailon/pi-subagents	work-splitting design adapted in pix-subagent

Previous standalone repos migrated into this monorepo: pix-optimizer, pix-themes, pix-pretty, pix-core, pix-9router, pix-data.

License

MIT