twig

A context-efficient Linux directory tree viewer with plain output shared by humans, agents, scripts, and logs.

Human & AI

published v0.4.3first release Apr 27, 2026LinuxRustMIT

Architecture before contents

twig answers “what is the shape of this project?” first. Directories appear by default. Files, metadata, sorting, and alternate output formats are explicit additions. Plain whitespace carries the hierarchy without a decorative layer.

Published output

$ twig -L 2 twig-v0.4.3/
  twig-v0.4.3
    bench
    src
    tests
| 4 directories

Common paths

twig                 # directories
twig -f              # include files
twig -L 2            # depth limit
twig -s              # payload sizes
twig -t              # descendant time
twig --json          # structured output
twig --md            # Markdown output

The example above was reproduced with the published v0.4.3 x86_64 binary against its release source archive. Empty directories remain visible; symlinks are not followed; files stay behind -f.

Published measurements

32–77%: fewer tokens than matching tree output
17–169: tokens from twig -L 2
193.6 ms: largest recorded default walk
3: published Linux architectures

The v0.4.3 benchmark used four real directory trees ranging from 35 to 18,235 lines of default tree output. The savings grew with the amount of repeated path and box-drawing structure.

Token cost on the four recorded trees

Tree	`tree -d`	`twig`	Saved	`tree`	`twig -f`	Saved
Tiny	52	29	44%	351	240	32%
Small	437	208	52%	1,726	1,038	40%
Medium	24,757	7,383	70%	299,220	100,963	66%
Large	33,142	7,669	77%	377,409	105,036	72%

Warm-cache walk time

Tree	`find` dirs	`tree -d`	`tre -d`	`twig`	`tree`	`tre`	`twig -f`
Small	8.7 ms	4.2 ms	—	4.2 ms	5.4 ms	—	4.5 ms
Medium	98.9 ms	194.5 ms	265.2 ms	135.4 ms	441.6 ms	577.6 ms	141.2 ms
Large	952.4 ms	229.0 ms	281.6 ms	193.6 ms	438.5 ms	611.3 ms	192.3 ms

Read the numbers narrowly. This was one Intel Linux machine on ext4, using warm state, hyperfine -N --warmup 10 --min-runs 1000, and the cl100k_base tokenizer. Small-tree differences fall inside measurement noise. find was faster on the medium directory-only tree. Absolute results depend on hardware, filesystem state, ignored directories, output scope, and tokenizer.

Design contract

Defaults

Directories first; files require -f.
Plain two-space indentation without box drawing.
No configuration file, theme, icons, or color.
Empty directories remain information unless pruned.
No ignore-file interpretation in published v0.4.3.

Cost and safety

The default path performs no per-entry metadata collection.
Size and time work occurs only when requested.
Published v0.4.3 is read-only and follows no symlinks.
It makes no network connections or subprocess calls.
JSON is the safe mode for filenames containing control characters.

-s reports visible descendant file payload, not filesystem block allocation. Use du for disk accounting and dust for proportional disk-use visualization.

Lineage and acknowledgment

tree defined this category and remains the right tool for many jobs. twig is not presented as its replacement; it chooses a different default for the narrower question of project shape.

Tree output

tree supplied the category and baseline. tre, eza, and erdtree demonstrate Rust implementations, Git-aware traversal, structured output, and alternative layouts.

Navigation

broot, lstr, tere, and walk explore truncation, interactive navigation, and folders-first workflows that twig deliberately leaves to interactive tools.

Measurement and machine context

GNU find, GNU du, and dust are the filesystem baselines. Repomix treats token budgeting as a first-class concern. stump is a reference for tree data exposed through machine-oriented protocols.

Built by Nate Rich through iterative, machine-assisted development. These open-source projects supplied the category, design contrasts, and measurement baselines; release judgment and responsibility remain human.

Download v0.4.3

Release boundary: v0.4.3 is the published site and GitHub release. Local v0.4.4 development refines compact counting, metadata notation, and explicit ignore controls; it is not presented here as a released binary.

x86_64357,150 bytes · Intel and AMD PCs aarch64333,800 bytes · 64-bit ARM Linux armv7350,322 bytes · 32-bit ARM Linux source38,257 bytes · Rust source archive

SHA-256 checksums GitHub release Source

Manual install

sha256sum -c sha256.txt --ignore-missing
tar -xzf twig-v0.4.3-x86_64-unknown-linux-gnu.tar.gz
sudo install -m 755 twig-v0.4.3-x86_64-unknown-linux-gnu/twig /usr/local/bin/twig
twig --version