`pathcode`: Path-to-Color Segment Engine#

Implements the promptcode console script and its backing PathCoder: a reusable engine that compresses an indexed directory tree (e.g. _0_nucleus/_2_documents) into a colored digit spine plus the leaf name, generalizing the condense_ai_path zsh function. Rendering is split from the model – segments produces a plain list of Segment values, render projects them into zsh prompt escapes, truecolor ansi SGR, or plain text.

Path-to-Color Segment Engine.

class irix.pathcode.Segment(text: str, hue: str = '', shade: str = 'text1', kind: str = 'name')#

One renderable piece of a compressed path.

text: str#: Alias for field number 0

hue: str#: Alias for field number 1

shade: str#: Alias for field number 2

kind: str#: Alias for field number 3

class irix.pathcode.PathCoder(*, palette: Palette = <factory>, root: Path = <factory>, home_glyph: str = '~', config: Path | None = None)#

Compresses a filesystem path into colored Segment values and renders them.

Any path component matching a leading numeric index (_0_name, 0-name, 0.name, or a bare 0) collapses to a colored digit; consecutive index components concatenate into a digit spine, and the last component’s trailing name (if any) is kept. Chambers 0-4 use the Irix chamber-stable hue (Color.IRIX_MAP[n][3]); indices outside that range fall back to a deterministic structural hue picked by n % len(palette.hues) over the palette’s sorted hue names – there is no chamber meaning past index 4, so this only guarantees some stable color, not a chamber-accurate one.

When a places config is supplied (a YAML file with places: and abbreviations: sections – entries may use ~/ and $VAR/${VAR} expansion, matching colorcode’s config expressions):

Repo-root anchoring: if the path is inside a git (.git) or Jujutsu (.jj) repository, the repo name becomes the anchor segment instead of my or ~, so the prompt leads with the project name.
Abbreviation compression: interim (non-leaf, non-index) path segments are compressed to 2-char codes from the abbreviations: table (like US state codes). Dirs not in the table fall back to their first character. The leaf (current directory) is always shown in full.
Name-hash coloring: segments without an explicit places: hue get a stable hue derived from zlib.crc32 of the directory name, so every dir gets a consistent color even without config coverage (JetBrains pattern).

segments(path: str | Path) → list[Segment]#

Break path into an ordered list of Segment values.

Parameters:: path – The filesystem path to compress.
Returns:: Segments in left-to-right rendering order.

render(path: str | Path, fmt: str = 'zsh', renderer: str = 'pathcode') → str#

Render path through a formatter and renderer projection.

Parameters:

path – The filesystem path to compress.
fmt – 'zsh' (prompt-safe %F{}/%f escapes), 'ansi' (truecolor SGR, for statuslines/tmux), or 'plain' (no color).
renderer – 'pathcode' preserves the current compressed path; opt-in 'wayfinding' adds ASCII @ repo, + worktree, $ project, and > dependency-edge markers without consuming the configured/indexed hue channel.

Returns:

The rendered string.

Raises:

ValueError – If fmt or renderer is unsupported.

dominant_hue(path: str | Path) → str#

Return the hue of the deepest (most-specific) index segment in path.

Parameters:: path – The filesystem path to inspect.
Returns:: The hue name, or '' if path contains no index segments.

model_config = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

irix.pathcode.main(*vargs: str) → None#: CLI entry point: print the compressed, colorized rendering of a path.

pathcode: Path-to-Color Segment Engine#

`pathcode`: Path-to-Color Segment Engine#