Add cgraph CLI tool and Claude Code indexing skill

AGENTS.md

@@ -21,6 +21,7 @@ Knowledge graph visualization tool for codebases. Python FastAPI backend + React
 
 ```text
 api/                  # Python backend
+  cli.py              # cgraph CLI tool (typer)
   index.py            # FastAPI app, routes, auth, SPA serving
   graph.py            # FalkorDB graph operations (sync + async)
   llm.py              # GraphRAG + LiteLLM chat
@@ -34,6 +35,7 @@ api/                  # Python backend
 app/                  # React frontend (Vite)
   src/components/     # React components (ForceGraph, chat, code-graph, etc.)
   src/lib/            # Utilities
+skills/code-graph/    # Claude Code skill for code graph indexing/querying
 tests/                # Pytest backend tests
   endpoints/          # API endpoint integration tests
 e2e/                  # Playwright E2E tests
@@ -44,6 +46,7 @@ e2e/                  # Playwright E2E tests
 
 ```bash
 make install         # Install all deps (uv sync + npm install)
+make install-cli     # Install cgraph CLI entry point
 make build-dev       # Build frontend (dev mode)
 make build-prod      # Build frontend (production)
 make run-dev         # Build dev frontend + run API with reload
@@ -130,3 +133,22 @@ Key variables (see `.env.template` for full list):
 - `POST /api/analyze_folder` — Analyze local folder
 - `POST /api/analyze_repo` — Clone and analyze repo
 - `POST /api/switch_commit` — Switch to specific commit
+
+## CLI (`cgraph`)
+
+Typer-based CLI wrapping the sync `Graph` and `Project` classes. Outputs JSON to stdout, status to stderr. Entry point: `api/cli.py`.
+
+Install: `make install-cli` or `uv pip install -e .`
+
+```bash
+cgraph ensure-db                          # Start FalkorDB if not running
+cgraph index . --ignore node_modules      # Index local folder
+cgraph index-repo <url>                   # Clone + index a repo
+cgraph list                               # List indexed repos
+cgraph search <prefix> [--repo <name>]    # Full-text prefix search
+cgraph neighbors <id>... [--repo <name>] [--rel <type>] [--label <label>]  # Connected entities
+cgraph paths <src-id> <dest-id> [--repo <name>]  # Call-chain paths
+cgraph info [--repo <name>]              # Repo stats + metadata
+```
+
+`--repo` defaults to the current directory name. Claude Code skill in `skills/code-graph/`.

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install test e2e lint lint-py lint-fe clean build-dev build-prod run-dev run-prod docker-falkordb docker-stop
+.PHONY: help install install-cli test e2e lint lint-py lint-fe clean build-dev build-prod run-dev run-prod docker-falkordb docker-stop
 
 help: ## Show this help message
 	@echo 'Usage: make [target]'
@@ -10,6 +10,9 @@ install: ## Install all dependencies (backend + frontend)
 	uv sync --all-extras
 	npm install --prefix ./app
 
+install-cli: ## Install cgraph CLI entry point
+	uv pip install -e .
+
 build-dev: ## Build frontend for development
 	npm --prefix ./app run build:dev
 

README.md

@@ -26,6 +26,7 @@ code-graph/
 │   ├── project.py        # Repository cloning and analysis orchestration
 │   ├── info.py           # Repository metadata stored in Redis/FalkorDB
 │   ├── prompts.py        # LLM system and prompt templates
+│   ├── cli.py            # cgraph CLI tool (typer)
 │   ├── auto_complete.py  # Prefix search helper
 │   ├── analyzers/        # Source analyzers (Python, Java, C#)
 │   ├── entities/         # Graph/entity models
@@ -37,6 +38,7 @@ code-graph/
 │   ├── package.json      # Frontend dependencies and scripts
 │   ├── vite.config.ts    # Vite config and /api proxy for dev mode
 │   └── tsconfig*.json    # TypeScript config
+├── skills/code-graph/    # Claude Code skill for CLI-driven indexing/querying
 ├── tests/                # Backend/unit and endpoint tests
 ├── e2e/                  # End-to-end helpers and Playwright assets
 ├── Dockerfile            # Unified container image
@@ -145,6 +147,7 @@ In this mode, the FastAPI app serves the built React SPA from `app/dist` on `htt
 
 ```bash
 make install       # Install backend + frontend dependencies
+make install-cli   # Install cgraph CLI entry point
 make build-dev     # Build frontend in development mode
 make build-prod    # Build frontend for production
 make run-dev       # Build dev frontend + run Uvicorn with reload
@@ -157,6 +160,58 @@ make clean         # Remove build/test artifacts
 
 `make test` currently points at the right backend test entrypoint, but some legacy analyzer/git-history tests still need maintenance before the suite passes on a clean checkout.
 
+## CLI Tool (`cgraph`)
+
+CodeGraph includes a CLI tool for indexing codebases and querying the knowledge graph directly from the terminal. All output is JSON (to stdout), with status messages on stderr.
+
+### Install
+
+```bash
+make install-cli
+# or
+uv pip install -e .
+```
+
+### Usage
+
+```bash
+# Ensure FalkorDB is running (auto-starts a Docker container if needed)
+cgraph ensure-db
+
+# Index the current project
+cgraph index . --ignore node_modules --ignore .git --ignore venv --ignore __pycache__
+
+# Index a remote repository
+cgraph index-repo https://github.com/user/repo --ignore node_modules
+
+# List indexed repos
+cgraph list
+
+# Search for entities by name prefix
+cgraph search parse_config
+
+# Explore relationships (what does node 42 call?)
+cgraph neighbors 42 --rel CALLS
+
+# Find call-chain paths between two nodes
+cgraph paths 42 99
+
+# Show repo statistics
+cgraph info
+```
+
+The `--repo` flag defaults to the current directory name. Run `cgraph --help` for full details.
+
+### Claude Code Skill
+
+A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill is included in `skills/code-graph/`. Install it with:
+
+```bash
+npx skills add FalkorDB/code-graph
+```
+
+Then ask Claude things like *"what functions call analyze_sources?"* or *"find the dependency chain between parse_config and send_request"* — it will handle the indexing and querying automatically.
+
 ## Running with Docker
 
 ### Using Docker Compose