# @xynogen/pix-pretty

> Enhanced tool output rendering with syntax highlighting, file icons, tree views, diff rendering, and FFF search

Latest version **1.30.1** (published 2026-10-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install @xynogen/pix-pretty
pnpm add @xynogen/pix-pretty
yarn add @xynogen/pix-pretty
bun add @xynogen/pix-pretty
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.30.1 |
| Published | 2026-10-16 |
| First published | 2026-06-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 76 |
| Author | xynogen |
| Maintainers | xynogen |
| Keywords | pi, pi-package, pi-extension, syntax-highlighting, fff, paste-chips, tool-rendering |

## Links

- npm: https://www.npmjs.com/package/@xynogen/pix-pretty
- Repository: https://github.com/xynogen/pix-mono
- Homepage: https://github.com/xynogen/pix-mono/tree/main/packages/pix-pretty#readme
- Issues: https://github.com/xynogen/pix-mono/issues
- npm.io page: https://npm.io/package/@xynogen/pix-pretty

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.30.1 (latest) — 2026-10-16
- 1.30.0 — 2026-10-06
- 1.29.0 — 2026-10-01
- 1.27.0 — 2026-09-23
- 1.26.0 — 2026-09-18
- 1.22.0 — 2026-09-11
- 1.21.0 — 2026-09-05
- 1.20.1 — 2026-09-05
- 1.20.0 — 2026-09-03
- 1.19.0 — 2026-09-02
- 1.18.4 — 2026-08-29
- 1.18.3 — 2026-08-29
- 1.18.2 — 2026-08-28
- 1.18.1 — 2026-08-24
- 1.18.0 — 2026-08-23
- … 54 more at https://npm.io/package/@xynogen/pix-pretty/versions

## README

# pix-pretty

Rendering and formatting library for Pi Coding Agent with syntax highlighting, file icons, tree views, FFF search integration, and gate-dialog overlay.

## What it does

This package is a **library + a small extension** that other pix packages
consume. It does not register user-facing tools itself — the tool renderers
(`pix-read`, `pix-bash`, `pix-ls`, `pix-find`, `pix-grep`, `pix-edit`,
`pix-write`) import from it. The extension entry point (`src/index.ts`) only
initializes the syntax-highlight theme from Pi settings, clears the highlight
cache, seeds the icon mode from `pix.json`, and registers two FFF slash
commands (`/fff-health`, `/fff-rescan`) once `pix-grep` has brought the FFF
finder online. The `/pix` settings command lives in `pix-runtime`.
(Activated by `pix-core`; not a standalone extension.)

### Rendering

- **Syntax highlighting** — `cli-highlight` (highlight.js-backed)
- **File icons** — type-aware icons in ls/find output
- **Tree views** — hierarchical directory display for ls
- **Diff rendering** — side-by-side split diff for edit/write
- **Bash exit summary** — colored status, line count, truncation notice

### Icon catalog (l10n-style)

Icons are treated like a localization catalog: packages never hardcode glyph
codepoints — they ask for a **semantic role** and the catalog resolves it
against one global icon mode. Reskinning, or fixing a missing-glyph (“tofu”)
problem on terminals without a Nerd Font, becomes a one-file edit here.

- **`./icon-catalog`** — `icon(key)` resolves a semantic key (`"cwd"`,
  `"model"`, `"paste.image"`, `"opt.caveman"`, …) to a glyph for the active
  mode. Modes: `nerd` (Nerd Font PUA, default), `unicode` (standard BMP glyphs,
  no patched font needed), `ascii` (plain letters). Also `iconFor(key, mode)`,
  `getIconMode()`, `setIconMode()`, `ICON_KEYS`, `ICON_MODES`.
- **`./icon-persist`** — reads/writes the icon mode via `pix.json`
  (`pretty.icons`); `initIconMode()` applies it on load.
- **`/pix`** (in `pix-runtime`) — unified settings overlay that includes the icon
  mode switch. One global knob governs every pix-* package (footer, paste
  chips, model picker, welcome banner, optimizer cell). Seeded from
  `PRETTY_ICONS` (`none`/`off` → `ascii`) when no choice is saved.

### Shared overlay

- **Gate overlay** (`./gate-overlay`) — the one permission-dialog component
  shared by `pix-gate` and `pix-sudo`. Two modes: `confirm` (SelectList) and
  `sudo` (SelectList + masked password). Returns
  `{ action: "approved" | "denied" | "timeout", password? }`. Padded with
  `Box` `paddingX=2`, `paddingY=1`. The simpler `./confirm` export is the
  plain boolean Yes/No dialog.
- **Provider picker** (`./provider-picker`) — the color-coded settings UI
  shared by `/web` and `/voice`: a sectioned settings overview, and a provider
  tree with a default dot, connection status, and expandable shell variables
  with set state and an export example.

### Inline chips (`./chips`)

The one source of truth for inline chip tags. Producers build tags with `chipTag`:
`chipTag.path(p)` (`@` picker), `chipTag.skill(ref)` (`$` picker), `chipTag.prompt(name, body)` (`/plan`).
The model receives each tag verbatim. `registerChips(pi)` shows them as chips in the prompt
editor and in sent user messages. `pix-display` calls it. Add a new chip kind here, not in a feature package.

UI features that moved to [`pix-display`](packages/pix-display): reasoning-tag (`<think>`/`<thinking>`) → native
`thinking` content blocks.

## Configuration

Configuration is read from **`~/.pi/agent/pix.json`** (the unified config file owned by `@xynogen/pix-runtime/config`). The `pretty` section of that file sets the defaults for theme, icon mode, and preview lines. Environment variables still override `pix.json` values.

> **Note:** config and collapse helpers previously shipped with `pix-pretty`; they now live in `pix-runtime` (`@xynogen/pix-runtime/config` and `@xynogen/pix-runtime/collapse`). Update any direct imports.

### `pix.json` — `pretty` section

```jsonc
{
  "pretty": {
    "icons": "nerd",          // nerd | unicode | ascii
    "maxPreviewLines": 80,
    "maxRenderLines": 150,
    "maxRenderWidth": "65%",  // modal frame width; percentage or columns
    "maxRenderHeight": "80%", // pagination threshold; percentage or rows
    "maxHighlightChars": 80000,
    "cacheLimit": 128,
    "diff": {
      "splitMinWidth": 150,
      "splitMinCodeWidth": 60
    }
  }
}
```

Syntax highlighting, diffs, and tool surfaces use the active Pi theme. Color overrides do not live in `pix.json`. `/pix` exposes modal width and height under **Pretty**; percentage choices move in 5% steps.

### Environment Variables (override `pix.json`)

- `PRETTY_MAX_HL_CHARS` — max characters to highlight (default: 80000)
- `PRETTY_MAX_PREVIEW_LINES` — max lines in preview output
- `PRETTY_CACHE_LIMIT` — FFF cache size limit
- `PRETTY_ICONS` — default icon mode when none is persisted: `nerd` (default),
  `unicode`, `ascii`, or `none`/`off` (→ `ascii`).
  Note: this seeds the file-icon helpers AND the semantic icon catalog.
  Overridden by the `/pix` settings command.
- `PRETTY_MAX_RENDER_LINES` — max lines in edit/write diff render (default: 150)
- `PRETTY_FFF_DIR` — override FFF state dir (default: `~/.cache/pi/fff`)

## Public exports

The package exposes its sub-modules via `exports`:

```
@xynogen/pix-pretty            (default — extension entry)
@xynogen/pix-pretty/ansi
@xynogen/pix-pretty/confirm
@xynogen/pix-pretty/progress
@xynogen/pix-pretty/config
@xynogen/pix-pretty/diff
@xynogen/pix-pretty/diff-render
@xynogen/pix-pretty/highlight
@xynogen/pix-pretty/lang
@xynogen/pix-pretty/icons
@xynogen/pix-pretty/icon-catalog
@xynogen/pix-pretty/icon-persist
@xynogen/pix-pretty/renderers
@xynogen/pix-pretty/fff
@xynogen/pix-pretty/types
@xynogen/pix-pretty/utils
@xynogen/pix-pretty/resize
@xynogen/pix-pretty/context
@xynogen/pix-pretty/gate-overlay
@xynogen/pix-pretty/modal-frame
@xynogen/pix-pretty/provider-picker
@xynogen/pix-pretty/shell-tool   (shared bash/powershell tool registrar + renderer)
@xynogen/pix-pretty/chips        (inline chip tags + editor/history chip renderer)
```

## Install

```bash
pi install npm:@xynogen/pix-pretty
```

> Foundation library. Feature packages install it as a dependency. Install it directly only when you build your own extension on it.

## Full distro

This package is part of [Pix](https://github.com/xynogen/pix-mono). The installer sets up Pi and the full distro. See [Install](https://github.com/xynogen/pix-mono#install) for the notes for each OS.

```bash
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh
```

```powershell
# Windows
irm https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.ps1 | iex
```

## License

MIT. See [LICENSE](LICENSE).

---
_Source: https://npm.io/package/@xynogen/pix-pretty · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._