https://github.com/semantic-infrastructure-lab/reveal
Progressive file disclosure for agentic AI - explore files hierarchically with plugin-based analyzers
https://github.com/semantic-infrastructure-lab/reveal
agentic ai cli code-analysis developer-tools file-explorer progressive-disclosure python
Last synced: about 1 month ago
JSON representation
Progressive file disclosure for agentic AI - explore files hierarchically with plugin-based analyzers
- Host: GitHub
- URL: https://github.com/semantic-infrastructure-lab/reveal
- Owner: Semantic-Infrastructure-Lab
- License: mit
- Created: 2025-11-21T20:03:34.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2026-04-18T05:07:38.000Z (3 months ago)
- Last Synced: 2026-04-18T07:03:05.216Z (3 months ago)
- Topics: agentic, ai, cli, code-analysis, developer-tools, file-explorer, progressive-disclosure, python
- Language: Python
- Size: 51.3 MB
- Stars: 6
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# Reveal
**Reveal is how AI agents understand codebases without wasting tokens.**
A local-first, adapter-driven semantic inspection layer — progressive disclosure enforced by design. One CLI, 24 URI adapters, 185+ languages. Structure before content, always. Engineers and AI systems use the same tool, the same syntax, the same progressive drill-down.
```bash
reveal src/auth.py validate_token # What does this function do?
reveal 'calls://src/?target=validate_token' # Who calls it? (cross-file)
reveal overview . # one-glance dashboard: quality, activity, deps
reveal 'ast://src/?complexity>10' # What's too complex?
reveal health ssl://api.example.com domain://example.com ./src # One-shot health check
reveal pack src/ --since main --budget 8000 # PR context snapshot for AI agents
```
## Installation
```bash
pip install reveal-cli
```
## What Makes It Different
**Progressive disclosure — the only way in.** `dir → file → element` isn't optional; it's the architecture. You cannot accidentally dump 7,000 tokens of raw code.
```bash
reveal src/ # tree structure (~50-200 tokens)
reveal src/auth.py # imports, functions, classes (~200-500 tokens)
reveal src/auth.py validate_token # exact code (~100-300 tokens)
```
**Local-first.** No backend, no API keys, no data leaving the machine. Runs in CI/CD pipelines, air-gapped environments, and anywhere you'd use a Unix tool.
**Everything is a URI.** `ast://`, `calls://`, `ssl://`, `mysql://`, `markdown://`, `claude://` — same query operators, same output format, same piping model across all of them.
**Cross-file call graph analysis:**
```bash
reveal 'calls://src/?target=fn&depth=3' # full impact radius before a refactor
reveal 'calls://src/?rank=callers&top=20' # most architecturally coupled functions
reveal 'calls://src/?uncalled' # functions with no callers — rough check, verify results
```
**Deep-dive code navigation (works on Python, PHP, and 35+ tree-sitter languages):**
```bash
reveal app.py process_batch --boundary # inputs read, outputs/effects produced
reveal app.py process_batch --sideeffects # DB / HTTP / FS / logging calls, classified
reveal app.py process_batch --deps # what this range depends on (params, externals)
reveal app.py process_batch --mutations # values written here, where they're next read
reveal app.py :123 --around # nearby context from a line number / stack trace
reveal app.py process_batch --ifmap # control-flow skeleton (branches + early exits)
reveal legacy.php :120-340 --boundary # same flags work on flat PHP, not just OO
```
Pinpoint inspection inside a single function or line range — built for triaging giant handlers, legacy files, and stack traces without reading top-to-bottom. See [`AGENT_HELP.md`](reveal/docs/AGENT_HELP.md) for the full nav-flag family.
**PR-aware context snapshots for AI agents:**
```bash
reveal pack src/ --since main --budget 8000 # changed files first, then key dependencies
reveal pack src/ --focus "auth" --budget 6000 # topic-focused snapshot
```
**Composable pipelines:**
```bash
# nginx config → extract all domains → check each SSL cert
reveal nginx.conf --extract domains | sed 's/^/ssl:\/\//' | reveal --stdin --check
# Find functions that got more complex in this PR
reveal diff://git://main/.:git://HEAD/. --format json | \
jq '.diff.functions[] | select(.complexity_delta > 5)'
# Batch SSL check from a file of domains
reveal @domains.txt --check
```
**Native MCP server (`reveal-mcp`) for AI agent integration:**
```bash
# Install once, works in Claude Code, Cursor, Windsurf, any MCP-compatible agent
pip install reveal-cli
reveal-mcp # starts the server
# Six tools: reveal_structure, reveal_element, reveal_nav, reveal_query, reveal_pack, reveal_check
# Agents get progressive disclosure, deep-dive nav, and call-graph analysis — no subprocess overhead
```
**Unified health checks across categories:**
```bash
reveal health ./src ssl://api.example.com domain://example.com mysql://prod
# → code quality + cert expiry + DNS health + DB replication, one exit code
```
**Documentation as a queryable graph:**
```bash
reveal 'markdown://docs/?aggregate=type' # taxonomy frequency table
reveal 'markdown://docs/?link-graph' # bidirectional link analysis + orphan detection
reveal 'markdown://docs/?body-contains=retry&type=procedure' # full-text + metadata
```
**AI session history as structured data** *(useful for workflows built on Claude Code)*:
```bash
reveal claude://sessions/ # list all sessions
reveal 'claude://sessions/?search=validate_token' # cross-session search
```
## What Reveal Does (and Doesn't)
| Reveal does | Reveal does not |
|-------------|-----------------|
| Inspect / read | Modify / write |
| Evaluate quality | Auto-fix issues |
| Package for LLMs | Run LLM inference |
| Compose workflows | Orchestrate pipelines |
| Describe itself | Require external config |
## Subcommands
```bash
reveal check src/ # quality check (complexity, maintainability, links)
reveal review main..HEAD # PR review: diff + check + hotspots, one pass
reveal health ssl://site.com # health check with exit codes 0/1/2
reveal pack src/ --budget 8000 # token-budgeted snapshot for LLM context
reveal pack src/ --architecture # pack + entry points + core abstractions brief
reveal hotspots src/ # top complexity hotspots (✅/⚪ test-coverage per fn)
reveal overview . # one-glance dashboard: stats, quality, git activity
reveal deps . # dependency health: circular imports, unused, packages
reveal architecture src/ # architectural brief: entry points, abstractions, risks
reveal trace src/ --from main # execution narrative from an entry point
reveal contracts src/ # ABC/Protocol/TypedDict/Pydantic inventory
reveal surface src/ # external boundary map: CLI args, routes, env vars, I/O
reveal dev new-adapter # scaffold new adapters/rules
```
## Adapters (24 built-in)
| Adapter | What it queries |
|---------|-----------------|
| `ast://` | Functions, classes, complexity, decorators — 185+ languages |
| `calls://` | Cross-file call graph: callers, callees, coupling metrics, dead code |
| `depends://` | Inverse module dependency graph: who imports this module |
| `diff://` | Structural diff between branches or commits (with per-function complexity delta) |
| `imports://` | Dependency graph, circular imports, unused imports |
| `stats://` | Codebase quality scores, hotspots, duplication |
| `git://` | Commits, blame, branches, tags, function-level history |
| `ssl://` | Certificate expiry, chain validation, hostname match |
| `autossl://` | cPanel AutoSSL run logs — per-domain TLS outcomes, DCV failures |
| `letsencrypt://` | Let's Encrypt certbot live certificates — expiry, multi-domain, renewal status |
| `domain://` | DNS, WHOIS, registrar, HTTP redirect chain, email DNS |
| `nginx://` | Config parsing, ACL rules, upstream routing, ACME validation |
| `cpanel://` | User environment, domains, SSL health, ACL audit |
| `mysql://` | Schema, replication status, table analysis |
| `sqlite://` | Schema, query analysis |
| `markdown://` | Frontmatter, headings, link graphs, full-text search |
| `json://` | JMESPath queries, nested navigation, flatten |
| `env://` | Environment variable analysis, `.env` validation |
| `python://` | Runtime introspection of live Python modules |
| `patches://` | Test patch pressure: repeated mocks, private patches, patch-heavy tests |
| `xlsx://` | Excel data extraction and analysis |
| `claude://` | AI session history, tool usage, file access patterns |
| `reveal://` | Reveal introspects itself: adapters, rules, config |
| `help://` | Built-in documentation, searchable from the CLI |
## Documentation
- **[Why Reveal](reveal/docs/WHY_REVEAL.md)** — what makes it powerful
- **[Quick Start](reveal/docs/QUICK_START.md)** — 5-minute introduction
- **[What Reveal Is Good For](reveal/docs/guides/WHAT_IS_REVEAL_GOOD_FOR.md)** — organized use cases and best-fit workflows
- **[MCP Server](reveal/docs/guides/MCP_SETUP.md)** — native integration with Claude Code, Cursor, Windsurf
- **[CI/CD Recipes](reveal/docs/guides/CI_RECIPES.md)** — GitHub Actions and GitLab CI ready-to-paste YAML
- **[Benchmarks](reveal/docs/BENCHMARKS.md)** — measured 3.9–15x token reduction on real scenarios
- **[Recipes](reveal/docs/guides/RECIPES.md)** — task-based workflows
- **[All Docs](reveal/docs/INDEX.md)** — complete documentation index
- **AI Agents**: `reveal --agent-help`
## License
See [LICENSE](LICENSE) for details.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.