# git-ai [![ci](https://github.com/mars167/git-ai-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/mars167/git-ai-cli/actions/workflows/ci.yml) [![release](https://github.com/mars167/git-ai-cli/actions/workflows/release.yml/badge.svg)](https://github.com/mars167/git-ai-cli/actions/workflows/release.yml) [![license](https://img.shields.io/github/license/mars167/git-ai-cli)](./LICENSE) [![npm version](https://img.shields.io/npm/v/@mars167/git-ai)](https://www.npmjs.com/package/@mars167/git-ai) [![npm downloads](https://img.shields.io/npm/dm/@mars167/git-ai)](https://www.npmjs.com/package/@mars167/git-ai) [![Agent Skill](https://img.shields.io/badge/Agent_Skill-git--ai--code--search-blue)](https://skills.sh) [🇨🇳 简体中文](./README.zh-CN.md) | **English** ---

### 🚀 Quick Install **For AI Agents (Claude Code, Cursor, Windsurf, etc.)** ```bash npx skills add mars167/git-ai-cli/skills/git-ai-code-search ``` **For CLI Usage** ```bash npm install -g @mars167/git-ai ```

--- ## Adding a Semantic Layer to Your Codebase, Enabling AI to Evolve from "Reading Code" to "Understanding Code" **Code semantics should be versioned and traceable, just like code itself** git-ai is a local code understanding tool that builds a traceable semantic layer for your codebase using DSR (Deterministic Semantic Record) and Hyper RAG, enabling AI Agents and developers to truly understand code evolution and relationships. ### ✨ Why git-ai? - **🔗 Hyper RAG**: Combines vector retrieval + graph retrieval + DSR for multi-dimensional semantic understanding - **📜 Versioned Semantics**: Every commit has a semantic snapshot, historical changes are clear and traceable - **🔄 Always Available**: Indices travel with code, available immediately after checkout, no rebuild needed - **🤖 AI-Native**: MCP Server enables Claude, Trae and other Agents to deeply understand your codebase - **🔒 Fully Local**: Code never leaves your machine, secure and private - **⚡ Full Lifecycle Support**: From development to Review to refactoring, indices span the entire lifecycle - **📊 Blazing Fast**: 10k files indexed in < 30s, search response < 100ms --- ## ✨ Core Capabilities ### 1️⃣ Semantic Search Find code using natural language, no need to remember file names or function names: ```bash git-ai ai semantic "user authentication logic" git-ai ai semantic "database connection pool configuration" git-ai ai semantic "error handling middleware" ``` ### 2️⃣ Symbol Relationship Analysis Understand relationships between code: ```bash # Find function callers git-ai ai graph callers authenticateUser # Find functions called by this function git-ai ai graph callees authenticateUser # Trace complete call chain git-ai ai graph chain authenticateUser --max-depth 3 ``` ### 3️⃣ Historical Change Tracing Track symbol evolution through DSR: ```bash # View function's historical changes git-ai ai dsr query symbol-evolution authenticateUser --limit 50 # View complete semantic snapshot for a commit git-ai ai dsr context ``` ### 4️⃣ Multi-Language Support Supports multiple mainstream programming languages: | Language | File Extensions | |----------|-----------------| | JavaScript | `.js`, `.jsx` | | TypeScript | `.ts`, `.tsx` | | Java | `.java` | | Python | `.py` | | Go | `.go` | | Rust | `.rs` | | C | `.c`, `.h` | | Markdown | `.md`, `.mdx` | | YAML | `.yml`, `.yaml` | --- ## 💡 Design Philosophy git-ai is not just a search tool, but a "semantic timeline" for your codebase: ### DSR (Deterministic Semantic Record) Each commit corresponds to an immutable semantic snapshot, recording the code structure, symbol relationships, and design intent at that time. Code semantics should be versioned—just like code itself—traceable, comparable, and evolvable. ### Hyper RAG Combines multiple retrieval methods for deeper understanding: - **Vector Retrieval**: Semantic similarity matching - **Graph Retrieval**: Call relationship, inheritance analysis - **DSR Retrieval**: Historical evolution tracing ### Decentralized Semantics Indices travel with code, no central server required. checkout, branch, tag—all can use consistent semantic indices immediately. ### Server Mode MCP Server enables any AI Agent to invoke indices, achieving true AI-assisted development. --- ## 🎯 Use Cases ### Scenario 1: Newcomers Quickly Understanding Large Projects > "Just joined the team, facing 100k lines of code, where do I start?" ```bash # 1. Get project global view git-ai ai repo-map --max-files 20 # 2. Search core business logic git-ai ai semantic "order processing flow" # 3. Trace key function call chains git-ai ai graph chain processOrder --max-depth 5 ``` *From design to development, semantic indices remain consistent* ### Scenario 2: Pre-Refactoring Impact Analysis > "About to refactor this function, what will it affect?" ```bash # Find all callers git-ai ai graph callers deprecatedFunction # Trace historical changes, understand design intent git-ai ai dsr query symbol-evolution deprecatedFunction --all ``` *DSR traces historical changes, understanding design intent* ### Scenario 3: Bug Localization and Root Cause Analysis > "User reported an error, but don't know where the problem is" ```bash # Search related error handling code git-ai ai semantic "user login failure handling" # View error propagation path git-ai ai graph chain handleLoginError --direction upstream ``` *Full lifecycle indices, quickly locate problem roots* ### Scenario 4: AI Agent-Assisted Development > "Let Claude Desktop help me understand this project" After configuring git-ai MCP Server in Claude Desktop, you can converse directly: > "Help me analyze this project's architecture, find all payment-related code, and explain their relationships" Claude will automatically invoke git-ai tools to provide deep analysis. *Enabling AI to evolve from "reading code" to "understanding code"* --- ## 🏗️ System Architecture ```mermaid graph TB A[Git Repository] -->|On Commit| B[DSR\nDeterministic Semantic Record] B --> C[.git-ai/dsr/commit.json\nSemantic Snapshot] C -->|Index Rebuild| D[LanceDB\nVector Database] C -->|Index Rebuild| E[CozoDB\nGraph Database] D --> F[MCP Server] E --> F F -->|Tool Call| G[AI Agent\nClaude Desktop / Trae] F -->|CLI| H[Developer] C -->|Cross-Version| I[Semantic Timeline\nTraceable · Comparable · Evolvable] style B fill:#e1f5ff,stroke:#333 style C fill:#e8f5e9,stroke:#333 style D fill:#fff4e1,stroke:#333 style E fill:#fff4e1,stroke:#333 style F fill:#e8f5e9,stroke:#333 style G fill:#f3e5f5,stroke:#333 style I fill:#fce4ec,stroke:#333 ``` **Core Components**: - **DSR (Deterministic Semantic Record)**: Immutable semantic snapshots stored per commit, versioned semantics - **LanceDB + SQ8**: High-performance vector database, supporting semantic search - **CozoDB**: Graph database, supporting AST-level relationship queries - **MCP Server**: Standard protocol interface, for AI Agent invocation --- ## 📊 Comparison with Other Tools | Feature | git-ai | GitHub Code Search | Sourcegraph | |---------|--------|-------------------|-------------| | Local Execution | ✅ | ❌ | ❌ | | AST-Level Analysis | ✅ | ❌ | ✅ | | Versioned Semantics | ✅ | ❌ | ❌ | | Historical Change Tracing | ✅ | ❌ | ❌ | | AI Agent Integration | ✅ | ❌ | ❌ | | Free & Open Source | ✅ | ❌ | ❌ | | Semantic Search | ✅ | ✅ | ✅ | | Call Chain Analysis | ✅ | ❌ | ✅ | --- ## 🚀 Quick Start ### 1. Install ```bash npm install -g @mars167/git-ai ``` ### 2. Initialize Repository ```bash cd your-project git-ai ai index --overwrite ``` ### 3. Start Using Immediately ```bash # Search code using natural language git-ai ai semantic "user authentication logic" # View function call relationships git-ai ai graph callers authenticateUser ``` **Actual Output Example**: ```json [ {

git-ai-mcp

Installation

SKILL.md