Tagline: The simplest way to understand code. Point it at a directory, file, or function. Get exactly what you need.
Status: ✅ Production v0.18.0 | Available on PyPI
Latest: v0.18.0 builds on v0.17.0's Python runtime inspection (python://) and progressive help system with continued refinements.
Quick Start
Install:
pip install reveal-cli
Use:
reveal src/ # Directory → tree view
reveal app.py # File → structure
reveal app.py load_config # Element → extraction
That's it. No flags, no configuration, just works.
The Problem
Developers and AI agents waste time reading entire files when they only need to understand structure or extract specific functions.
Example: You want to see what's in app.py - do you really need to read all 500 lines?
Agent inefficiency:
- Reads entire file: 500 tokens × $0.003/1K = $0.0015
- Does this 100x/day across 1000 agents = $54,750/year
- Plus energy: ~2M kWh/year (190 US homes equivalent)
The Solution: Progressive Disclosure
Reveal provides three levels of detail - start broad, drill down as needed:
1. Directory Structure
$ reveal src/
📁 src/
├── app.py (247 lines, Python)
├── database.py (189 lines, Python)
└── models/
├── user.py (156 lines, Python)
└── post.py (203 lines, Python)
2. File Structure
$ reveal app.py
app.py (247 lines, Python)
├── Imports (5)
├── Classes (2)
│ ├── Config (lines 15-34)
│ └── Application (lines 36-198)
└── Functions (6)
├── load_config (lines 201-215)
├── init_database (lines 217-230)
└── ...
3. Element Extraction
$ reveal app.py load_config
app.py:201-215
def load_config(config_path: str) -> Config:
"""Load configuration from YAML file."""
with open(config_path) as f:
data = yaml.safe_load(f)
return Config(**data)
Result: 10x more efficient than reading full files. Perfect for AI agents working within token budgets.
SIL Principles in Action
Reveal demonstrates SIL's core principles (see SIL_PRINCIPLES.md):
✅ Clarity - Structure is visible, not hidden (see what's in a file without reading it)
✅ Simplicity - Zero configuration, smart defaults (just works)
✅ Composability - Unix tool composition (pipes to grep, jq, vim)
✅ Correctness - Reliable parsing via Tree-sitter (AST-based, not regex)
✅ Verifiability - Precise filename:line format (vim/git/grep compatible)
Layer in Semantic OS: Layer 5 (Human Interfaces / SIM) - makes structure visible and navigable
Supported Languages (18 built-in)
Programming:
- 🐍 Python (.py)
- 📜 JavaScript (.js) - ES6+, classes, arrow functions, async/await
- 🔷 TypeScript (.ts, .tsx) - Type annotations, interfaces, React/TSX
- 🦀 Rust (.rs)
- 🔷 Go (.go)
- 🎮 GDScript (.gd) - Godot game engine
Scripts & DevOps:
- 🐚 Bash/Shell (.sh, .bash)
- 🐳 Docker (Dockerfile)
Data & Docs:
- 📓 Jupyter (.ipynb)
- 📝 Markdown (.md)
- 📋 JSON (.json)
- 📋 YAML (.yaml, .yml)
- 📋 TOML (.toml)
Run reveal --list-supported to see the current list.
Advanced Features
Pattern Detection (v0.16.0+)
Check code quality with industry-aligned rules:
reveal app.py --check # All rules
reveal app.py --check --select B,S # Bugs + Security only
reveal --rules # List available rules
reveal --explain B001 # Explain specific rule
Built-in rules: Bare excepts, Docker :latest tags, function complexity, line length, insecure URLs
Extensible: Drop custom rules in ~/.reveal/rules/ - zero configuration!
Python Runtime Adapter (v0.17.0+)
Inspect Python runtime environments with progressive disclosure:
reveal python:// # Overview of Python environment
reveal python://version # Python version info
reveal python://env # Environment variables (Python-filtered)
reveal python://venv # Virtual environment status
reveal python://packages # Installed packages
reveal python://imports # Module import analysis
reveal python://debug/bytecode # Bytecode inspection
Self-documenting: reveal help://python shows all available endpoints with examples.
Use cases:
- Debug dependency conflicts
- Verify environment setup before deployment
- Inspect production Python environments
- Analyze import dependencies
URI Adapters (Experimental)
Explore beyond files and Python runtimes:
reveal env://PATH # Environment variables
reveal postgres://prod users # Database schema (coming soon)
reveal https://api.github.com # REST APIs (coming soon)
See Reveal Roadmap for adapter evolution.
Agent-Help Implementation (v0.16.0+, Enhanced v0.17.0)
Reveal validates SIL's proposed agent-help standard with a production three-tier implementation:
reveal --agent-help # Quick strategic guide (~1,500 tokens)
reveal help:// # Progressive discovery system (50-500 tokens as needed)
reveal --agent-help-full # Comprehensive reference (~12,000 tokens offline)
What agents get:
- Decision trees - When to use reveal vs alternatives (cat, grep, etc.)
- Token efficiency analysis - 7-150x reduction patterns with real examples
- Anti-patterns - What NOT to do (e.g., reading full file before checking structure)
- Workflow sequences - Codebase exploration, PR review, refactoring patterns
- Pipeline composition - Integrate with git, find, jq, vim
- Self-documenting adapters - help://python, help://ast auto-discovered from registry
Three-Tier Progressive Discovery (v0.17.0)
Tier 1 (--agent-help): Strategic guide that teaches discovery (~1,500 tokens)
- Use when: Agent first encounters reveal
- Teaches: Use help:// for progressive discovery
- Token cost: ~1,500 tokens (one-time load)
Tier 2 (help://): Dynamic self-documenting system (50-500 tokens)
- Use when: Agent needs specific adapter or feature docs
- Examples: help://python, help://ast, help://check
- Token cost: 50-500 tokens per topic (progressive loading)
- Key innovation: Auto-discovers from adapter registry - never goes stale
Tier 3 (--agent-help-full): Complete offline reference (~12,000 tokens)
- Use when: Offline environments or comprehensive analysis needed
- Token cost: ~12,000 tokens (comprehensive)
Result: 85% token reduction for typical usage (1,500 + 200 vs 11,000 tokens)
Production Validated
After 3 months in production (v0.16.0 released Nov 2025, v0.17.0 Dec 2025):
- ✅ Agents adopt reveal-first pattern (check structure before reading)
- ✅ Token reduction matches predictions (7-150x measured in practice)
- ✅ Three-tier system prevents documentation drift (help:// auto-discovers adapters)
- ✅ 85% token efficiency gain over static full docs
- ✅ Agents naturally use progressive discovery (brief → help:// → full as needed)
Conclusion: The agent-help standard works. The three-tier progressive model is recommended for complex evolving CLI tools.
See the full standard: AGENT_HELP_STANDARD.md
Use Cases
For Developers
- Quick file overview without opening editor
- Find functions/classes rapidly (
reveal file.py | grep "def ") - Jump to code with vim integration (
vim $(reveal app.py | grep load_config)) - Terminal workflows - perfect for SSH sessions
For AI Agents
- Token efficiency - See structure (50 tokens) before reading full file (500 tokens)
- Context gathering - Extract only relevant functions
- Codebase exploration - Discover structure progressively
- Integration - Works with LangChain, Claude Code, etc.
For Teams
- Code reviews - Understand structure before detailed review
- Onboarding - New team members explore codebase efficiently
- Documentation - Generate structure docs automatically
- Refactoring - See dependencies before changes
Economic Impact
Agent Efficiency at Scale
Without Reveal (traditional approach):
- Read 500-line file: 500 tokens
- Cost: 500 × $0.003/1K = $0.0015 per operation
- At 100x/day per agent: $0.15/day = $54.75/year per agent
- 1000 agents: $54,750/year
With Reveal (progressive disclosure):
- Structure view: 50 tokens
- Extract specific function: 20 tokens
- Total: 70 tokens
- Cost: 70 × $0.003/1K = $0.00021 per operation
- At 100x/day per agent: $0.021/day = $7.67/year per agent
- 1000 agents: $7,670/year
Savings: $47,080/year (86% reduction)
Environmental Impact
Energy waste from poor agent loops:
- Traditional approach: ~2M kWh/year per 1000 agents
- Equivalent to: 190 US homes annual consumption
- Reveal + progressive disclosure: 86% reduction (~280,000 kWh saved)
Scale this to millions of agents globally = massive economic and environmental impact.
Why Reveal Matters for SIL
Progressive disclosure is a core SIL principle - start broad, drill down as needed.
Reveal proves this pattern works for code exploration. As SIL evolves, this same pattern will extend to:
- Semantic graphs (Pantheon IR)
- Provenance chains (GenesisGraph)
- Multi-agent reasoning (Agent Ether)
- Domain schemas (Morphogen, TiaCAD, SUP)
Reveal today: Explore code semantically
SIM vision: Explore ALL semantic structure (code, graphs, reasoning, provenance)
See the Reveal Roadmap for detailed plans.
Get Started
Install from PyPI:
pip install reveal-cli
Try it:
reveal --version # Check installation
reveal --list-supported # See supported file types
reveal . # Explore current directory
Learn more:
- GitHub Repository
- Full Documentation
- Changelog
- PyPI Package
Report issues or contribute:
- GitHub Issues
- Contributing Guide
Related SIL Projects
- morphogen - Cross-domain computation (audio, physics, circuits)
- tiacad - Declarative parametric CAD in YAML
- genesisgraph - Verifiable process provenance
See the complete Project Index for all 12 SIL projects.
Last Updated: 2025-12-08 (v0.18.0)
Document Version: 1.1