ASTro-sight
AST CLI for AI agents that parses 16 languages with tree-sitter and reports symbols, references, diff impact, API changes, and dead code as JSON or TOON
English |
日本語
astro-sight gives AI coding agents structural information while they edit code: symbol definitions and references, diff impact, public API changes, dead-code candidates, complexity, and dependencies.
It queries tree-sitter syntax trees, excluding comments and strings from identifier searches. Output is compact JSON by default, with TOON available. Use it from the CLI, an NDJSON session, or an MCP server.
Features
-
Complexity and architecture metrics: metrics measures function complexity, static local dependencies, cycles, CCD, ACD and propagation cost; select file or directory components and their depth. See usage and coverage limits.
-
References by identifier: refs lists the definitions and references of a symbol across a directory, and refs --names looks up many names in one pass
-
Diff impact: context maps a unified diff to changed symbols, signature changes, and callers, and impact exits 1 while callers outside the diff are left unresolved (made for Stop hooks)
-
Structured review: review combines the impact, files that usually change together according to git blame (cochange), public API changes, and dead symbols in one run
-
File structure: symbols, calls, imports, and ast return a file's outline, call graph, dependencies, and exact syntax nodes, and sequence draws the call flow as a Mermaid sequence diagram
-
Dead code and rules: dead-code reports exported symbols that nothing references, leaving out the ones test runners and frameworks call at run time, and lint checks AST pattern rules written in YAML
-
Token-aware output: compact JSON, TOON, or --format auto; results for frequent names stop at 100 references or about 3,000 tokens by default, with a result_summary of what was left out. See summary aggregation benchmarks for the cost of counting omitted references
-
Agent integration: skills for Claude Code and Codex, an MCP server, and an NDJSON session that batches queries
Supported languages (extensions and parser versions are in docs/languages.md):
Installation
Homebrew (macOS/Linux)
brew install owayo/astro-sight/astro-sight
winget (Windows)
winget install owayo.astro-sight
Cargo
Requires Rust 1.99 or later.
cargo install --git https://github.com/owayo/astro-sight --locked
From GitHub Releases
Download the archive for your platform from Releases, extract it, and put astro-sight on your PATH. Each release also includes SHA256SUMS for checking the downloads.
| Platform | Archive |
|---|
| Linux (x86_64) | astro-sight-x86_64-unknown-linux-gnu.tar.gz |
| Linux (x86_64, musl) | astro-sight-x86_64-unknown-linux-musl.tar.gz |
| Linux (ARM64) | astro-sight-aarch64-unknown-linux-gnu.tar.gz |
| macOS (Intel) | astro-sight-x86_64-apple-darwin.tar.gz |
| macOS (Apple Silicon) | astro-sight-aarch64-apple-darwin.tar.gz |
| Windows (x86_64) | astro-sight-x86_64-pc-windows-msvc.zip |
On macOS, if you downloaded the archive with a browser, remove the quarantine attribute before running it: xattr -d com.apple.quarantine astro-sight.
From Source
Requires mise (the Rust toolchain is pinned in mise.toml).
git clone https://github.com/owayo/astro-sight.git
cd astro-sight
make install
make install installs to /usr/local/bin. Set INSTALL_PATH to change it (for example make install INSTALL_PATH="$HOME/.local/bin").
Check astro-sight --version after installing. If command -v astro-sight shows a mise shim, mise which astro-sight identifies the executable to update; see installation checks.
After winget install, open a new terminal: the portable package reaches PATH by rewriting it, which terminals that were already open do not pick up. The musl archive is a statically linked build for Linux without glibc (Alpine) or with an old glibc (some Docker images).
Building from source also needs a C compiler for the tree-sitter parsers (Xcode Command Line Tools on macOS). After the binary, make install writes the Claude Code and Codex skills described in AI Agent Integration.
Usage
Results are compact JSON on one line by default (batch modes print one line per file). --pretty indents the JSON, and --format toon or --format auto switches to TOON or to whichever of the two is estimated to take fewer tokens. TOON output follows the v4.1 specification; an empty array is [].
Recommended Flow for Agents
# 1. Start the review of a whole diff with review
astro-sight review --dir . --git
# 2. Pair context and impact around an edit
astro-sight context --dir . --git
astro-sight impact --dir . --git
# 3. Read structure with symbols, and look up identifiers with refs
astro-sight symbols --path src/main.rs
astro-sight refs --name "AppService" --dir src/
# 4. Use ast only to pin down an exact syntax node
astro-sight ast --path src/main.rs --line 10 --col 0
# 5. Put structural rules you check repeatedly in lint, and use sequence when call order matters or calls go 3 or more levels deep
astro-sight lint --path src/main.rs --rules rules.yaml
astro-sight sequence --path src/main.rs --function main
# 6. Batch two or more different queries into one session
printf '%s\n' \
'{"command":"symbols","path":"src/main.rs"}' \
'{"command":"refs","name":"AppService","dir":"src"}' \
| astro-sight session
Compare Complexity and Dependencies
astro-sight metrics --dir . --component directory --component-depth 2 --base HEAD
Measure cyclomatic complexity, dependencies, cycles, CCD, ACD, and propagation cost by file or directory. --base compares against a Git commit; dependency edges and representative cycle paths include source evidence.
impact exits 1 while unresolved callers remain; otherwise it prints nothing and exits 0. JSON positions are zero-based; human-readable impact positions are one-based. Unanalyzable inputs and unresolved dependencies appear in diagnostics; an empty result alone does not prove the absence of impact or cycles.
| Topic | Guide |
|---|
| Commands, dependency-resolution coverage, baseline comparisons, and cycle evidence | Usage |
| Diff classification, language-specific compatibility checks, dead code, and co-change | Diff analysis |
| JSON, TOON, reference limits, and token budgets | Output format |
Configuration
astro-sight init writes a configuration file to ~/.config/astro-sight/config.toml (--path writes it elsewhere; an existing file is overwritten without asking). --config reads another file for a single run.
debug = false # write debug logs to files
format = "json" # default output format: "json" | "toon" | "auto"
skip_generated = true # leave generated files out of directory scans
--format on the command line takes precedence over format. The log directory, the cache under ~/.cache/astro-sight/, and --no-cache are described in docs/configuration.md.
AI Agent Integration
Register astro-sight as a skill so that Claude Code or Codex reaches for it on questions such as "who calls this function?" or "what does this diff affect?":
astro-sight skill-install claude # ~/.claude/skills/astro-sight/SKILL.md
astro-sight skill-install codex # ~/.codex/skills/astro-sight/SKILL.md
To use it as an MCP server over stdio, start astro-sight mcp from the repository you want to analyze. Files outside that directory are rejected.
{
"mcpServers": {
"astro-sight": {
"command": "astro-sight",
"args": ["mcp"]
}
}
}
With only the skill, an agent can still fall back to grep. Rules for CLAUDE.md / AGENTS.md that make it prefer astro-sight, and a Stop hook that keeps it working while impact reports unresolved callers, are in docs/integrations.md.
Development
Requires mise. Tool versions are pinned in mise.toml.
make setup # Install the toolchain (mise) and dependencies
make ci # Run the same checks as CI (no changes)
Run make help to list all development commands.
Besides mise, the build needs a C compiler for the tree-sitter parsers, and the tests need git. The tests run with cargo-nextest, which make setup installs at the version in mise.toml. Without mise, add SYSTEM_TOOLS=1 to use the tools on PATH (make test then needs cargo-nextest on PATH as well). When a [patch] in .cargo/config.toml swaps in local tree-sitter crates, Cargo.lock changes only on your machine and --locked stops the build; run make ci CARGO_FLAGS= in that case.
Choosing the skills that make install writes, heap profiling, the usage statistics tool, and how a release is built are covered in docs/development.md.
License
MIT