GitSpec 🤖

中文文档

GitSpec is a powerful AI-driven CLI tool that reverse engineers GitHub repositories into comprehensive documentation. It analyzes your codebase using LLMs (OpenAI, Claude, etc.) and generates detailed specifications, including Product Requirements (PRD), Architecture diagrams, API specs, Database schemas, and UI/UX analysis.

🚀 Key Features

• Multi-Agent Analysis: Orchestrates specialized AI agents (Architecture, API, Database, UI, Product) to deeply understand your code.
• Full Spec Generation: Automatically generates:
  • 🏗️ Architecture Document: System overview, tech stack, and Mermaid C4 diagrams.
  • 🔌 API Specification: OpenAPI (Swagger) definitions.
  • 🗄️ Database Schema: ER diagrams and table definitions.
  • 🎨 UI/UX Analysis: Component library and page structure.
  • 📝 PRD (Product Requirement Document): User stories and functional requirements.
• Vector Search: Built-in RAG (Retrieval-Augmented Generation) using PGlite vector database to query your codebase.
• Flexible LLM Support: Works with:
  • OpenAI (GPT-4o, GPT-3.5)
  • Anthropic (Claude 3.5 Sonnet, Opus)
  • OpenRouter (Access to any model)
  • Cloudflare Workers AI (Llama 3, etc.)
  • Local Models (Ollama, LocalAI via OpenAI-compatible API)
• Interactive Configuration: Easy setup wizard to configure API keys and models.

📦 Installation

# Clone the repository
git clone https://github.com/yourusername/git-spec.git
cd git-spec

# Install dependencies
bun install

# Build the project
bun run build

# Link globally (optional)
npm link

🛠️ Usage

1. Configuration

Run the interactive setup to configure your LLM provider and API keys:

bun run src/index.ts config
# Or if installed globally:
git-spec config

2. Generate Documentation

Analyze a GitHub repository and generate all specifications:

bun run src/index.ts generate <github-repo-url>
# Example:
# bun run src/index.ts generate https://github.com/facebook/react

The documentation will be saved in the docs/ folder.

3. Chat with Codebase

Ask questions about the indexed codebase:

bun run src/index.ts query "How does the authentication middleware work?"

4. Manual Indexing

Index a local directory into the vector database without generating full docs:

bun run src/index.ts index ./path/to/local/repo

⚙️ Configuration

You can manually configure settings in the .env file or use the config command.

| Variable | Description | Default | | :--- | :--- | :--- | | LLM_PROVIDER | openai, anthropic, openrouter, cloudflare, other | openai | | LLM_MODEL | Model name (e.g., gpt-4o, claude-3-5-sonnet) | gpt-4o | | OPENAI_API_KEY | Key for OpenAI (and Embeddings) | - | | ANTHROPIC_API_KEY | Key for Anthropic | - | | OPENROUTER_API_KEY | Key for OpenRouter | - | | CLOUDFLARE_API_TOKEN | Token for Cloudflare Workers AI | - | | CLOUDFLARE_ACCOUNT_ID | Account ID for Cloudflare | - | | EMBEDDING_PROVIDER | openai, openrouter, cloudflare, other | openai | | EMBEDDING_MODEL | Embedding model (e.g., text-embedding-3-small, @cf/baai/bge-small-en-v1.5) | text-embedding-3-small | | EMBEDDING_BASE_URL | Custom base URL for embeddings | - |

🏗️ Architecture

GitSpec uses a multi-agent system powered by LangChain:

1. RepoLoader: Clones and analyzes the file structure.
2. CodeParser & Chunker: Parses code into ASTs and chunks them for vector storage.
3. VectorStore (PGlite): Stores code embeddings locally for fast retrieval.
4. Agents:
   • ArchitectureAgent: High-level system design.
   • APIAgent: Endpoint extraction.
   • DatabaseAgent: Schema analysis.
   • UIAgent: Frontend component analysis.
   • ProductAgent: Synthesizes technical details into a PRD.
5. SpecMerger: Combines all outputs into a structured documentation site.

📄 License

MIT