dirpack 0.2.0

Budgeted directory indexes for AI coding agents with tree-sitter signatures
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

# 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](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals), which suggests that putting a "compressed" index of the directory directly inside `AGENTS.md` outperforms the "progressive disclosure" strategy recommended by [Agent Skills](https://github.com/agentskills/agentskills).

## 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)

```bash
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

```bash
cargo install dirpack

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

## Quick Start

```bash
# 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:

```toml
[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

| Tool | Budgeting | Signatures | Progressive |
|------|-----------|------------|-------------|
| **dirpack** | ✅ tokens/bytes | ✅ tree-sitter | ✅ 4-phase |
| yek | ✅ tokens | ❌ | ❌ |
| code2prompt | ❌ | ❌ | ❌ |
| repomix | ❌ | ❌ | ❌ |

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