{"id":35085356,"url":"https://github.com/aimasteracc/tree-sitter-analyzer","last_synced_at":"2026-04-02T18:00:58.682Z","repository":{"id":307258150,"uuid":"1028849208","full_name":"aimasteracc/tree-sitter-analyzer","owner":"aimasteracc","description":"A scalable, multi-language code analysis framework based on Tree-sitter, usable both as a CLI tool and an MCP server.","archived":false,"fork":false,"pushed_at":"2026-03-30T02:16:55.000Z","size":16298,"stargazers_count":27,"open_issues_count":5,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T04:27:09.272Z","etag":null,"topics":["ai","ai-coding","llms","mcp-server","programing","toon","tree-sitter","tree-sitter-analyzer","vibe-coding"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aimasteracc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["aimasteracc"],"tidelift":"pypi/tree-sitter-analyzer"}},"created_at":"2025-07-30T06:42:41.000Z","updated_at":"2026-03-29T14:13:36.000Z","dependencies_parsed_at":"2025-11-12T09:03:23.643Z","dependency_job_id":null,"html_url":"https://github.com/aimasteracc/tree-sitter-analyzer","commit_stats":null,"previous_names":["aimasteracc/tree-sitter-analyzer"],"tags_count":86,"template":false,"template_full_name":null,"purl":"pkg:github/aimasteracc/tree-sitter-analyzer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimasteracc%2Ftree-sitter-analyzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimasteracc%2Ftree-sitter-analyzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimasteracc%2Ftree-sitter-analyzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimasteracc%2Ftree-sitter-analyzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aimasteracc","download_url":"https://codeload.github.com/aimasteracc/tree-sitter-analyzer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimasteracc%2Ftree-sitter-analyzer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31312744,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-coding","llms","mcp-server","programing","toon","tree-sitter","tree-sitter-analyzer","vibe-coding"],"created_at":"2025-12-27T13:29:16.543Z","updated_at":"2026-04-02T18:00:58.671Z","avatar_url":"https://github.com/aimasteracc.png","language":"Python","readme":"# 🌳 Tree-sitter Analyzer\n\n**English** | **[日本語](README_ja.md)** | **[简体中文](README_zh.md)**\n\n[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Tests](https://img.shields.io/badge/tests-multi--thousand-brightgreen.svg)](#-quality--testing)\n[![Coverage](https://codecov.io/gh/aimasteracc/tree-sitter-analyzer/branch/main/graph/badge.svg)](https://codecov.io/gh/aimasteracc/tree-sitter-analyzer)\n[![PyPI](https://img.shields.io/pypi/v/tree-sitter-analyzer.svg)](https://pypi.org/project/tree-sitter-analyzer/)\n[![Version](https://img.shields.io/badge/version-1.10.5-blue.svg)](https://github.com/aimasteracc/tree-sitter-analyzer/releases)\n[![GitHub Stars](https://img.shields.io/github/stars/aimasteracc/tree-sitter-analyzer.svg?style=social)](https://github.com/aimasteracc/tree-sitter-analyzer)\n\n\u003e **Tree-Sitter-Analyzer is a local-first code context engine for AI-assisted development** — combining fast repository retrieval, AST-based structural analysis, and secure MCP integration.\n\nIts job is not just to parse code. Its job is to help humans and AI agents fetch only the code context they actually need, safely, quickly, and with structural precision.\n\n```\nfind the right files → find the right matches → extract the right structure → send only the right context\n```\n\n**17 languages · Project-boundary security · Claude Desktop / Cursor / Roo Code · CLI + Python API**\n\n---\n\n## ✨ What's New in v1.10.5\n\n- **`get_code_outline` MCP tool with TOON format**: Outline-first navigation delivering **54-56% token reduction** vs JSON. Retrieve hierarchical structure first, then fetch only the bodies you need.\n- **`trace_impact` MCP tool**: Lightweight call site finder using ripgrep — impact analysis without graph database overhead\n- **Intent-based tool aliases**: AI-friendly tool naming (`locate_usage`, `map_structure`) makes tool discovery natural for agents\n- **Analysis session tracking**: Audit multi-step SMART workflows with session IDs and operation history\n- **23 critical bug fixes**: TOON format return structure, default output format, test assertions - **project fully operational**\n- **Measured token savings**: Real-world testing shows TOON format reduces output size by 54-56% across small/medium/large files\n- **Enhanced test coverage**: 8,470 tests (100% pass), 88.68% coverage (↑8.35% from v1.10.4)\n- **Cross-platform verified**: All tests pass on Ubuntu, Windows, macOS × Python 3.10-3.13\n\n📖 **[Full Changelog](CHANGELOG.md)** for complete version history.\n---\n---\n\n## 🎬 See It In Action\n\n\u003c!-- GIF placeholder - see docs/assets/demo-placeholder.md for creation instructions --\u003e\n*Demo GIF coming soon - showcasing AI integration with SMART workflow*\n\n---\n\n## 🎯 Why Tree-sitter Analyzer\n\nTree-sitter Analyzer is an open-source, local-first code context engine for helping AI assistants read only what matters in large codebases.\n\n- **Minimal context, not whole-file stuffing**: retrieve the smallest useful code regions before sending them to AI\n- **Evidence-based analysis**: combine tree-sitter structure with `fd` and `ripgrep` to surface relevant files, symbols, and paths\n- **No heavy preprocessing required**: useful on messy repositories where full indexing can be slow, stale, or difficult to maintain\n\n### Common Use Cases\n\n- Understand what a very large file or module is doing without loading the entire file into an AI prompt\n- Trace business logic, UI handlers, or bug-related code paths across a complex repository\n- Narrow AI context for Java and other large codebases before asking for analysis or changes\n\n---\n\n## 🚀 5-Minute Quick Start\n\n### Prerequisites\n\n```bash\n# Install uv (required)\n# macOS/Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n# Windows PowerShell\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# Install fd + ripgrep (required for search features)\nbrew install fd ripgrep          # macOS\nwinget install sharkdp.fd BurntSushi.ripgrep.MSVC  # Windows\n```\n\n📖 **[Detailed Installation Guide](docs/installation.md)** for all platforms.\n\n### Verify Installation\n\n```bash\nuv run tree-sitter-analyzer --show-supported-languages\n```\n\n---\n\n## 🤖 AI Integration\n\nConfigure your AI assistant to use Tree-sitter Analyzer via MCP protocol.\n\nThis works especially well when your assistant struggles with very large files, noisy repository-wide context, or legacy code that is too expensive to load all at once.\n\n### Claude Desktop / Cursor / Roo Code\n\nAdd to your MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"tree-sitter-analyzer\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\", \"tree-sitter-analyzer[mcp]\",\n        \"tree-sitter-analyzer-mcp\"\n      ],\n      \"env\": {\n        \"TREE_SITTER_PROJECT_ROOT\": \"/path/to/your/project\",\n        \"TREE_SITTER_OUTPUT_PATH\": \"/path/to/output/directory\"\n      }\n    }\n  }\n}\n```\n\n**Configuration file locations:**\n- **Claude Desktop**: `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows) / `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)\n- **Cursor**: Built-in MCP settings\n- **Roo Code**: MCP configuration\n\nAfter restart, tell the AI: `Please set the project root directory to: /path/to/your/project`\n\n📖 **[MCP Tools Reference](docs/api/mcp_tools_specification.md)** for complete API documentation.\n\n---\n\n## 💻 Common CLI Commands\n\n### Installation\n\n```bash\nuv add \"tree-sitter-analyzer[all,mcp]\"  # Full installation\n```\n\n### Top 5 Commands\n\n```bash\n# 1. Analyze file structure\nuv run tree-sitter-analyzer examples/BigService.java --table full\n\n# 2. Quick summary\nuv run tree-sitter-analyzer examples/BigService.java --summary\n\n# 3. Extract code section\nuv run tree-sitter-analyzer examples/BigService.java --partial-read --start-line 93 --end-line 106\n\n# 4. Find files and search content\nuv run find-and-grep --roots . --query \"class.*Service\" --extensions java\n\n# 5. Query specific elements\nuv run tree-sitter-analyzer examples/BigService.java --query-key methods --filter \"public=true\"\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e📋 View Output Example\u003c/summary\u003e\n\n```\n╭─────────────────────────────────────────────────────────────╮\n│                   BigService.java Analysis                   │\n├─────────────────────────────────────────────────────────────┤\n│ Total Lines: 1419 | Code: 906 | Comments: 246 | Blank: 267  │\n│ Classes: 1 | Methods: 66 | Fields: 9 | Complexity: 5.27 avg │\n╰─────────────────────────────────────────────────────────────╯\n```\n\n\u003c/details\u003e\n\n📖 **[Complete CLI Reference](docs/cli-reference.md)** for all commands and options.\n\n---\n\n## 🌍 Supported Languages\n\n| Language | Support Level | Key Features |\n|----------|---------------|--------------|\n| **Java** | ✅ Complete | Spring, JPA, enterprise features |\n| **Python** | ✅ Complete | Type annotations, decorators |\n| **TypeScript** | ✅ Complete | Interfaces, types, TSX/JSX |\n| **JavaScript** | ✅ Complete | ES6+, React/Vue/Angular |\n| **C** | ✅ Complete | Functions, structs, unions, enums, preprocessor |\n| **C++** | ✅ Complete | Classes, templates, namespaces, inheritance |\n| **C#** | ✅ Complete | Records, async/await, attributes |\n| **SQL** | ✅ Enhanced | Tables, views, procedures, triggers |\n| **HTML** | ✅ Complete | DOM structure, element classification |\n| **CSS** | ✅ Complete | Selectors, properties, categorization |\n| **Go** | ✅ Complete | Structs, interfaces, goroutines |\n| **Rust** | ✅ Complete | Traits, impl blocks, macros |\n| **Kotlin** | ✅ Complete | Data classes, coroutines |\n| **PHP** | ✅ Complete | PHP 8+, attributes, traits |\n| **Ruby** | ✅ Complete | Rails patterns, metaprogramming |\n| **YAML** | ✅ Complete | Anchors, aliases, multi-document |\n| **Markdown** | ✅ Complete | Headers, code blocks, tables |\n\n📖 **[Features Documentation](docs/features.md)** for language-specific details.\n\n---\n\n## 📊 Features Overview\n\n| Feature | Description | Learn More |\n|---------|-------------|------------|\n| **SMART Workflow** | Set-Map-Analyze-Retrieve-Trace methodology | [Guide](docs/smart-workflow.md) |\n| **Outline-First Navigation** | `get_code_outline` — hierarchical structure map before content retrieval | [MCP Tools](docs/api/mcp_tools_specification.md) |\n| **MCP Protocol** | Native AI assistant integration | [API Docs](docs/api/mcp_tools_specification.md) |\n| **Token Optimization** | TOON format delivers 54-56% token reduction; token-aware controls for large AI workflows | [Features](docs/features.md) |\n| **File Search** | fd-based high-performance discovery | [CLI Reference](docs/cli-reference.md) |\n| **Content Search** | ripgrep regex search | [CLI Reference](docs/cli-reference.md) |\n| **Security** | Project boundary protection | [Architecture](docs/architecture.md) |\n\n---\n\n## 🏆 Quality \u0026 Testing\n\n| Metric | Value |\n|--------|-------|\n| **Tests** | Multi-thousand automated tests |\n| **Coverage** | [![Coverage](https://codecov.io/gh/aimasteracc/tree-sitter-analyzer/branch/main/graph/badge.svg)](https://codecov.io/gh/aimasteracc/tree-sitter-analyzer) |\n| **Type Safety** | 100% mypy compliance |\n| **Platforms** | Windows, macOS, Linux |\n\n```bash\n# Run tests\nuv run pytest tests/ -v\n\n# Generate coverage report\nuv run pytest tests/ --cov=tree_sitter_analyzer --cov-report=html\n```\n\n---\n\n## 🛠️ Development\n\n### Setup\n\n```bash\ngit clone https://github.com/aimasteracc/tree-sitter-analyzer.git\ncd tree-sitter-analyzer\nuv sync --extra all --extra mcp\n```\n\n### Quality Checks\n\n```bash\nuv run pytest tests/ -v                    # Run tests\nuv run python check_quality.py --new-code-only  # Quality check\nuv run python llm_code_checker.py --check-all   # AI code check\n```\n\n📖 **[Architecture Guide](docs/architecture.md)** for system design details.\n\n---\n\n## 🤝 Contributing \u0026 License\n\nWe welcome contributions! See **[Contributing Guide](docs/CONTRIBUTING.md)** for development guidelines.\n\n### ⭐ Support\n\nIf this project helps you, please give us a ⭐ on GitHub!\n\n### 💝 Sponsors\n\n**[@o93](https://github.com/o93)** - Lead Sponsor supporting MCP tool enhancement, test infrastructure, and quality improvements.\n\n**[💖 Sponsor this project](https://github.com/sponsors/aimasteracc)**\n\n### 📄 License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n---\n\n## 🧪 Testing\n\n### Test Coverage\n\n| Metric | Value |\n|--------|-------|\n| **Test Suite** | Multi-thousand automated tests across unit, integration, regression, property, benchmark, and compatibility layers |\n| **Code Coverage** | [![Coverage](https://codecov.io/gh/aimasteracc/tree-sitter-analyzer/branch/main/graph/badge.svg)](https://codecov.io/gh/aimasteracc/tree-sitter-analyzer) |\n| **Type Safety** | 100% mypy compliance |\n\n### Running Tests\n\n```bash\n# Run all tests\nuv run pytest tests/ -v\n\n# Run specific test category\nuv run pytest tests/unit/ -v              # Unit tests\nuv run pytest tests/integration/ -v         # Integration tests\nuv run pytest tests/regression/ -m regression  # Regression tests\nuv run pytest tests/benchmarks/ -v         # Benchmark tests\n\n# Run with coverage\nuv run pytest tests/ --cov=tree_sitter_analyzer --cov-report=html\n\n# Run property-based tests\nuv run pytest tests/property/\n\n# Run performance benchmarks\nuv run pytest tests/benchmarks/ --benchmark-only\n```\n\n### Test Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Test Writing Guide](docs/test-writing-guide.md) | Comprehensive guide for writing tests |\n| [Regression Testing Guide](docs/regression-testing-guide.md) | Golden Master methodology and regression testing |\n| [Testing Documentation](docs/TESTING.md) | Project testing standards |\n\n### Test Categories\n\n- **Unit Tests**: Test individual components in isolation\n- **Integration Tests**: Test component interactions\n- **Regression Tests**: Ensure backward compatibility and format stability\n- **Property Tests**: Use Hypothesis-based invariant checking\n- **Benchmark Tests**: Track performance and regression signals\n- **Compatibility Tests**: Validate cross-version behavior\n\n### CI/CD Integration\n\n- **Test Coverage Workflow**: Automated coverage checks on PRs and pushes\n- **Regression Tests Workflow**: Golden Master validation and format stability checks\n- **Performance Benchmarks**: Daily benchmark runs with trend analysis\n- **Quality Checks**: Automated linting, type checking, and security scanning\n\n### Contributing Tests\n\nWhen contributing new features:\n\n1. **Write Tests**: Follow the [Test Writing Guide](docs/test-writing-guide.md)\n2. **Ensure Coverage**: Maintain \u003e80% code coverage\n3. **Run Locally**: `uv run pytest tests/ -v`\n4. **Check Quality**: `uv run ruff check . \u0026\u0026 uv run mypy tree_sitter_analyzer/`\n5. **Update Docs**: Document new tests and features\n\n---\n\n## 📚 Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Installation Guide](docs/installation.md) | Setup for all platforms |\n| [CLI Reference](docs/cli-reference.md) | Complete command reference |\n| [SMART Workflow](docs/smart-workflow.md) | AI-assisted analysis guide |\n| [MCP Tools API](docs/api/mcp_tools_specification.md) | MCP integration details |\n| [Features](docs/features.md) | Language support details |\n| [Architecture](docs/architecture.md) | System design |\n| [Contributing](docs/CONTRIBUTING.md) | Development guidelines |\n| [Test Writing Guide](docs/test-writing-guide.md) | Comprehensive test writing guide |\n| [Regression Testing Guide](docs/regression-testing-guide.md) | Golden Master methodology |\n| [Changelog](CHANGELOG.md) | Version history |\n\n---\n\n**🎯 Built for developers working with large codebases and AI assistants**\n\n*Making every line of code understandable to AI, enabling every project to break through token limitations*\n","funding_links":["https://github.com/sponsors/aimasteracc","https://tidelift.com/funding/github/pypi/tree-sitter-analyzer"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faimasteracc%2Ftree-sitter-analyzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faimasteracc%2Ftree-sitter-analyzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faimasteracc%2Ftree-sitter-analyzer/lists"}