dirpack

Budgeted directory indexes for AI coding agents

dirpack creates compressed directory representations that fit within token/byte budgets. Unlike other tools, it uses progressive disclosure—including structure first, then signatures, then content—stopping exactly when the budget is exhausted.

dirpack was inspired by recent research from Jude Gao at Vercel, which suggests that putting a "compressed" index of the directory directly inside AGENTS.md outperforms the "progressive disclosure" strategy recommended by Agent Skills.

Features

• Budget-aware: Set token or byte limits; output stops at the boundary
• Tree-sitter signatures: Extract function/struct/trait signatures for Rust, Go, Python, TypeScript, JavaScript, C, C++
• Progressive disclosure: Spine → signatures → summaries → content
• Git-aware: Uses git ls-files when available, respects .gitignore
• Configurable: Priority rules, file categories, exclude patterns via TOML

Installation

Quick Install (recommended)

curl -fsSL https://raw.githubusercontent.com/rawwerks/dirpack/master/install.sh | bash

This downloads a pre-built binary for your platform and installs it to ~/.local/bin.

Using Cargo

cargo install dirpack

# or from source
cargo install --git https://github.com/rawwerks/dirpack

Quick Start

# Pack current directory with 4K token budget
dirpack pack . -t 4000

# Pack with 16KB byte budget, markdown output
dirpack pack . -b 16000 -f full

# View directory tree with priorities
dirpack tree . --show-priority

# Create default config
dirpack init

Output Formats

Pipe (default)

Compact, single-line format optimized for AGENTS.md:

[myproject]|root: ./path|dirs:{src,tests}|src:{main.rs,lib.rs}|main.rs:fn main(),fn setup()

Full

Markdown with sections for structure, signatures, and content.

JSON

Machine-readable output with budget stats.

Configuration

Create dirpack.toml in your project:

[output]
format = "pipe"
default_budget_tokens = 4000

[scanning]
use_gitignore = true
include_hidden = false
max_depth = 20

[signatures]
enabled = true
max_signature_length = 200

# High-priority files get included first
[[priority_rules]]
pattern = "README*"
priority = 200

[[priority_rules]]
pattern = "src/main.*"
priority = 140

Run dirpack init to generate a full default config.

Runtime Limits

dirpack enforces a per-process concurrency cap for pack jobs to protect CPU/IO.

• DIRPACK_PACK_CONCURRENCY_LIMIT: max concurrent pack jobs (default: available CPU parallelism)
• DIRPACK_PACK_RETRY_AFTER_SECS: suggested retry delay for saturated servers (default: 1)

How It Works

1. Scan directory (git-aware or walkdir fallback)
2. Prioritize files by pattern rules and category
3. Pack progressively:
   • Phase 1: Directory spine (always included)
   • Phase 2: Code signatures (high-priority files first)
   • Phase 3: Doc summaries (README excerpts)
   • Phase 4: Full content (budget permitting)
4. Stop when budget exhausted

Comparison

dirpack's unique value: progressive disclosure with real signatures, not just file listings.

CLI Reference

dirpack pack [PATH] [OPTIONS]
  -t, --target-tokens <N>   Token budget
  -b, --target-bytes <N>    Byte budget
  -f, --format <FORMAT>     Output: pipe, full, json
  -o, --output <FILE>       Write to file instead of stdout
  -c, --config <FILE>       Custom config path
  --root-label <LABEL>      Override root path in output (e.g., '.')
  --no-git                  Don't use git ls-files
  --no-signatures           Skip tree-sitter extraction
  -v, --verbose             Show stats

dirpack tree [PATH]
  --show-priority           Display computed priorities

dirpack init
  --global                  Create in ~/.config/dirpack/
  --force                   Overwrite existing

License

MIT