Content
# codegraph-summary
> CodeGraph Summary Tool — Generates business summaries for code symbols, supports semantic search and PRD association analysis.
Integrate CodeGraph with Large Language Models (LLM) to search code, understand system architecture, and track requirements coverage using business terms.
## Features
- **One-click Initialization** — `codegraph-summary init` automatically builds index + generates summaries
- **Semantic Search** — Search code using business terms like "transaction query" or "refund process"
- **FTS5 trigram** — High-quality substring matching without a tokenizer
- **Graph Expansion** — Search results show call chains (who called it, and who it called)
- **PRD Association** — Import requirement documents, automatically associate with code implementations
- **Multi-protocol LLM** — Supports Anthropic / OpenAI compatible API
- **Heuristic Degradation** — Generates basic summaries without LLM API Key
- **Three Interfaces** — CLI / HTTP API / MCP Server
## Quick Start
### Installation
```bash
npm install -g codegraph-summary
```
Requires [CodeGraph](https://github.com/colbymchenry/codegraph) to be installed:
```bash
npm install -g @colbymchenry/codegraph
```
### One-click Initialization
```bash
cd your-project
codegraph-summary init
```
This will automatically:
1. Build CodeGraph code index (if it doesn't exist)
2. Generate Chinese summaries for all exported symbols using LLM
### Configure LLM (Optional)
Create a `.env` file in the project root directory:
```env
SUMMARY_LLM_API_KEY=your-api-key
SUMMARY_LLM_BASE_URL=https://api.anthropic.com
SUMMARY_LLM_MODEL=claude-sonnet-4-20250514
SUMMARY_LLM_API_TYPE=anthropic
```
You can still use the tool without configuring an API Key (heuristic mode uses function signatures as summaries).
## Usage
### Search Code
```bash
codegraph-summary search "transaction query" -p /path/to/project
```
### View Status
```bash
codegraph-summary status -p /path/to/project
```
### Force Re-generation
```bash
codegraph-summary init -f
codegraph-summary generate -f -p /path/to/project
```
### PRD Association
```bash
# Import PRD documents (supports .md / .docx / .pdf / .txt)
codegraph-summary prd-import ./docs/prd.md -p /path/to/project
# Search code using requirement descriptions
codegraph-summary prd-search "user refund process" -p /path/to/project
# View requirement coverage
codegraph-summary prd-coverage -p /path/to/project
```
### MCP Server (AI Assistant Integration)
```bash
codegraph-summary mcp
```
Add this to your Claude Code MCP configuration to let the AI assistant directly search code summaries.
### HTTP API
```bash
codegraph-summary serve --port 3000
```
## Environment Variables
| Variable | Description | Default |
| --- | --- | --- |
| `SUMMARY_LLM_API_KEY` | LLM API Key | (empty, heuristic mode) |
| `SUMMARY_LLM_BASE_URL` | LLM API URL | (empty) |
| `SUMMARY_LLM_MODEL` | Model name | (empty) |
| `SUMMARY_LLM_API_TYPE` | `anthropic` or `openai` | `anthropic` |
| `SUMMARY_LLM_BATCH_SIZE` | Number of symbols per batch | `10` |
| `SUMMARY_LLM_CONCURRENCY` | Concurrent requests | `3` |
| `SUMMARY_VECTOR_GATEWAY_URL` | Vector service URL (optional) | (empty) |
| `CODEGRAPH_BIN` | Custom CodeGraph path | (auto-detect) |
## System Requirements
- Node.js >= 22.5.0
- [CodeGraph](https://github.com/colbymchenry/codegraph) (for code indexing)
- PDF support requires `poppler-utils` (macOS: `brew install poppler`)
- DOCX support requires `unzip` command
## License
MIT
