How it works

02 · INSTALL

Install

One curl one-liner installs the full bundle.

The fast path — pre-built binaries for the current host:

curl -fsSL https://loctree.com/install.sh | sh

What lands on your PATH:

• loct — core CLI: scan, slice, find, dead, cycles, report.
• loctree-mcp — MCP server (stdio) for Claude Code, Cursor, and compatible agents.
• loctree-lsp — LSP server for VS Code, Helix, Neovim, and other LSP-aware editors.

03 · FIRST SCAN

First scan

One scan per repository. Subsequent commands query the snapshot — instant, offline, deterministic.

Run loctree at the root of your repository:

cd your-project
loct scan

The snapshot lands at .loctree/snapshot.json — full dependency graph, exports, importers, language detection. A small repo finishes in 1–3 seconds; a 100k-LOC monorepo in roughly 30. Re-runs are incremental and use mtime caching.

From here every command is instant:

loct repo-view

loct slice src/app.tsx

loct find UserSession

Snapshots persist across sessions. Loctree compares git HEAD on every command and re-scans only when the tree has actually moved.

04 · PROJECT CONFIG

Project configuration

Two files. One for what to ignore. One for stack-specific overrides.

.loctignore

Gitignore-style patterns plus loctree-specific directives (e.g. dead-ok suppression for generated code).

# Standard ignore patterns (gitignore syntax)
node_modules
target
dist
*.min.js

# Suppress dead-export findings for generated code
@loctignore:dead-ok src/generated/**

.loctree/config.toml

Optional. Lets you toggle library mode and configure stack-specific analyzers (Tauri command macros, DOM exclusions, etc.).

library_mode = false
library_example_globs = ["examples/**"]

[tauri]
command_macros = ["api_cmd_tauri"]
dom_exclusions = ["customDomMethod"]
non_invoke_exclusions = ["helperFunction"]

05 · CONNECT AN AGENT

Connect an agent

loctree-mcp speaks stdio. Drop the same configuration into any MCP-compatible client.

Claude Code

Add via the CLI:

claude mcp add loctree loctree-mcp stdio

Or write the config manually to ~/.claude/mcp.json (global) or .mcp.json in the workspace root:

{
  "mcpServers": {
    "loctree": {
      "command": "loctree-mcp",
      "args": ["stdio"]
    }
  }
}

Cursor, Continue, Cline

Same JSON, different file. Look for the mcpServers object in your editor's settings (Cursor: Settings → MCP; Continue: ~/.continue/config.json; Cline: VS Code settings).

What the agent gets

Six tools — repo-view, slice, find, impact, focus, tree. The first call auto-runs loct scan in the project directory; subsequent calls are instant. Snapshots are cached per project across MCP sessions and re-validated against git HEAD on every call.

06 · EDITOR (LSP)

Editor integration

loctree-lsp speaks LSP over stdio. Works wherever you can register a custom server.

VS Code

Use the bundled extension at editors/vscode/. It registers loctree-lsp and adds the inline scan/slice commands.

Helix

Add to ~/.config/helix/languages.toml:

[[language]]
name = "typescript"
language-server = { command = "loctree-lsp" }

Neovim (lspconfig)

local lspconfig = require('lspconfig')
local configs = require('lspconfig.configs')

if not configs.loctree_lsp then
  configs.loctree_lsp = {
    default_config = {
      cmd = { "loctree-lsp" },
      filetypes = { "typescript", "javascript", "rust", "python" },
      root_dir = lspconfig.util.root_pattern(".loctree", ".git"),
    },
  }
end

lspconfig.loctree_lsp.setup({})

07 · CI / SARIF

CI integration

Fail the build on regressions. Upload SARIF for GitHub Code Scanning.

A minimal GitHub Actions step:

- run: |
    curl -fsSL https://loctree.com/install.sh | sh
    echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- run: loct scan
- run: loct dead --fail
- run: loct cycles --fail
- run: loct lint --sarif > loctree.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: loctree.sarif

Useful flags:

• --fail — exit non-zero when findings are detected.
• --fail-stale — exit non-zero if the snapshot does not match the current git HEAD.
• --no-scan — require a pre-built snapshot. Use it to keep CI deterministic.
• --sarif — emit SARIF 2.1.0 for GitHub Code Scanning.

08 · SUPPRESSIONS

Suppressions

Mark reviewed false positives once. Tracked in .loctree/suppressions.toml, scoped per finding kind.

Add and list suppressions through the CLI:

loct suppress add dead \
  --target src/extension.ts \
  --reason "VS Code activate/deactivate entrypoint"

loct suppress list

Common false-positive patterns: VS Code extension activate / deactivate exports, Rust attribute-driven entry points (#[tauri::command]), and frameworks that resolve handlers reflectively. Suppressions are reviewed and committed alongside source code.

09 · UPDATE & UNINSTALL

Update and uninstall

Same install paths in reverse. Snapshots are forward-compatible across patch versions.

Update — re-run the curl one-liner:

curl -fsSL https://loctree.com/install.sh | sh

Uninstall:

rm -f ~/.local/bin/loct ~/.local/bin/loctree ~/.local/bin/loctree-mcp ~/.local/bin/loctree-lsp ~/.local/bin/aicx ~/.local/bin/aicx-mcp

Project artifacts live under .loctree/ in your repository. Delete the directory if you want to purge snapshots, suppressions, and config.

10 · WHERE NEXT

Where next

You're set up. The reference, the proof, and the source live one click away.