npm package: @latentforce/latentgraph
Description: Latentgraph CLI - AI-powered code intelligence with MCP support
Author: Latentforce
Latest version: 1.0.10

# @latentforce/latentgraph

AI-powered code intelligence CLI and MCP server.

Latentgraph indexes your codebase, builds a dependency relationship graph (DRG), and provides AI-powered insights via MCP tools — enabling AI coding assistants to understand your project's structure, dependencies, and blast radius of changes.

---

## Table of Contents

- [Installation](#installation)
- [Getting an API Key](#getting-an-api-key)
- [Quick Start](#quick-start)
- [CLI Reference](#cli-reference)
  - [lgraph start](#lgraph-start)
  - [lgraph init](#lgraph-init)
  - [lgraph status](#lgraph-status)
  - [lgraph update-drg](#lgraph-update-drg)
  - [lgraph stop](#lgraph-stop)
  - [lgraph add](#lgraph-add)
  - [lgraph config](#lgraph-config)
- [MCP Integration](#mcp-integration)
  - [Supported Tools](#supported-tools)
  - [Claude Desktop (manual)](#claude-desktop-manual)
- [Scan Targets](#scan-targets)
- [MCP Tools](#mcp-tools)
- [Configuration Files](#configuration-files)

---

## Installation

```bash
npm install -g @latentforce/latentgraph
```

---

## Getting an API Key

1. Go to **https://latentgraph.latentforce.ai/auth**
2. **Sign up** for an account
3. **Sign in** to your dashboard
4. Copy your **API key** from the dashboard

From the dashboard you can also **create a project** and **select a migration template** — or you can do both directly from the CLI.

---

## Quick Start

All commands must be run from your project's root directory:

```bash
cd /path/to/your/project
```

### Option A — Interactive (recommended)

```bash
lgraph start    # Step 1: Configure API key and project, launch daemon
lgraph init     # Step 2: Scan and index project files
lgraph status   # Step 3: Verify everything is connected
```

When you run `lgraph start` interactively, it will:

1. **Ask for your API key** — paste the key from your dashboard, or choose guest mode
2. **Ask to create or select a project** — you can either:
   - Select an existing project from your account
   - Create a new project directly from the CLI (prompts for a name and migration template)

### Option B — Non-interactive (CI/CD)

```bash
lgraph init -k YOUR_KEY -n "My App"
```

If a project named "My App" already exists in your account it will be reused; otherwise a new one is created.

---

## CLI Reference

| Command | Description |
|---|---|
| `lgraph start` | Start the daemon and configure the project |
| `lgraph init` | Scan and index project files |
| `lgraph status` | Show current status |
| `lgraph update-drg` | Update the dependency relationship graph |
| `lgraph stop` | Stop the daemon |
| `lgraph add [tool]` | Add Latentgraph MCP server to an AI coding tool |
| `lgraph config` | Manage configuration |

---

### `lgraph start`

Resolves authentication, configures the project, and launches a background daemon that maintains a WebSocket connection to the Latentgraph backend.

**Interactive flow (no flags):**

1. Prompts for your API key or guest mode
2. Prompts to select an existing project or create a new one
   - If creating: asks for a project name and lets you pick a migration template
3. Saves config to `.lgraph/config.json`
4. Launches the background daemon

| Flag | Short | Description |
|---|---|---|
| `--guest` | | Use guest authentication (auto-creates a temporary project) |
| `--api-key <key>` | `-k` | Provide API key directly (skips the key prompt) |
| `--project-name <name>` | `-n` | Create new project or match existing by name |
| `--project-id <id>` | | Use existing project UUID |
| `--template <id>` | | Migration template ID for project creation |

```bash
lgraph start                           # Interactive setup
lgraph start --guest                   # Quick start without API key
lgraph start -k <key> -n "My App"      # Non-interactive
```

---

### `lgraph init`

Performs a full project scan — collects the file tree, categorizes files (source, config, assets), gathers git info, and sends everything to the Latentgraph backend for indexing. Automatically starts the daemon if not running.

If the project is already indexed, you will be prompted to re-index. Use `--force` to skip the prompt.

| Flag | Short | Description |
|---|---|---|
| `--force` | `-f` | Force re-indexing even if already indexed |
| `--guest` | | Use guest authentication |
| `--api-key <key>` | `-k` | Provide API key directly |
| `--project-name <name>` | `-n` | Create new project or match existing by name |
| `--project-id <id>` | | Use existing project UUID |
| `--template <id>` | | Migration template ID for project creation |

```bash
lgraph init                            # Interactive initialization
lgraph init -f                         # Force re-index without prompt
lgraph init --guest                    # Quick init with guest auth
lgraph init -k <key> -n "My App"       # Non-interactive
```

---

### `lgraph status`

Displays a comprehensive overview of the current Latentgraph setup — API key status, project details, backend indexing state, and daemon health.

```bash
lgraph status
```

---

### `lgraph update-drg`

Scans source files across all supported languages, detects git changes, and sends file contents to the backend for dependency analysis.

**Supported languages:**

| Language | Extensions |
|---|---|
| JavaScript / TypeScript | `.js` `.jsx` `.ts` `.tsx` `.mjs` `.cjs` |
| Python | `.py` |
| C# | `.cs` |
| C / C++ | `.cpp` `.cc` `.cxx` `.c` `.h` `.hpp` |

| Flag | Short | Description |
|---|---|---|
| `--baseline` | `-b` | Full re-analysis of all source files (slower) |
| `--mode <mode>` | `-m` | Explicit mode: `baseline` or `incremental` |

**Modes:**

- **incremental** (default) — sends only git-changed files for faster updates
- **baseline** — sends all source files for a full re-analysis

```bash
lgraph update-drg                      # Incremental update (default)
lgraph update-drg -b                   # Full re-analysis (short)
lgraph update-drg --baseline           # Full re-analysis (long)
```

---

### `lgraph stop`

Stops the background daemon process. The daemon can be restarted with `lgraph start`.

```bash
lgraph stop
```

---

### `lgraph add`

Configures the Latentgraph MCP server in your AI coding tool. Run `lgraph add` without arguments to see the list of supported tools.

```bash
lgraph add [tool]
```

---

### `lgraph config`

Manages Latentgraph configuration. Running `lgraph config` with no subcommand displays the current configuration.

#### Subcommands

| Subcommand | Description |
|---|---|
| `lgraph config show` | Display current configuration (default) |
| `lgraph config set <key> [value]` | Set a configuration value |
| `lgraph config clear [key]` | Clear a specific key or all configuration |

#### Configurable keys

| Key | Description |
|---|---|
| `api-key` | Your Latentgraph API key |
| `api-url` | Backend API URL |
| `orch-url` | Orchestrator URL |
| `ws-url` | WebSocket URL |

URLs can also be set via environment variables: `LGRAPH_API_URL`, `LGRAPH_ORCH_URL`, `LGRAPH_WS_URL`.

```bash
lgraph config                                      # Show current config
lgraph config set api-key sk-abc123                # Set API key
lgraph config set api-url http://localhost:9000    # Set API URL
lgraph config clear api-key                        # Clear API key
lgraph config clear urls                           # Clear all custom URLs
lgraph config clear                                # Clear all config
```

---

## MCP Integration

After initializing your project, use `lgraph add` to configure the Latentgraph MCP server in your AI coding tool.

### Supported Tools

| Tool | Command | Config method |
|---|---|---|
| Shiftcode | `lgraph add shiftcode` | Writes `shiftcode.json` |
| Claude Code | `lgraph add claude-code` | Runs `claude mcp add-json` |
| Opencode | `lgraph add opencode` | Writes `opencode.json` |
| Codex | `lgraph add codex` | Runs `codex mcp add` |
| GitHub Copilot | `lgraph add copilot` | Writes `.vscode/mcp.json` |
| Factory Droid | `lgraph add droid` | Runs `droid mcp add` |

For CLI-based tools, if the tool's CLI is not found on `PATH`, the command will print manual setup instructions instead.

### Claude Desktop (manual)

Add to your Claude Desktop config file:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "lgraph": {
      "command": "lgraph",
      "args": ["mcp"],
      "env": {
        "LGRAPH_PROJECT_ID": "YOUR_PROJECT_ID"
      }
    }
  }
}
```

---

## Scan Targets

Latentgraph uses `.lgraph/scan_target.json` to control which parts of your codebase are scanned and in which language. This is especially useful for monorepos or multi-language projects.

A default template is **automatically created** the first time you run `lgraph init` or `lgraph start`. When left as the default (single entry with `language: null`), the server auto-detects scan targets.

### Format

The file is a JSON array. Each entry has:

| Field | Type | Description |
|---|---|---|
| `language` | `string \| null` | Language to use, or `null` for auto-detect |
| `path` | `string` | Relative path from project root (`""` for root) |

**Valid language values:** `javascript`, `typescript`, `python`, `cpp`, `csharp`

### Default (auto-detect)

```json
[
  {
    "language": null,
    "path": ""
  }
]
```

### Examples

**Single-language TypeScript project:**

```json
[
  {
    "language": "typescript",
    "path": ""
  }
]
```

**Monorepo with multiple languages:**

```json
[
  {
    "language": "typescript",
    "path": "frontend"
  },
  {
    "language": "python",
    "path": "backend"
  },
  {
    "language": "csharp",
    "path": "services/auth"
  }
]
```

**C++ engine in a subdirectory:**

```json
[
  {
    "language": "cpp",
    "path": "engine/src"
  }
]
```

---

## MCP Tools

| Tool | Description |
|---|---|
| `project_overview` | Highest-level project context: architecture, tech stack, entry points, and top-level modules |
| `file_summary` | Summary of a file with optional parent directory context |
| `module_summary` | Full documentation for the module that owns a given file, including DRG cluster metadata and parent/child module relationships |
| `dependencies` | All dependencies for a file with relationship summaries |
| `blast_radius` | Files that would be affected if a given file is modified or deleted |

Each tool accepts an optional `project_id` parameter. If omitted, it falls back to the `LGRAPH_PROJECT_ID` environment variable.

---

## Configuration Files

| File | Location | Description |
|---|---|---|
| Global config | `~/.lgraph/config.json` | API key and server URLs |
| Project config | `.lgraph/config.json` | Project ID, name, and agent info |
| Scan targets | `.lgraph/scan_target.json` | Language and path targets for scanning (auto-created) |