The simplest way to understand code
Point it at a directory, file, or function. Get exactly what you need with zero configuration.
Developers and AI agents waste time reading entire files when they only need to understand structure or extract specific functions. There's no standard way to progressively explore code.
reveal provides smart, semantic exploration of codebases:
- Directories → See what's inside
- Files → See structure (imports, functions, classes)
- Elements → See implementation (extract specific function/class)
All with perfect filename:line integration for vim, git, grep, and other tools.
Install:
pip install reveal-cli # Basic install
pip install reveal-cli[treesitter] # With 50+ language supportUse:
reveal src/ # Directory → tree view
reveal app.py # File → structure
reveal app.py load_config # Element → extractionThat's it. No flags, no configuration, just works.
# Directories → tree view
$ reveal src/
📁 src/
├── app.py (247 lines, Python)
├── database.py (189 lines, Python)
└── models/
├── user.py (156 lines, Python)
└── post.py (203 lines, Python)
# Files → structure view
$ reveal app.py
📄 app.py
Imports (3):
app.py:1 import os, sys
app.py:2 from typing import Dict
Functions (5):
app.py:15 load_config(path: str) -> Dict
app.py:28 setup_logging(level: str) -> None
Classes (2):
app.py:95 Database
app.py:145 RequestHandler
# Elements → extraction
$ reveal app.py load_config
app.py:15-27 | load_config
15 def load_config(path: str) -> Dict:
16 """Load configuration from JSON file."""
17
18 if not os.path.exists(path):
19 raise FileNotFoundError(f"Config not found: {path}")
20
21 with open(path) as f:
22 return json.load(f)Every line is filename:line format:
# Works with vim
$ reveal app.py | grep "Database"
app.py:95 Database
$ vim app.py:95
# Works with git
$ reveal app.py | grep "load_config"
app.py:15 load_config(path: str) -> Dict
$ git blame app.py -L 15,27
# Pipe to other tools
$ reveal app.py --format=grep | grep "config"
app.py:15:def load_config(path: str) -> Dict:
app.py:18: if not os.path.exists(path):from reveal import TreeSitterAnalyzer, register
@register('.go', name='Go', icon='🔷')
class GoAnalyzer(TreeSitterAnalyzer):
language = 'go'Done! Full Go support with structure extraction and element access.
Works for: Python, Rust, Go, JavaScript, TypeScript, C#, Java, PHP, Bash, C, C++, Swift, Kotlin, and 40+ more languages!
from reveal import FileAnalyzer, register
@register('.md', name='Markdown', icon='📝')
class MarkdownAnalyzer(FileAnalyzer):
def get_structure(self):
"""Extract headings."""
headings = []
for i, line in enumerate(self.lines, 1):
if line.startswith('#'):
headings.append({'line': i, 'name': line.strip('# ')})
return {'headings': headings}
def extract_element(self, element_type, name):
"""Extract a section."""
# Custom extraction logic
...That's it! Your file type now works with reveal.
- ✅ Smart defaults - No flags needed for 99% of use cases
- ✅ Directory trees - See what's in a folder
- ✅ Structure extraction - Imports, functions, classes
- ✅ Element extraction - Get specific function/class
- ✅ 50+ languages - Via tree-sitter (Python, Rust, Go, JS, TS, C#, Java, PHP, etc.)
- ✅ Perfect line numbers -
filename:lineformat everywhere - ✅ Unix composable - Works with vim, git, grep, sed, awk
- ✅ Multiple output formats - text (default), json, grep
- ✅ Easy to extend - Add new file type in 10-50 lines
- ✅ AI-optimized - Designed for agentic workflows
# Start broad
$ reveal src/
# Pick interesting file
$ reveal src/app.py
# Deep dive
$ reveal src/app.py Database# See function implementation
$ reveal app.py load_config
# Jump to edit
$ vim app.py:15# Find all TODO comments
$ reveal src/*.py | grep -i "todo"
# Count functions per file
$ for f in src/*.py; do echo "$f: $(reveal $f | grep -c 'Functions')"; done
# Extract all function names
$ reveal app.py | awk '/Functions/,/^$/ {if ($2 ~ /:/) print $3}'For AI Agents:
- Explore unknown codebases efficiently
- Get structure without reading full files
- Extract specific elements on demand
- Standard interface across all file types
For Developers:
- Quick reference without opening editor
- Understand file structure rapidly
- Find specific functions/classes
- Perfect for terminal workflows
For Scripts:
- JSON output for programmatic access
- Grep-compatible format
- Composable with Unix tools
- Reliable filename:line references
reveal/
├── base.py # FileAnalyzer base class
├── treesitter.py # TreeSitterAnalyzer (50+ languages!)
├── tree_view.py # Directory tree view
├── new_cli.py # Simple CLI (200 lines)
└── analyzers_new/
├── python.py # 15 lines
├── rust.py # 13 lines
├── go.py # 13 lines
├── markdown.py # 79 lines
├── yaml_json.py # 110 lines
└── ... # Easy to add more!
Total core: ~500 lines Per analyzer: 10-50 lines
# Metadata only
reveal app.py --meta
# JSON output
reveal app.py --format=json
# Grep-compatible output
reveal app.py --format=grep
# Directory depth
reveal src/ --depth=5We welcome contributions! Adding a new file type takes 10-50 lines of code.
Most wanted:
- New language analyzers (TypeScript, Java, Swift, Kotlin)
- Better extraction logic for existing analyzers
- Documentation improvements
- Bug reports and feature requests
MIT License - See LICENSE
- GitHub: https://github.com/scottsen/reveal
- Issues: https://github.com/scottsen/reveal/issues
- Discussions: https://github.com/scottsen/reveal/discussions
Make reveal the standard way to explore code - for humans and AI agents alike. Clean, simple, powerful.
Status: 🚀 v0.2.0 - Clean Redesign | License: MIT
