https://github.com/scottbaggett/dex
Context optimization for agentic workflows. Extract and format code changes with surgical precision for LLM.
https://github.com/scottbaggett/dex
agentic-ai cli context-engineering llms
Last synced: 15 days ago
JSON representation
Context optimization for agentic workflows. Extract and format code changes with surgical precision for LLM.
- Host: GitHub
- URL: https://github.com/scottbaggett/dex
- Owner: scottbaggett
- License: mit
- Created: 2025-07-13T01:48:04.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-02-22T21:50:40.000Z (2 months ago)
- Last Synced: 2026-02-23T00:30:33.043Z (2 months ago)
- Topics: agentic-ai, cli, context-engineering, llms
- Language: TypeScript
- Homepage:
- Size: 1.37 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# DEX
Context extraction and codebase analysis for AI workflows. Generate precise, token‑efficient context, combine files, distill entire repos, and visualize APIs — all from one CLI.
Local installation via Bun
git clone
·
bun link
·
dex --help
## Quick Start
```bash
# Clone and install locally
git clone https://github.com/scottbaggett/dex.git
cd dex
bun install
bun link
# Now use dex globally
dex --help
# Extract your current changes (txt by default)
dex -s --format md --clipboard
```
## Safety Stance
Dex treats AI context generation as a trust-boundary operation. When context leaves your repository and enters a model prompt, leakage risk is real.
Dex is opinionated by design:
1. Always scan content for secrets and obvious PII before output.
2. Redact sensitive spans by default.
3. Write an audit manifest entry for every generated output.
Unsafe behavior should be an explicit override, not a hidden default.
## Core Commands
## `Extract` (default command)
Extracts Git changes and formats context for LLMs.
```bash
dex # Current unstaged changes
dex -s # Staged changes only
dex -a # Staged + unstaged
dex HEAD~5..HEAD # Specific commit range
dex -p "src/**" -t ts,tsx # Filter by path and types
dex --select # Interactive file picker (TTY)
```
Key options:
- -s, --staged: Only staged changes
- -a, --all: Staged + unstaged changes
- --full : Include full files matching pattern
- --diff-only: Force diffs (disable Smart Context)
- -p, --path : Filter by file path
- -t, --type : Filter by file types (e.g. ts,tsx,js)
- -f, --format : md | json | txt (default: txt)
- -c, --clipboard: Copy output to clipboard
- -u, --include-untracked: Include untracked files
- --untracked-pattern : Pattern for untracked files
- --optimize : aid, symbols
- --no-metadata: Omit metadata block
- --select: Interactive file selection (TTY)
- --sort-by : name | updated | size | status
- --sort-order : asc | desc
- --filter-by : all | staged | unstaged | untracked | modified | added | deleted
- --include-sensitive: Include sensitive content without redaction safeguards
- --target : claude | gpt | local | custom (recorded in audit metadata)
- --yes: Required in non-TTY usage with `--include-sensitive`
Outputs are saved to `.dex/` by default unless `--clipboard`, `--stdout` (where available), or an explicit `--output` is used.
## Distill
Extract clean API signatures from entire codebases, removing implementation details for token-efficient LLM context.
```bash
dex distill . # Distill current project
dex distill packages/api # Distill a specific directory
dex distill src/index.ts # Distill a single file
dex distill . --private 1 # Include private members
dex distill . --include "*.ts" # Only TypeScript files
dex distill . --stdout # Print to stdout
```
Key options:
- -f, --format : txt | md | json (default: txt)
- -o, --output : Write to a specific file
- -c, --clipboard: Copy output to clipboard
- --stdout: Print to stdout
- -s, --select: Interactive file selection
- --include : Include file patterns (e.g., "*.ts" "src/**/*.js")
- --exclude : Exclude file patterns
- --comments <0|1>: Include comments (default: 0)
- --docstrings <0|1>: Include docstrings (default: 1)
- --private <0|1>: Include private members (default: 0)
- --protected <0|1>: Include protected members (default: 0)
- --internal <0|1>: Include internal members (default: 0)
- --workers : Number of worker threads (default: 1)
- --dry-run: Preview what would be processed
- --staged: Only process staged files
- --include-sensitive: Include sensitive content without redaction safeguards
- --target : claude | gpt | local | custom (recorded in audit metadata)
- --yes: Required in non-TTY usage with `--include-sensitive`
## `Combine`
Create a single, LLM‑friendly document from many files.
```bash
dex combine src/auth/ src/api/ # Combine directories
dex combine file1.ts file2.ts # Combine specific files
dex combine -s # Pick files interactively (TTY)
dex combine --staged -c # Use staged files; copy to clipboard
```
**Key options:**
- -f, --format : txt | md | json (default: txt)
- --staged: Use all staged files (full contents)
- -c, --clipboard: Copy to clipboard
- -o, --output : Write to file instead of saving to `.dex/`
- --include : Include patterns, e.g. "*.ts" "*.js"
- --exclude : Exclude patterns, e.g. "*.test.*" "*.spec.*"
- --max-files : Limit files processed (default 1000)
- --no-gitignore: Ignore .gitignore
- -s, --select: Interactive picker (TTY)
- --stdout: Print output to stdout
- --since : Only process files changed since git ref
- --dry-run: Show what files would be processed
- --include-sensitive: Include sensitive content without redaction safeguards
- --target : claude | gpt | local | custom (recorded in audit metadata)
- --yes: Required in non-TTY usage with `--include-sensitive`
## `Scan`
Run detection-only safety scans without generating context artifacts.
```bash
dex scan . # Human-readable summary
dex scan . --format json # CI-friendly machine output
```
**Key options:**
- -f, --format : txt | json (default: txt)
### Tree
Generate a beautiful API tree or outline for quick understanding.
```bash
dex tree src/ # Tree view
dex tree . --outline # Outline view
dex tree . --group-by type --show-types --show-params
```
Key options:
- -o, --output : Write to file
- --stdout: Print to stdout
- -c, --clipboard: Copy to clipboard
- --exclude : Exclude patterns
- --include-private: Include private/internal APIs
- --show-types: Show param and return types
- --show-params: Show function parameters
- --group-by : file | type | none (default: file)
## Installation
### Local Installation
```bash
# Clone the repository
git clone https://github.com/scottbaggett/dex.git
cd dex
# Install dependencies and link globally
bun install
bun link
# Verify installation
dex --help
```
### Alternative: Run directly from source
```bash
# With Bun (no build needed, runs TypeScript directly)
cd /path/to/dex
bun run src/cli.ts [command] [options]
```
DEX saves outputs to `.dex/` with descriptive, timestamped filenames. Use `--clipboard`, `--stdout` (where available), or `--output ` to override.
## Performance & Parallel Processing
DEX supports worker threads for CPU parallelism during `distill`:
```bash
# Default: sequential worker mode
dex distill .
# Sequential processing for small projects
dex distill . --workers 1
# Parallel processing for larger codebases
dex distill . --workers 4
```
**Performance Notes:**
- **Default safety**: Sequential mode avoids worker startup overhead in small runs
- **Small projects** (<100 files): Keep `--workers 1`
- **Large projects** (1000+ files): Try `--workers 2` to `--workers 8`
- **Memory-intensive**: Each worker has independent parser state
## Requirements
- Bun 1.0+
- Git (for change tracking)
## Tips
- Use `--select` to interactively choose files when you don’t want to depend on Git state.
- Prefer `--format txt` for agents that parse structure, `--format md` for human review, and `--format json` for programmatic pipelines.
- `distill` supports `--dry-run` to preview scope and `--exclude` repeatedly for fine control.
## Contributing
- ⭐ Star the repo: https://github.com/scottbaggett/dex
- 🐛 Issues: https://github.com/scottbaggett/dex/issues
- 🔧 PRs: https://github.com/scottbaggett/dex/pulls
## License
MIT — see [LICENSE](LICENSE)