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.

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.