Arian

Your documentation is a direct reflection of your software, so hold it to the same standards.

Arian generates LLM-optimized context from source code repositories. Instead of dumping raw files, it intelligently selects, compresses, and organizes code so that language models get the most relevant information — within token limits.

Status: Alpha — Core architecture is established. APIs, CLI, and output may evolve.

Highlights

• Task-aware — File selection and compression adapt to what you're doing (bug fix, feature, review, onboarding...)
• Token-budget-first — Set a limit, Arian respects it. Never exceeds your budget
• Smart compression — Large files get compressed to signatures or structure outlines automatically
• Python deep analysis — Extracts classes, functions, methods via AST for precise fragmentation
• One command — arian scans your repo and produces a single, organized Markdown context file
• Flexible output — Merged, separate, or grouped context files per directory

Overview

Arian does not concatenate files. It builds a structured context plan: collects files, classifies them by architectural role, analyzes symbols, applies compression, and renders Markdown optimized for LLM workflows.

# Generate context for a bug fix
arian src/ tests/ --task bug_fix

# Onboard to a new project
arian --task onboarding

# Set a token budget
arian src/ --budget 5000

Output goes to ~/.arian/output/context.md by default. Each file contains a YAML manifest, full directory tree, and syntax-highlighted code blocks organized by importance.

✍️ Author

Created by Salim Namvar. Built out of the need to feed LLMs the right code context — not just all the code.

Usage

Quick examples

# Current directory
arian

# Specific paths with a task
arian src/ lib/ --task feature

# Token budget
arian src/ --budget 10000

# Separate output per directory
arian src/ lib/ --scope separate

# Grouped output
arian --group src/,lib/ --group tests/

# Verbose logging
arian src/ --verbose

Task types

CLI options

arian [OPTIONS] [paths]...

For detailed usage, see docs/USAGE.md.

Installation

pip install arian

Requires Python 3.10+.

From source (development)

git clone https://github.com/salimnamvar/arian.git
cd arian
pip install -e ".[dev]"

Development instructions are kept to a minimum here. See docs/developer/GITFLOW.md for the full development workflow.

How it works

1. Collect — Scans repository for files matching configured extensions
2. Classify — Assigns each file an architectural role (readme, test, domain, service, infrastructure...)
3. Analyze — Extracts symbols from Python via AST (other languages get role-based classification)
4. Plan — Ranks files by relevance to the task, applies compression, enforces token budgets
5. Materialize — Loads content, applies compression (full → signatures → structure → summary), fragments large files along symbol boundaries
6. Render — Produces Markdown with manifest, directory tree, and syntax-highlighted code

Compression levels

Feedback and Contributing

Contributions are welcome! Open an issue or submit a pull request at the source repository.

For development setup and workflow, see docs/developer/GITFLOW.md.

License

Apache-2.0