Getting Started

Install larkx

Five steps. Under five minutes. Works on Windows, macOS, and Linux.

PrerequisitesNode.js 18 or higher. Check with node --version. No other dependencies required.
  1. 1

    Install globally with npm

    Run this once per machine:

    bash
    npm install -g larkx

    Verify the install worked:

    bash
    larkx --version
# → larkx v0.1.0
  2. 2

    Initialize your project

    Open a terminal in your project root and run:

    bash
    cd /path/to/your-project
larkx init

    You will be asked three questions:

    • Set up MCP server? (Y/n), creates .mcp.json for VS Code / Claude Code
    • Which AI agents do you use?, pick any combination of Claude Code, Cursor, Copilot, Codex, Gemini
    • Per-agent instruction files (CLAUDE.md, .cursorrules, etc.) are created automatically

    If you picked Claude Code, a .claude/settings.json hook is added so Claude uses MCP tools first on every prompt.

  3. 3

    Build the index

    bash
    larkx index

    You'll see something like:

    output
    ✓ Found 342 files
✓ Parsed 342 files · 1,847 functions · 89 classes
✓ Built graph: 342 nodes · 4,612 edges
✓ Saved to .larkx/

    Subsequent indexes are incremental, only changed files are reparsed. A 1000-file project typically reindexes in under 2 seconds.

  4. 4

    Restart your AI client

    VS Code / Claude Code extension:

    bash
    # Ctrl+Shift+P → Developer: Reload Window

    Claude Code will detect the .mcp.json file and ask you to approve the larkx MCP server. Click Allow.

  5. 5

    Verify it's working

    bash
    larkx stats

    Output includes file counts, detected frameworks, and token estimates per level:

    stats output
    Project Stats
  Files:        342
  Functions:    1,847
  Classes:      89

AI Token Estimates (per get_project_index call)
  Level 1 (paths     ): ~1.2K tokens
  Level 2 (symbols   ): ~8.5K tokens
  Level 3 (signatures): ~16K tokens
  Level 4 (summaries ): ~24K tokens

    Then, in Claude Code, ask: "Show me the project index." The AI should call get_project_index directly without opening any source files.

    You can also verify the CLI path with larkx mcp --check, inspect a smaller slice with larkx context --folder src/auth --level 2, or open the graph with larkx serve.

Common next steps

Trouble shootingIf larkx is not found after install, your global npm bin folder may not be in PATH. On Windows: npm config get prefix and add that path to your environment variables.