Content
# lattice
Local-first JavaScript and TypeScript code intelligence for CLI workflows and MCP agents.
`lattice` indexes a JS/TS workspace into a local graph and vector store, then exposes the result through a CLI and an MCP stdio server. It is built for agents and developers that need grounded answers about symbols, references, call paths, imports, tests, diagnostics, and bounded source context without sending a codebase to a hosted indexing service.
## What It Provides
- JS/TS workspace indexing with Tree-sitter syntax facts and SCIP compiler facts.
- A persistent local LadybugDB graph/vector index under `.lattice/`.
- Hybrid semantic search using local Jina embeddings by default, with a deterministic hash provider for tests and offline checks.
- Symbol lookup, references, callers, callees, relationship browsing, path tracing, and bounded context reads.
- Diagnostics for missing files, missing symbols, discovery skips, parse recovery, graph writes, and queryability.
- MCP tools backed by the same query engine and schema contracts as the CLI.
- Eval packs and benchmarks for regression testing graph, ranking, MCP, CLI parity, and app-flow behavior.
No hosted embedding API or hosted code index is used during normal indexing.
## Status
This is an early standalone tool. The CLI and MCP surfaces are usable, and the repository supports versioned local installs. Install from the repository or a local tarball until an npm package is published.
## Install From Source
```bash
git clone https://github.com/jlm0/lattice.git
cd lattice
npm install
npm run build
npm link
```
Confirm the binary is available:
```bash
lattice health --json
```
## Versioned Local Install
Build, pack, and install the current package version globally:
```bash
npm run release:local
lattice --version
```
The release script runs the test suite, creates a versioned tarball under `.local-releases/v<version>/`, installs that exact tarball with `npm install -g`, and verifies the installed CLI reports the same package version.
When a new local version is ready, bump the package version first:
```bash
npm run version:bump -- patch
npm run version:bump -- minor
npm run version:bump -- 0.2.0
```
## Quick Start
Index a workspace:
```bash
lattice index \
--workspace /path/to/workspace \
--index-path /path/to/workspace/.lattice/index \
--json
```
Run common queries:
```bash
lattice semantic "wallet signer" --workspace /path/to/workspace --index-path /path/to/workspace/.lattice/index --json
lattice find-symbol SomeSymbol --workspace /path/to/workspace --index-path /path/to/workspace/.lattice/index --json
lattice relationships SomeSymbol --workspace /path/to/workspace --index-path /path/to/workspace/.lattice/index --direction either --json
lattice trace-path SourceSymbol TargetSymbol --workspace /path/to/workspace --index-path /path/to/workspace/.lattice/index --json
lattice get-context node-id-or-file --workspace /path/to/workspace --index-path /path/to/workspace/.lattice/index --json
```
Incrementally refresh after edits:
```bash
lattice update --workspace /path/to/workspace --index-path /path/to/workspace/.lattice/index --json
```
Check current or latest index progress:
```bash
lattice progress --workspace /path/to/workspace --index-path /path/to/workspace/.lattice/index --json
lattice progress --workspace /path/to/workspace --index-path /path/to/workspace/.lattice/index --events --limit 50 --json
```
`progress --events` includes recent JSONL run events with substeps, discovery summaries, SCIP quality details, memory usage, durations, and failure details. `progress` and `status` include write-lock state.
If `--repo` is omitted, `index` uses `--workspace-manifest` when provided and otherwise indexes the workspace root. Generated folders, dependency folders, build output, logs, and local runtime folders are ignored by default.
## MCP Usage
Start the MCP server:
```bash
lattice mcp --workspace /path/to/workspace --index-path /path/to/workspace/.lattice/index
```
Example MCP client configuration:
```json
{
"mcpServers": {
"lattice": {
"command": "lattice",
"args": [
"mcp",
"--workspace",
"/path/to/workspace",
"--index-path",
"/path/to/workspace/.lattice/index"
]
}
}
}
```
The MCP server uses stdio. Logs go to stderr or files so stdout remains valid MCP JSON-RPC traffic. Tool outputs include structured content, schema metadata, evidence fields, ranking reasons, and bounded result limits.
## Command Surface
Core commands:
```text
lattice index
lattice update
lattice progress
lattice status
lattice health
lattice search
lattice semantic
lattice find-symbol
lattice references
lattice callers
lattice callees
lattice relationships
lattice trace-path
lattice expand-context
lattice get-context
lattice diagnose file
lattice diagnose symbol
lattice eval
lattice benchmark
lattice mcp
```
Use `--json` for deterministic machine-readable output. Human-readable output is intended for TTY use, while non-TTY and JSON modes stay stable for agent and script consumption.
Run `lattice --help` or `lattice <command> --help` for command details.
## Embeddings
The default embedding provider is local Jina through Transformers.js:
```text
jinaai/jina-embeddings-v2-base-code
```
The model is downloaded into the configured index model cache on first use unless it is already cached. Use the deterministic hash provider for fast regression checks, offline diagnostics, or comparison runs:
```bash
lattice index --workspace /path/to/workspace --embedding-provider hash --json
```
## Evals And Benchmarks
Run the fast synthetic regression suite:
```bash
npm run build
lattice eval --suite js-ts-general --embedding-provider hash --json
```
Run the adversarial pack:
```bash
lattice eval --eval-pack eval-packs/js-ts-adversarial --embedding-provider hash --json
```
Run a benchmark:
```bash
lattice benchmark --suite js-ts-general --embedding-provider hash --skip-mcp-latency --json
```
Evals include blocking `required` gates plus non-blocking `target` and `scoreboard` gates for quality tracking.
## Development
```bash
npm run build
npm test
git diff --check
npm pack --dry-run
```
Workstream definitions and validation history live under `.agent-workstream/` when a workstream is created. Use the global workstream creation skills to define workstreams and `$workstream-execution` to implement existing workstreams. Agent workflow guidance lives in `docs/agent-workflows/`.
