Metadata-Version: 2.4
Name: codegraph-cli
Version: 2.0.0
Summary: AI-powered code intelligence CLI with multi-agent analysis, impact graphs, and conversational coding.
Author-email: Ali Nasir <ali@codegraph.dev>
License: MIT
Project-URL: Homepage, https://github.com/al1-nasir/codegraph-cli
Project-URL: Documentation, https://github.com/al1-nasir/codegraph-cli#readme
Project-URL: Repository, https://github.com/al1-nasir/codegraph-cli
Project-URL: Issues, https://github.com/al1-nasir/codegraph-cli/issues
Project-URL: Changelog, https://github.com/al1-nasir/codegraph-cli/blob/main/CHANGELOG.md
Keywords: code-analysis,code-intelligence,cli,ai,code-graph,rag,impact-analysis,refactoring,crewai,multi-agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Environment :: Console
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: typer<1.0.0,>=0.12.0
Requires-Dist: toml>=0.10.2
Requires-Dist: lancedb>=0.4.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: tree-sitter>=0.24.0
Requires-Dist: tree-sitter-python>=0.23.0
Requires-Dist: tree-sitter-javascript>=0.23.0
Requires-Dist: tree-sitter-typescript>=0.23.0
Requires-Dist: litellm>=1.30.0
Provides-Extra: crew
Requires-Dist: crewai>=0.80.0; extra == "crew"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: crewai>=0.80.0; extra == "all"
Requires-Dist: google-generativeai>=0.5.0; extra == "all"
Dynamic: license-file

# CodeGraph CLI

**Code intelligence from the terminal. Semantic search, impact analysis, multi-agent code generation, and conversational coding — all backed by your choice of LLM.**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org)
[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://github.com/al1-nasir/codegraph-cli)

---

## Overview

CodeGraph CLI (`cg`) parses your codebase into a semantic graph, then exposes that graph through search, impact analysis, visualization, and a conversational interface. It supports six LLM providers and optionally runs a CrewAI multi-agent system that can read, write, patch, and rollback files autonomously.

Core capabilities:

- **Semantic Search** — find code by meaning, not string matching
- **Impact Analysis** — trace multi-hop dependencies before making changes
- **Graph Visualization** — interactive HTML and Graphviz DOT exports
- **Conversational Chat** — natural language coding sessions with RAG context
- **Multi-Agent System** — CrewAI-powered agents for code generation, refactoring, and analysis
- **File Rollback** — automatic backups before every file modification

---

## Installation

```bash
pip install codegraph-cli
```

With CrewAI multi-agent support:

```bash
pip install codegraph-cli[crew]
```

For development:

```bash
git clone https://github.com/al1-nasir/codegraph-cli.git
cd codegraph-cli
pip install -e ".[dev]"
```

---

## Quick Start

### 1. Configure your LLM provider

```bash
cg setup
```

This runs an interactive wizard that writes configuration to `~/.codegraph/config.toml`. Alternatively, switch providers directly:

```bash
cg set-llm openrouter
cg set-llm groq
cg set-llm ollama
```

### 2. Index a project

```bash
cg index /path/to/project --name myproject
```

This parses the source tree using tree-sitter, builds a dependency graph in SQLite, and generates embeddings for semantic search.

### 3. Use it

```bash
cg search "authentication logic"
cg impact UserService --hops 3
cg graph process_payment --depth 2
cg chat start
cg chat start --crew    # multi-agent mode
```

---

## Supported LLM Providers

| Provider | Type | Configuration |
|----------|------|---------------|
| Ollama | Local, free | `cg set-llm ollama` |
| Groq | Cloud, free tier | `cg set-llm groq` |
| OpenAI | Cloud | `cg set-llm openai` |
| Anthropic | Cloud | `cg set-llm anthropic` |
| Gemini | Cloud | `cg set-llm gemini` |
| OpenRouter | Cloud, multi-model | `cg set-llm openrouter` |

All configuration is stored in `~/.codegraph/config.toml`. No environment variables required.

```bash
cg show-llm        # view current provider, model, and endpoint
cg unset-llm       # reset to defaults
```

---

## Commands

### Project Management

```bash
cg index <path> [--name NAME]       # parse and index a codebase
cg list-projects                     # list all indexed projects
cg load-project <name>               # switch active project
cg current-project                   # print active project name
cg delete-project <name>             # remove a project index
cg merge-projects <src> <dst>        # merge two project graphs
cg unload-project                    # unload without deleting
```

### Search and Analysis

```bash
cg search <query> [--top-k N]       # semantic search across the graph
cg impact <symbol> [--hops N]       # multi-hop dependency impact analysis
cg graph <symbol> [--depth N]       # ASCII dependency graph
cg rag-context <query> [--top-k N]  # raw RAG retrieval for debugging
```

### Graph Export

```bash
cg export-graph --format html        # interactive vis.js visualization
cg export-graph --format dot         # Graphviz DOT format
cg export-graph MyClass -f html -o out.html  # focused subgraph
```

### Interactive Chat

```bash
cg chat start                        # start or resume a session
cg chat start --new                  # force a new session
cg chat start --crew                 # multi-agent mode (CrewAI)
cg chat start -s <id>                # resume a specific session
cg chat list                         # list all sessions
cg chat delete <id>                  # delete a session
```

In-chat commands:

| Command | Mode | Description |
|---------|------|-------------|
| `/help` | Both | Show available commands |
| `/clear` | Both | Clear conversation history |
| `/new` | Both | Start a fresh session |
| `/exit` | Both | Save and exit |
| `/apply` | Standard | Apply pending code proposal |
| `/preview` | Standard | Preview pending file changes |
| `/backups` | Crew | List all file backups |
| `/rollback <file>` | Crew | Restore a file from backup |
| `/undo <file>` | Crew | Alias for rollback |

### Code Generation (v2)

```bash
cg v2 generate "add a REST endpoint for user deletion"
cg v2 review src/auth.py --check-security
cg v2 refactor rename-symbol OldName NewName
cg v2 refactor extract-function target_fn 45 60
cg v2 test unit process_payment
cg v2 diagnose check src/
cg v2 diagnose fix src/auth.py
cg v2 rollback <file>
cg v2 list-backups
```

---

## Multi-Agent System

When you run `cg chat start --crew`, CodeGraph launches a CrewAI pipeline with four specialized agents:

| Agent | Role | Tools |
|-------|------|-------|
| Project Coordinator | Routes tasks to the right specialist | Delegation only |
| File System Engineer | File I/O, directory traversal, backups | list_directory, read_file, write_file, patch_file, delete_file, rollback_file, file_tree |
| Senior Software Developer | Code generation, refactoring, bug fixes | All tools (file ops + code analysis) |
| Code Intelligence Analyst | Search, dependency tracing, explanations | search_code, grep, project_summary, read_file |

Every file modification automatically creates a timestamped backup in `~/.codegraph/backups/`. Files can be rolled back to any previous state via `/rollback` or `cg v2 rollback`.

---

## Architecture

```
CLI Layer (Typer)
    |
    +-- MCPOrchestrator ----------> GraphStore (SQLite)
    |       |                           |
    |       +-- Parser (tree-sitter)    +-- VectorStore (LanceDB)
    |       +-- RAGRetriever            |
    |       +-- LLM Adapter             +-- Embeddings
    |
    +-- ChatAgent (standard mode)
    |
    +-- CrewChatAgent (--crew mode)
            |
            +-- Coordinator Agent
            +-- File System Agent -----> 8 file operation tools
            +-- Code Gen Agent --------> all 11 tools
            +-- Code Analysis Agent ---> 3 search/analysis tools
```

**Parser**: tree-sitter grammars for Python, JavaScript, and TypeScript. Extracts modules, classes, functions, imports, and call relationships into a directed graph.

**Storage**: SQLite for the code graph (nodes + edges), LanceDB for vector embeddings. All data stored under `~/.codegraph/`.

**LLM Adapter**: Unified interface across six providers. For CrewAI, models are routed through LiteLLM. Configuration is read exclusively from `~/.codegraph/config.toml`.

---

## Project Structure

```
codegraph_cli/
    cli.py               # main Typer application, all top-level commands
    cli_chat.py           # interactive chat REPL with styled output
    cli_setup.py          # setup wizard, set-llm, unset-llm, show-llm
    cli_v2.py             # v2 code generation commands
    config.py             # loads config from TOML
    config_manager.py     # TOML read/write, provider validation
    llm.py                # multi-provider LLM adapter
    parser.py             # tree-sitter AST parsing
    storage.py            # SQLite graph store
    embeddings.py         # hash-based embedding model
    rag.py                # RAG retriever
    vector_store.py       # LanceDB vector store
    orchestrator.py       # coordinates parsing, search, impact
    graph_export.py       # DOT and HTML export
    project_context.py    # unified file access layer
    crew_tools.py         # 11 CrewAI tools (file ops + analysis)
    crew_agents.py        # 4 specialized CrewAI agents
    crew_chat.py          # CrewAI orchestrator with rollback
    chat_agent.py         # standard chat agent
    chat_session.py       # session persistence
    models.py             # core data models
    models_v2.py          # v2 models (ChatSession, CodeProposal)
    templates/
        graph_interactive.html  # vis.js graph template
```

---

## Development

```bash
git clone https://github.com/al1-nasir/codegraph-cli.git
cd codegraph-cli
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,crew]"
pytest
```

---

## License

MIT. See [LICENSE](LICENSE).
