npm package: @latentforce/shift
Description: Shift CLI - AI-powered code intelligence with MCP support
Author: Latentforce
Latest version: 1.0.17
Deprecated: @latentforce/shift has been renamed to @latentforce/latentgraph. This package will no longer receive updates.

# @latentforce/shift

AI-powered code intelligence CLI and MCP server for Claude.

Shift indexes your codebase, builds a dependency relationship graph (DRG), and provides AI-powered insights via MCP tools — enabling Claude to understand your project's structure, dependencies, and blast radius of changes.

## Installation

```bash
npm install -g @latentforce/shift
```

## Getting an API Key

1. Go to **https://dev-shift-lite.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 (see below).

## Quick Start

All commands **must be run** from your project's root directory:

```bash
cd /path/to/your/project
```

### Option A: Interactive (recommended)

```bash
shift-cli start    # Step 1: Configure API key and project, launch daemon
shift-cli init     # Step 2: Scan and index project files
shift-cli status   # Step 3: Verify everything is connected
```

When you run `shift-cli 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 (if you created one on the dashboard)
   - **Create a new project** from the CLI — it will prompt for a name (defaults to your directory name) and let you select a migration template

### Option B: Non-interactive (CI/CD friendly)

```bash
shift-cli init --api-key YOUR_KEY --project-name "My App"
```

If a project named "My App" already exists in your account, it will be reused. Otherwise a new one is created with the specified template.


## CLI Commands

| Command | Description |
|---------|-------------|
| `shift-cli start` | Start the daemon and configure the project |
| `shift-cli init` | Scan and index project files |
| `shift-cli status` | Show current status |
| `shift-cli update-drg` | Update the dependency relationship graph |
| `shift-cli stop` | Stop the daemon |
| `shift-cli add <tool>` | Add Shift MCP server to an AI coding tool |
| `shift-cli config` | Manage configuration |

### `shift-cli start`

Resolves authentication, configures the project, and launches a background daemon that maintains a WebSocket connection to the Shift backend.

**When run interactively (no flags):**
1. Prompts you to enter your API key or choose guest mode
2. Prompts you 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 `.shift/config.json`
4. Launches the background daemon

If you already created a project on the dashboard (https://dev-shift-lite.latentforce.ai), you can select it from the list. Otherwise, create one directly from the CLI.

| Flag | Description |
|------|-------------|
| `--guest` | Use guest authentication (auto-creates a temporary project) |
| `--api-key <key>` | Provide API key directly (skips the key prompt) |
| `--project-name <name>` | Create new project or match existing by name (skips project prompt) |
| `--project-id <id>` | Use existing project UUID (skips project prompt) |
| `--template <id>` | Migration template ID for project creation |

```bash
shift-cli start                                     # Interactive setup (prompts for key + project)
shift-cli start --guest                              # Quick start without API key
shift-cli start --api-key <key> --project-name "My App"  # Non-interactive
```

### `shift-cli init`

Performs a full project scan — collects the file tree, categorizes files (source, config, assets), gathers git info, and sends everything to the Shift 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 | Description |
|------|-------------|
| `--guest` | Use guest authentication (auto-creates a temporary project) |
| `--api-key <key>` | Provide API key directly |
| `--project-name <name>` | Create new project or match existing by name |
| `--project-id <id>` | Use existing project UUID |
| `--template <id>` | Migration template ID for project creation |
| `-f, --force` | Force re-indexing even if already indexed |

```bash
shift-cli init                     # Interactive initialization
shift-cli init --force             # Force re-index without prompt
```

### `shift-cli status`

Displays comprehensive information about the current Shift setup — API key status, project details, backend indexing state, and daemon health.

```bash
shift-cli status
```

### `shift-cli update-drg`

Scans source files across all supported languages, detects git changes, and sends file contents to the backend for dependency analysis.

**Supported languages and extensions:**

| Language | Extensions |
|----------|------------|
| JavaScript / TypeScript | `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` |
| Python | `.py` |
| C# | `.cs` |
| C/C++ | `.cpp`, `.cc`, `.cxx`, `.h`, `.hpp`, `.c` |

| Flag | Description |
|------|-------------|
| `-m, --mode <mode>` | `baseline` (all files) or `incremental` (git-changed only, default) |

**Modes:**
- **incremental** (default) — sends only git-changed files for faster updates
- **baseline** — sends all source files for a full re-analysis

```bash
shift-cli update-drg                       # Incremental update (default)
shift-cli update-drg -m baseline           # Full re-analysis
```

### `shift-cli stop`

Stops the background daemon process.

```bash
shift-cli stop
```

### `shift-cli config`

Manage Shift configuration (URLs, API key).

| Action | Description |
|--------|-------------|
| `show` | Display current configuration (default) |
| `set <key> <value>` | Set a configuration value |
| `clear [key]` | Clear a specific key or all configuration |

**Configurable key:** `api-key`

```bash
shift-cli config                                      # Show config
shift-cli config set api-key sk-abc123                 # Set API key
shift-cli config clear api-key                         # Clear API key
shift-cli config clear                                 # Clear all config
```
## MCP Integration

After initializing your project, use `shift-cli add` to configure Shift's MCP server in your AI coding tool:

```bash
shift-cli add <tool>
```

### Supported tools

| Tool | Command | Config method |
|------|---------|---------------|
| Claude Code | `shift-cli add claude-code` | Runs `claude mcp add-json` |
| Opencode | `shift-cli add opencode` | Writes `opencode.json` |
| Codex | `shift-cli add codex` | Runs `codex mcp add` |
| GitHub Copilot | `shift-cli add copilot` | Writes `.vscode/mcp.json` |
| Factory Droid | `shift-cli add droid` | Runs `droid mcp add` |

For CLI-based tools, if the CLI is not installed, the command will print manual setup instructions.

### Claude Desktop (manual)

Add to your config file (`%APPDATA%\Claude\claude_desktop_config.json` on Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "shift": {
      "command": "shift-cli",
      "args": ["mcp"],
      "env": {
        "SHIFT_PROJECT_ID": "YOUR_PROJECT_ID"
      }
    }
  }
}
```
## `.shift/scan_target.json`

Shift uses a `scan_target.json` file inside the `.shift/` directory to let you specify which parts of your codebase to scan and in which language. This is especially useful for monorepos or projects with multiple languages.

A default template is **automatically created** the first time you run `shift-cli init` or `shift-cli start`. By default, it is unconfigured and the server will auto-detect scan targets. Edit the file to manually specify targets.

### Valid Languages

```
javascript, typescript, python, cpp, csharp
```

### Format

The file is a JSON array of objects, each with:

| Field | Type | Description |
|-------|------|-------------|
| `language` | `string \| null` | One of the valid languages above, or `null` for auto-detect |
| `path` | `string` | Relative path from project root (empty string `""` for root) |

### Default Template (auto-generated)

```json
[
  {
    "language": null,
    "path": ""
  }
]
```

When left as-is (single entry with `language: null` and `path: ""`), the server auto-detects scan targets.

### Examples

**Single-language project (TypeScript at root):**

```json
[
  {
    "language": "typescript",
    "path": ""
  }
]
```

**Monorepo with multiple languages:**

```json
[
  {
    "language": "typescript",
    "path": "frontend"
  },
  {
    "language": "python",
    "path": "backend"
  },
  {
    "language": "csharp",
    "path": "services/auth"
  }
]
```

**C++ project in a subdirectory:**

```json
[
  {
    "language": "cpp",
    "path": "engine/src"
  }
]
```

**Mixed JavaScript and Python at root:**

```json
[
  {
    "language": "javascript",
    "path": ""
  },
  {
    "language": "python",
    "path": ""
  }
]
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `project_overview` | Get the highest-level context for the project: architecture, tech stack, entry points, and top-level modules |
| `file_summary` | Get a summary of a file with optional parent directory context |
| `module_summary` | Get full documentation for the module that owns a given file, including DRG cluster metadata and parent/child module relationships |
| `dependencies` | Get all dependencies for a file with relationship summaries |
| `blast_radius` | Analyze what files would be affected if a file is modified or deleted |

Each tool accepts an optional `project_id` parameter. If not provided, it falls back to the `SHIFT_PROJECT_ID` environment variable.

## Configuration Files

| File | Location | Description |
|------|----------|-------------|
| Global config | `~/.shift/config.json` | API key and server URLs |
| Project config | `.shift/config.json` | Project ID, name, and agent info |
| Scan targets | `.shift/scan_target.json` | Language and path targets for scanning (auto-created) |