Trellis

Trellis is an open-source context graph engine for large codebases. It is a local-first architectural replica of Graft: parse once with tree-sitter, write a folder of linked markdown nodes plus a per-symbol wiring graph, and serve that map to coding agents over MCP.

Agents stop rediscovering your repo from scratch every task. Humans onboard once; Trellis lets agents do the same.

npm install -g trellis-graph
trellis init --yes
# or
npx trellis-graph init --yes

No daemon. No embeddings. No database. The graph is files under .trellis/ (gitignored, like node_modules).

What you get

Source files ──► Pass 1 / Tier 1 (tree-sitter, $0, no key)
                      │
                      ▼
              .trellis/.graph/wiring.json
                      │
Source files ──► Pass 2 / Tier 2 (summaries + grouping)
                      │     heuristic by default
                      │     --deep uses your LLM
                      ▼
              .trellis/*.md   (15–30 subsystem nodes)
                      │
                      ▼
              trellis mcp     (stdio MCP for Cursor / Claude Code)

• Tier 1 is deterministic. trellis build walks the git working tree, parses symbols / imports / call edges, and writes wiring.json. Cached by SHA-256; unchanged files are replayed.
• Tier 2 writes plain-English component roles and compiles them into a curated set of subsystem markdown files — not one node per file. --deep calls OpenAI, Anthropic, OpenRouter, LiteLLM, Ollama, or any OpenAI-compatible endpoint under your key.
• Freshness is a hash diff against the working tree (size+mtime first, SHA-256 when metadata moved). trellis check is the drift report and never auto-rebuilds. Query commands refresh structurally when something moved.

CLI

trellis init [dir]                 # scaffold .trellis/, .gitignore, AGENTS.md, MCP configs
trellis build [dir]                # Pass 1 + Pass 2 (no LLM)
trellis build --deep               # LLM summaries + regrouping
trellis check [dir]                # exit 1 if the graph is stale
trellis mcp [dir]                  # stdio MCP server
trellis grep <query>               # exhaustive search, grouped by enclosing symbol
trellis map                        # directory clusters, hubs, hotspots
trellis ask "<question>"           # ranked symbol hits
trellis callers <symbol>           # inbound references; --direction out for callees
trellis skeleton <file>            # signatures only
trellis viz                        # local graph viewer (http://127.0.0.1:43177)
trellis uninstall -y               # remove wiring files

init on a TTY prompts for agents. In CI, pass --yes or --agents cursor claude. --dry-run prints every path it would touch.

MCP

trellis init registers the server with Cursor (.cursor/mcp.json) and Claude Code (.mcp.json):

{
  "mcpServers": {
    "trellis": {
      "command": "npx",
      "args": ["-y", "trellis-graph", "mcp"]
    }
  }
}

| Tool / resource | Purpose | |---|---| | trellis_read_graph | Index of .trellis/*.md nodes | | trellis_get_node | Fetch one node (e.g. auth-system) | | trellis_find_code | Symbols, callers, AST relationships in wiring.json | | trellis_check | Working-tree freshness / hash diff | | trellis_file_api | Signatures in a file | | trellis_trace_calls | Blast radius (direction, depth) | | trellis_find_all | Regex search grouped by symbol | | trellis://graph/map | Live architectural overview |

LLM providers (build --deep)

Set any of:

| Variable | Use | |---|---| | OPENAI_API_KEY | OpenAI | | ANTHROPIC_API_KEY | Anthropic | | OPENROUTER_API_KEY | OpenRouter | | TRELLIS_API_KEY + TRELLIS_BASE_URL | LiteLLM, Ollama, custom gateways | | TRELLIS_MODEL | Model id | | TRELLIS_PROVIDER | openai | anthropic | openai-compatible |

Ollama example:

export TRELLIS_BASE_URL=http://127.0.0.1:11434/v1
export TRELLIS_API_KEY=ollama
export TRELLIS_MODEL=llama3.1
trellis build --deep

Without credentials, Pass 2 still emits subsystem nodes from directory clusters, exports, and call edges.

Node format

Each .trellis/<id>.md file is readable markdown with YAML front matter: id, title, files, per-file SHA-256 hashes, and typed links (depends_on, part_of, uses, implements, extends, produces, configures, validates). A Notes section is preserved across rebuilds.

Marketing site

The landing page in site/ matches Graft’s public site: #0e1012 canvas, Geist type, display wordmark, pill nav, Copy setup control, terminal demo, bench bars, and a scroll-driven graph.

npm run site
# http://127.0.0.1:43123

Develop

Requires Node.js 20+.

npm install
npm run build
npm test
node dist/cli.js build .
node dist/cli.js map

Publish:

npm publish

The trellis, trellis-graph, and trellis-cli bins all point at dist/cli.js (shebang #!/usr/bin/env node). Package output is ESM + CJS from tsup. Published on npm as trellis-graph (trellis-cli was already taken).

License

MIT