@xynogen/pix-ls

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 only. This project has only been tested on Linux. macOS and Windows are not tested and may not work correctly.

Packages

Core bundle

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

Libraries

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

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

Theme

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

UI / UX extensions

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

Behaviour

Package	Description
@xynogen/pix-optimizer	Caveman mode + RTK tool rewriting + jq/TOON JSON compression + ponytail lazy-dev mode (/optimizer overlay)
@xynogen/pix-gate	Permission gate for dangerous bash + path commands — 4 severity tiers (block/critical/dangerous/risky) + sudo redirect, configurable
@xynogen/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
@xynogen/pix-bash	bash — shell execution with framed output block and exit-code summary
@xynogen/pix-read	read — file read with syntax highlighting, image mime + size metadata
@xynogen/pix-write	write — file write with split-diff rendering on overwrite
@xynogen/pix-edit	edit — precise text replacement with side-by-side diff per edit
@xynogen/pix-find	find — glob search with FFF acceleration and file icons
@xynogen/pix-grep	grep — pattern search with FFF-prioritised results
@xynogen/pix-ls	ls — directory listing as an indented icon tree
@xynogen/pix-ask	ask_user — structured TUI questionnaire (multi-choice, multi-select, previews)
@xynogen/pix-todo	todo — durable execution checklist, survives context compaction

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:@xynogen/<name>.

Package	Why it's opt-in
@xynogen/pix-9router	9Router LLM provider + fetch/search/transcribe tools — needs a 9Router API key, so only useful if you route through 9Router
@xynogen/pix-sudo	sudo_run — root execution via a PAM password overlay; a privileged capability you opt into explicitly (blocked in non-interactive mode)
@xynogen/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 @xynogen/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/xynogen/pix-mono/main/scripts/install.sh | sh

Or from a local clones:

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

Uninstall

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

curl -fsSL https://raw.githubusercontent.com/xynogen/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/xynogen/pix-mono/main/scripts/uninstall.sh | sh
curl -fsSL https://raw.githubusercontent.com/xynogen/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

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 @xynogen/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