Getting Started

Initialize a project

What larkx init does, step by step.

The init wizard

larkx init runs an interactive wizard that sets up everything in one go:

Creates .larkx/ with empty index, graph, and config files
Adds .larkx to .gitignore
Asks how you want to generate AI summaries (Skip, Local Claude, or Anthropic API key)
Asks if you want an MCP server (creates .mcp.json)
Asks which AI agents you use (creates per-agent instruction files)
If Claude Code is selected, adds a UserPromptSubmit hook to .claude/settings.json

Step 3 — AI summaries

AI summaries generate a one-sentence description for each file, shown in get_project_index level 4. Because they call an LLM per file, Skip is the recommended default — you can always enable them later.

AI summary prompt

? AI summaries — how do you want to generate them?
  ❯ Skip  (recommended — summaries cost extra tokens)
    Local Claude  (uses your Claude subscription — no key needed)
    Anthropic API key

Choosing Local Claude requires the claude CLI to be installed and in your PATH. It uses your existing Claude Pro/Team subscription — no extra API key needed.

If you pick Anthropic API key and ANTHROPIC_API_KEY is already set in your environment, larkx uses it automatically. Otherwise the wizard prompts you to enter one. The key is saved to .larkx/config.json, which is gitignored.

The choice is saved to .larkx/config.json under an ai key. You can change it at any time by editing that file or re-running larkx init.

Step 4 — MCP server

MCP prompt

? Set up MCP server for Claude Code / VS Code? (creates .mcp.json) [Y/n]

Answering Y creates .mcp.json pointing at the local larkx mcp binary. Reload VS Code afterwards to activate it.

Step 5 — Agent instruction files

agent picker

? Which AI agents do you use? (Space to select, Enter to confirm)
  ◯ Claude Code     →  CLAUDE.md
  ◯ GitHub Copilot  →  .github/copilot-instructions.md
  ◯ Cursor          →  .cursorrules
  ◯ OpenAI Codex    →  AGENTS.md
  ◯ Gemini CLI      →  GEMINI.md

Press Space to toggle, Enter to confirm. You can pick multiple.

Files created

File	Purpose	When
`.larkx/`	Index data — gitignored	init
`.larkx/config.json`	Exclude rules, entry points, AI provider config	init
`.larkx/context.md`	Pre-generated compact codebase map — read by any AI agent that can read files	every index run
`.mcp.json`	MCP server config for Claude Code / VS Code and other MCP clients	init (if MCP selected)
`CLAUDE.md`	Instructions for Claude Code	init
`.cursorrules`	Instructions for Cursor	init
`.github/copilot-instructions.md`	Instructions for GitHub Copilot	init
`AGENTS.md`	Instructions for OpenAI Codex	init
`GEMINI.md`	Instructions for Gemini CLI	init
`.claude/settings.json`	UserPromptSubmit hook (Claude only)	init

You can re-run larkx setup-agents at any time to add or update agent instruction files without re-initializing.

Already initialized?

output if re-run

⚠ Already initialized. Run: larkx index

Init is a one-time operation. To re-create just the agent files, use larkx setup-agents. To change your AI provider, edit .larkx/config.json directly.

Next: Index your code