astra-code-map

# Tool List <p align="center"> <img src="pic/banner.png" alt="astra-code-map Hero Banner" width="100%"> </p> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"></a> <a href="https://golang.org/"><img src="https://img.shields.io/badge/Go-1.25+-00ADD8.svg" alt="Go Version"></a> <a href="THIRD_PARTY_NOTICES.md"><img src="https://img.shields.io/badge/Compliance-Third--Party_Notices-green.svg" alt="Compliance"></a> </p> English | [README_EN.md](README_EN.md) > Semantic Code Map · Code Graph · Code Intelligence · MCP Server astra-code-map is a local-first **semantic code map and code graph engine**, designed for Claude Code, Codex, Cursor, and other AI-powered coding tools that support MCP. It transforms codebases into queryable "symbol nodes + semantic relationship edges," enabling AI to perform symbol location, call chain tracking, dependency exploration, and change impact analysis without relying on repeated `grep` and full-file reads. ```text Source Code ├─ Tree-sitter: Fast parsing of current file structure └─ SCIP: Provides cross-file, type-aware ultimate semantics ↓ astra-code-map Merge Engine ↓ SQLite Semantic Code Graph ↓ MCP Server · REST API · Web Dashboard ``` ## What astra-code-map Solves | Problem You Want to Know | Capability Provided by astra-code-map | |---|---| | Where is a function, type, or method defined? | Semantic symbol search and precise location | | Who calls this function? Who does it call? | Callers / Callees queries | | How are two modules associated? | Code exploration and call path tracking | | What files and modules will be affected by changing a symbol? | Recursive impact analysis and Git Diff analysis | | What content in large repositories should not be included in AI context? | Ecosystem-aware filtering and generated file exclusion | | How can AI understand codebases with less context? | MCP structured queries and on-demand source code snippets | astra-code-map does not replace source code or compilers. It provides a **queryable, trackable, and sustainably updated code navigation base map** for AI agents, IDEs, and development platforms. ## Core Features - **Semantic Code Map**: Unified organization of functions, methods, types, files, and modules, as well as call, reference, import, inheritance, and implementation relationships. - **Dual-layer Indexing Architecture**: Tree-sitter handles real-time structure, while SCIP Provider handles cross-file semantics and symbol disambiguation. - **Incremental Synchronization**: Updates changed files based on file state and content hash, eliminating the need for full rebuilds. - **MCP Native Access**: Provides structured code queries for clients like Claude Code, Codex, Cursor, and VS Code. - **Call and Impact Analysis**: Supports callers, callees, path tracking, recursive impact propagation, cycle detection, and coupling analysis. - **Local Visualization**: Web Dashboard displays project structure, call neighborhoods, source code snippets, and understanding documents. - **Ecosystem-aware Filtering**: Automatically excludes dependency directories, build artifacts, caches, binary files, and generated code. - **C/C++ Conditional Compilation Awareness**: Preserves `#if`, `#ifdef`, and `#ifndef` guard contexts. ## Interface Preview ### Explore View Enter from projects, directories, files, or functions, and observe the overall structure before diving into local implementations. <img src="pic/explore.png" alt="astra-code-map Explore View"> ### Dependency Graph View callers, callees, and related call paths around a target function. <img src="pic/trace.png" alt="astra-code-map Dependency Graph"> ### Understanding Documents Generate structured documents for functions, files, modules, and project-level structures to aid code reading, reviews, refactoring, and handoffs. <img src="pic/understand.png" alt="astra-code-map Understanding Documents"> ## Quick Start See [QUICKSTART.md](QUICKSTART.md) for complete platform installation, SCIP Provider configuration, and troubleshooting. ### 1. Build and Install Run in the astra-code-map repository root: ```bash ./build.sh mkdir -p "$HOME/.local/bin" install -m 755 ./amap "$HOME/.local/bin/amap" export PATH="$HOME/.local/bin:$PATH" ``` Verify installation: ```bash amap --help ``` > Go version requirements are specified in the repository's `go.mod`. Windows users should build `amap.exe` and add its directory to the user's PATH. ### 2. Enter the Project to Analyze ```bash cd /path/to/your/project ``` ### 3. Register MCP ```bash amap install ``` This command detects installed clients and writes astra-code-map MCP configurations only for existing clients. ### 4. Build the Code Map ```bash amap index ``` The first run creates: ```text .astra-code-map/ ├── config.yaml └── astra-code-map.db ``` ### 5. Start Dashboard ```bash amap dashboard ``` Access in the browser: ```text http://localhost:3000 ``` ### 6. Continuous Synchronization (Optional) Run in a separate terminal: ```bash amap watch 30 ``` Avoid running multiple watchers simultaneously to prevent duplicate scanning and increased database writes. ## AI Agent Usage Examples After MCP registration, test the code map in IDE coding tools to verify its effectiveness. Corresponding MCP Tools: | Tool | Purpose | |---|---| | `astra-code-map_search` | Search functions, methods, types, and other symbols | | `astra-code-map_explore` | Explore related files and relationships around business concepts or symbols | | `astra-code-map_node` | View symbol definitions, signatures, locations, and source code snippets | | `astra-code-map_callers` | Query direct callers | | `astra-code-map_callees` | Query direct callees | | `astra-code-map_impact` | Recursively analyze change impact | | `astra-code-map_trace` | Find call paths between two symbols | | `astra-code-map_status` | View index coverage and data sources | | `astra-code-map_files` | Query indexed files by directory or pattern | ## Architecture Overview astra-code-map uses a "real-time structure + ultimate semantics" dual-layer model. ```mermaid graph LR A[Source Code] --> B[Tree-sitter Real-time Layer] A --> C[SCIP Semantic Providers] B --> D[astra-code-map Merge Engine] C --> D D --> E[(SQLite Semantic Code Graph)] E --> F[MCP Server] E --> G[REST API] G --> H[Web Dashboard] F --> I[AI Coding Agents] ``` ### Tree-sitter Real-time Layer - Fast parsing of current disk files - Extract definitions, signatures, comments, and local calls - Supports file-level incremental updates - Provides a basic code map when no SCIP Provider is available ### SCIP Semantic Layer - Provides cross-file definitions and references - Resolves type relationships, implementation relationships, and overloaded symbols - Enhances call graph and impact analysis determinism - Selectively enabled based on project language and build environment ### Merge and Storage All nodes and relationships record source information and are written to a local SQLite database. MCP, REST API, and Dashboard share the same data and do not maintain multiple divergent indexes. ## Supported Languages Core has built-in Tree-sitter real-time parsing for the following languages. Install the corresponding SCIP Provider for more complete cross-file semantics. | Language | Common Extensions | Semantic Provider | Real-time Parsing | |---|---|---|---| | Go | `.go` | `scip-go` | Tree-sitter | | TypeScript | `.ts` `.tsx` | `scip-typescript` | Tree-sitter | | JavaScript | `.js` `.jsx` `.mjs` `.cjs` | `scip-typescript` | Tree-sitter | | Python | `.py` | `scip-python` | Tree-sitter | | Java | `.java` | `scip-java` | Tree-sitter | | Kotlin | `.kt` `.kts` | `scip-java` | Tree-sitter | | Scala | `.scala` `.sc` | `scip-java` | Tree-sitter | | C | `.c` `.h` | `scip-clang` | Tree-sitter | | C++ | `.cc` `.cpp` `.cxx` `.hpp` `.hxx` | `scip-clang` | Tree-sitter | | Rust | `.rs` | `scip-rust` | Tree-sitter | | C# | `.cs` | `scip-dotnet` | Tree-sitter | | Ruby | `.rb` `.rake` | `scip-ruby` | Tree-sitter | SCIP Provider availability depends on the corresponding project, language toolchain, and build inputs. For example, high-precision C/C++ indexing typically requires a valid `compile_commands.json`. ## Common CLI ### Indexing and Service | Command | Description | |---|---| | `amap install` | Registers MCP to local AI coding tools | | `amap index` | Builds or incrementally updates the code map | | `amap index --tree-sitter` | Uses only Tree-sitter real-time layer | | `amap index --refresh-scip` | Forces refresh of SCIP semantic layer | | `amap index --full` | Performs full refresh | | `amap watch [seconds]` | Listens to code changes and synchronizes continuously | | `amap serve` | Starts MCP stdio Server | | `amap dashboard` | Starts Web Dashboard | ### Navigation and Analysis | Command | Description | |---|---| | `amap locate <symbol>` | Locates symbol definition | | `amap tree <symbol>` | Outputs call topology tree | | `amap diff [--suggest-tests]` | Analyzes Git change impact and suggests test scope | | `amap hotspots` | Finds code hotspots | | `amap deadcode` | Detects unreachable functions and methods | | `amap cycles` | Detects cycle dependencies | | `amap coupling [--path=...]` | Analyzes module coupling | | `amap owners <symbol>` | Queries code ownership based on Git blame | | `amap query "<SQL>"` | Directly queries local SQLite code graph | ## Ecosystem-aware Filtering astra-code-map follows a default principle: > Code maps prioritize indexing hand-written, business-semantic-bearing source code. The system automatically identifies and excludes common ecosystems: - Version control metadata - Third-party dependency directories - Build artifacts and caches - Generated code and compressed files - Binary files and non-parsable resources Users can adjust results using `include`, `exclude`, and `force-include` in `.astra-code-map/config.yaml`. ```yaml index: languages: - go exclude: - "docs/**" - "vendor/**" include: - "src/**" ``` ## Local Data and Privacy astra-code-map reads and indexes code locally and stores data in the current project's `.astra-code-map/` directory. - astra-code-map does not require uploading complete codebases to a separate remote indexing service. - MCP Server provides structured queries to clients through local stdio. - Dashboard and REST API serve local project data by default. - Whether AI clients send query results to remote models depends on the client and model service configurations, not controlled by astra-code-map. Do not commit `.astra-code-map/astra-code-map.db` to Git. Add to the project's `.gitignore`: ```gitignore .astra-code-map/ ``` ## Open-source Components and Licenses astra-code-map is built on mature open-source ecosystems, including SCIP, Tree-sitter, SQLite, `sqlx`, `fsnotify`, D3.js, and Marked. - astra-code-map's proprietary source code uses [Apache License 2.0](LICENSE), unless otherwise specified in individual files. - Third-party components continue to apply their respective copyright notices and licenses. - Complete lists of third-party components, versions, and licenses are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). - Release packages should include `LICENSES/` license texts and corresponding SBOMs. - External SCIP Providers are used as independent tools by default; they are not distributed with astra-code-map binaries unless explicitly stated in a release. The README component list is for illustration purposes only; `THIRD_PARTY_NOTICES.md`, `LICENSES/`, and release SBOMs are authoritative lists for compliance. ## Project Status astra-code-map is continuously evolving. Public interfaces, configuration formats, and indexing data structures may change before stabilization. Suitable usage for the current stage: - Verify semantic code map capabilities in local projects - Integrate with AI coding agents for code navigation and impact analysis - Provide feedback on incorrect indexing, missed indexing, and cross-file relationships in real-world repositories - Contribute new test cases, documentation, platform adaptations, and language compatibility fixes ## Contributing Before submitting issues, provide: - Operating system and astra-code-map version - Project language and build tools - Used SCIP Provider and version - Reproducible minimal code examples - Actual and expected results Before submitting code, describe the problem background and expected solutions in an issue. Do not disclose sensitive details in public issues. ## Related Documents - [Quick Start](QUICKSTART.md) - [Third-party Software Notices](THIRD_PARTY_NOTICES.md) ## License Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.