Trellis

A comprehensive graph-native platform for code, knowledge, and collaboration.

Table of Contents

• Quick Start
• Platform Overview
• Core Capabilities
• Project Surfaces
• Package Architecture
• CLI Overview
• VS Code Extension
• Module & Subpath Guide
• Development & Releases
• Roadmap

Quick Start

Install

Global install:

npm install -g trellis
trellis -h

Or use npx:

npx trellis -h

Initialize a repository

# With the CLI
npx trellis init
npx trellis watch

# Or programmatically
import { TrellisVcsEngine } from 'trellis';
const engine = new TrellisVcsEngine({ rootPath: '/my/project' });
await engine.initRepo();

Import from Git

npx trellis import --from /path/to/git-repo

Platform Overview

Trellis is a comprehensive platform that unifies version control, knowledge management, semantic analysis, and intelligent automation. Built on a graph-native foundation, it treats every action—code changes, decisions, links, and embeddings—as first-class entities in a causal graph.

The platform consists of multiple integrated surfaces:

• trellis npm package — the published package exposing all platform APIs through modular subpaths
• trellis CLI — command-line interface for repository management, semantic tooling, knowledge operations, and automation
• VS Code extension — visual interface for timeline exploration, issue management, knowledge navigation, and collaborative features
• Core platform modules — reusable building blocks for graph storage, semantic analysis, sync, knowledge graphs, embeddings, and decision traces

Core Capabilities

1. Graph-Native Foundation

• EAV Store — Entity-Attribute-Value graph database with SQLite backend
• TrellisKernel — Generic graph CRUD operations independent of VCS
• Query Engine — EQL-S query language and Datalog evaluator
• Ontology System — Schema validation and built-in ontologies

2. Advanced Version Control

• Causal Stream — Immutable, content-addressed operations with causal chaining
• Semantic Patching — AST-aware changes enabling conflict-free merges
• Narrative Milestones — Human-readable checkpoints over continuous work streams
• Governance — Op signing, identity management, and policy enforcement

3. Knowledge & Intelligence

• Wiki-Links — Bidirectional reference system for cross-linking entities
• Embeddings — Semantic indexing and vector search for intelligent discovery
• Decision Traces — Automated capture and querying of agent decisions
• Idea Garden — Detection and revival of abandoned work clusters

4. Collaboration & Sync

• Peer Sync — CRDT-based reconciliation with HTTP/WebSocket transports
• Multi-Repo Federation — Cross-repository entity references and linking
• Agent System — Tool registry and decision trace capture
• Plugin Architecture — Extensible system with event bus and workspace config

Project Surfaces

Package Architecture

trellis/
├── src/
│   ├── core/              # EAV store, kernel, ontology, query, agents, plugins
│   │   ├── kernel/        # TrellisKernel with entity CRUD and middleware
│   │   ├── ontology/      # Schema registry, validation, built-in ontologies
│   │   ├── query/         # EQL-S query engine and Datalog evaluator
│   │   ├── agents/        # Agent harness, tool registry, decision traces
│   │   └── plugins/       # Plugin registry, event bus, workspace config
│   ├── vcs/               # Version control: ops, branches, milestones, diff, merge
│   ├── links/             # Wiki-link parsing, resolution, backlink index
│   ├── embeddings/        # Semantic indexing, vector search, auto-embed, RAG
│   ├── decisions/         # Decision trace capture and querying
│   ├── semantic/          # AST parsers, semantic diff, semantic merge
│   ├── sync/              # Peer sync, CRDT reconciler, HTTP/WebSocket transports, multi-repo
│   ├── garden/            # Idea Garden: abandoned work detection and revival
│   ├── git/               # Git import/export bridge
│   ├── identity/          # Ed25519 identity management and governance
│   ├── watcher/           # File watching + ingestion pipeline
│   ├── mcp/               # Model Context Protocol server integration
│   ├── cli/               # CLI entrypoint
│   ├── engine.ts          # Composition root
│   └── index.ts           # Main package entrypoint
├── vscode-extension/      # VS Code extension surface
├── test/                  # Comprehensive test suites
├── DESIGN.md              # Detailed architecture specification
└── justfile               # Local build and development recipes

The Op Stream

Every action in Trellis is an immutable VcsOp:

interface VcsOp {
  hash: string; // trellis:op:<sha256> — content-addressed
  kind: VcsOpKind; // e.g. 'vcs:fileModify'
  timestamp: string; // ISO 8601
  agentId: string; // Author identity (DID)
  previousHash?: string; // Causal chain link
  vcs: VcsPayload; // Op-specific data (filePath, contentHash, …)
  signature?: string; // Ed25519 signature (P4+)
}

Ops are written to .trellis/ops.json and replayed into an in-memory EAV graph on startup. They are never rewritten or deleted.

Op Tiers

CLI Overview

The CLI is the operational surface for Trellis repositories. It is the fastest way to initialize repos, inspect history, create milestones, diff/merge work, and script automation around the op stream.

Repository Setup

trellis init [--path <dir>]            # Initialize a new repo
trellis import --from <git-repo>       # Import Git history as milestones
trellis export --to <dir>              # Export milestones to Git commits

Working

trellis status                          # Current branch, op count, pending changes
trellis log [--limit N] [--branch b]    # Op stream history
trellis files [--deleted]               # All tracked files
trellis watch                           # Start continuous file watching

Branches

trellis branch                          # List branches
trellis branch <name>                   # Create a branch
trellis branch -d <name>                # Delete a branch

Milestones & Checkpoints

trellis milestone create -m "message"                          # Create milestone
trellis milestone create -m "msg" --from <hash> --to <hash>   # Over a specific range
trellis milestone list                                          # List milestones
trellis checkpoint create                                       # Manual checkpoint
trellis checkpoint list                                         # List checkpoints

Diff & Merge

trellis diff [--from <hash>] [--to <hash>]  # File-level diff
trellis merge --branch <name> [--dry-run]   # Three-way merge
trellis parse <file>                        # Semantic parse (declarations, imports)
trellis sdiff <fileA> <fileB>               # Semantic diff between two versions

Identity & Governance

trellis identity [show|create|list]         # Manage identities
trellis governance [list|add|remove]        # Manage policy rules

Idea Garden

trellis garden                                        # List abandoned clusters
trellis garden list [--status <s>] [--file <f>]      # Filter clusters
trellis garden show <cluster-id>                      # Inspect a cluster
trellis garden search --keyword <term>                # Search by keyword
trellis garden revive <cluster-id>                    # Revive cluster as branch
trellis garden stats                                  # Garden statistics

Sync

trellis sync status                       # Local sync state
trellis sync reconcile --remote <path>    # Reconcile with another local repo
trellis sync push --peer <id>             # Push ops to a peer (HTTP/WebSocket)
trellis sync pull --peer <id>             # Pull ops from a peer
trellis link-repo <alias> <location>      # Link a remote repo for cross-repo refs

Query & Search

trellis query "find Project where status = 'active'"     # EQL-S structured query
trellis query-repl                                        # Interactive query REPL
trellis ask "authentication code"                         # Natural language semantic search
trellis ask "show me auth code" --rag                    # Output as RAG context for LLMs

Ontology

trellis ontology list                     # List registered ontologies
trellis ontology show <id>                # Show ontology details
trellis ontology validate                 # Validate store against ontologies

Agents

trellis agent list                        # List registered agents
trellis agent create <name>               # Create a new agent definition
trellis agent run <id> --input "task"     # Execute an agent run
trellis agent inspect <run-id>            # View run details and decision traces

Plugins

trellis plugin list                       # List loaded plugins
trellis plugin add <id>                   # Register and load a plugin
trellis plugin remove <id>                # Unload and unregister a plugin

VS Code Extension

The VS Code extension provides a rich visual interface for the entire Trellis platform, making knowledge navigation, collaboration, and project management intuitive and efficient.

Core Features

• Status Dashboard — Real-time view of repository health, activity metrics, and system state
• Causal Timeline — Interactive exploration of the complete operation history with filtering and search
• Knowledge Navigator — Browse and traverse the wiki-link graph with visual connections
• Issue Management — Full lifecycle issue management with drag-and-drop workflow automation
• Semantic Explorer — Navigate code structure and relationships through AST-aware visualizations
• Decision Inspector — Review decision traces and understand the reasoning behind changes
• Collaboration Hub — Multi-repo federation view and cross-project relationship mapping
• Intelligence Panel — Semantic search, RAG context, and AI-powered insights

The extension lives in vscode-extension/ and publishes separately from the npm package.

Module & Subpath Guide

The trellis package is intentionally split into subpaths so consumers can depend on the specific capabilities they need, from core graph operations to advanced AI features.

Published Package Surface

npm install trellis

// Main entry — full platform engine
import { TrellisVcsEngine } from 'trellis';

// Core graph foundation (independent of VCS)
import { EAVStore, TrellisKernel } from 'trellis/core';
import type { Fact, Link, EntityRecord } from 'trellis/core';

// Version control primitives
import type { VcsOp, VcsOpKind } from 'trellis/vcs';

// Knowledge and intelligence
import { EmbeddingManager } from 'trellis/ai';
import { parseFileRefs, resolveRef, RefIndex } from 'trellis/links';
import { recordDecision, queryDecisions } from 'trellis/decisions';

trellis — Platform Engine (TrellisVcsEngine)

The main entry point that orchestrates the entire platform: kernel, file watcher, version control, knowledge graphs, semantic analysis, and collaboration features.

import { TrellisVcsEngine } from 'trellis';

const engine = new TrellisVcsEngine({ rootPath: '/my/project' });

// Repository management
await engine.initRepo();
engine.open();

// Core operations
engine.getOps(); // All operations
engine.status(); // Branch, op count, files
engine.log(); // Formatted history
engine.getFiles(); // Currently tracked files

// Version control
await engine.createBranch('feature/x');
await engine.createMilestone('Implement auth', { fromOpHash, toOpHash });

// Semantic analysis
engine.parseFile(content, 'src/auth.ts');
engine.semanticDiff(oldContent, newContent, 'src/auth.ts');

// Knowledge operations
const garden = engine.garden();
garden.listClusters();
garden.search({ keyword: 'auth' });

// Intelligence features
const embeddings = engine.embeddings();
await embeddings.search('authentication flow');

trellis/core — Graph Foundation

The core graph layer exposes EAV primitives, ontology schemas, query engine, agent harness, and plugin system. This module is independent of version control and can be used for any graph-based application.

import { EAVStore, TrellisKernel } from 'trellis/core';
import { OntologyRegistry, builtinOntologies } from 'trellis/core';
import { QueryEngine, parseQuery } from 'trellis/core';
import { AgentHarness } from 'trellis/core';
import { PluginRegistry, EventBus } from 'trellis/core';
import type { Fact, Link, KernelOp, AgentDef, PluginDef } from 'trellis/core';

// Graph operations
const kernel = new TrellisKernel({ backend, agentId: 'me' });
await kernel.createEntity('proj:1', 'Project', {
  name: 'Trellis',
  status: 'active',
});

// Ontology validation
const registry = new OntologyRegistry();
for (const o of builtinOntologies) registry.register(o);

// Graph queries
const query = parseQuery('find Project where status = "active"');
const results = new QueryEngine(store).eval(query);

// Agent orchestration
const harness = new AgentHarness(kernel);
await harness.createAgent({ name: 'Reviewer', status: 'active' });

// Plugin system
const plugins = new PluginRegistry();
plugins.register({ id: 'my:plugin', name: 'My Plugin', version: '1.0.0' });

trellis/vcs — Version Control Model

The VCS subpath exposes operation types and domain-level building blocks for version control: branches, milestones, checkpoints, issues, diffing, merging, and blob storage.

Use this subpath when you want Trellis version control capabilities without the full platform surface.

trellis/links — Knowledge Graph & Wiki-Links

Parse [[wiki-links]] from markdown, doc-comments, and source files. Resolve references to issues, files, symbols, milestones, and decisions. Build a bidirectional knowledge graph that connects all entities in your workspace.

import { parseFileRefs, resolveRef, RefIndex } from 'trellis/links';

const refs = parseFileRefs('src/engine.ts', source);
const resolved = resolveRef(ref, context);
const index = new RefIndex();
index.indexFile('README.md', refs, context);
index.getIncoming('issue:TRL-5');

// Cross-repository references
index.addCrossRepoLink('frontend', 'proj:app', 'backend', 'api:users');

trellis/ai — Semantic Intelligence

Advanced semantic capabilities: embed issues, milestones, files, code entities, and decisions into a vector store for intelligent search, discovery, and RAG (Retrieval-Augmented Generation).

import { EmbeddingManager } from 'trellis/ai';

const manager = new EmbeddingManager(engine, { dbPath: 'embeddings.db' });
await manager.reindex();
const results = await manager.search('auth flow');

// RAG context for LLMs
const context = await manager.getRAGContext('authentication implementation');

trellis/decisions — Decision Intelligence

Automatically capture tool invocations and agent decisions as auditable traces. Enrich them with rationale via hooks and query them later by tool, entity, or decision chain. Perfect for understanding how and why decisions were made.

import { recordDecision, queryDecisions } from 'trellis/decisions';

const dec = await recordDecision(ctx, {
  toolName: 'trellis_issue_create',
  input: { title: 'Add parser' },
  output: { id: 'TRL-5' },
  rationale: 'Needed for TypeScript support',
});

// Query decision patterns
const decs = queryDecisions(ctx, { tool: 'trellis_issue_*' });
const chain = queryDecisions(ctx, { entity: 'TRL-5' }); // Full decision chain

src/garden/ — Idea Garden

Detects abandoned work using three heuristics, then exposes a query API.

import { detectClusters, IdeaGarden } from './src/garden/index.js';

const clusters = detectClusters(ops, milestonedHashes);
const garden = new IdeaGarden(ops, milestones);

garden.search({ file: 'auth.ts', status: 'abandoned', limit: 10 });
garden.stats(); // { total, abandoned, draft, revived, totalOps, totalFiles }
garden.revive('cluster:abc');

Platform Subsystem Guides

The following sections provide detailed guides for Trellis' internal subsystems. These are useful if you're contributing to the platform or extending its capabilities.

Knowledge Graph & Wiki-Links (src/links/)

Builds a bidirectional knowledge graph from wiki-link references across all workspace entities.

Detection heuristics:

Semantic Intelligence (src/semantic/)

Advanced TypeScript/JavaScript analysis with structural entity extraction and semantic diffing for intelligent code understanding.

import { typescriptParser, semanticMerge } from './src/semantic/index.js';

// Parse code into structural entities
const result = typescriptParser.parse(source, 'file.ts');
result.declarations; // ASTEntity[] — functions, classes, interfaces, enums, …
result.imports; // ImportRelation[]
result.exports; // ExportRelation[]

// Compute semantic differences
const patches = typescriptParser.diff(oldResult, newResult);
// SemanticPatch[] — symbolAdd | symbolRemove | symbolModify |
//                   symbolRename | importAdd | importRemove | …

// Intelligent merging with conflict resolution
const merged = semanticMerge(ourPatches, theirPatches, 'file.ts');
merged.clean; // true if no conflicts
merged.patches; // Merged patch list
merged.conflicts; // SemanticMergeConflict[] — entity-level, with suggestions

src/sync/ — Peer Sync

Implements the have→want→ops→ack protocol with linear and CRDT branch modes.

import { SyncEngine, MemoryTransport, reconcile } from './src/sync/index.js';

// Standalone CRDT reconciler
const result = reconcile(localOps, remoteOps);
result.merged; // Interleaved by timestamp
result.forkPoint; // Last common op hash
result.conflicts; // File-level conflicts

// Full sync engine
const transport = new MemoryTransport('peer-a', 'Alice');
const engine = new SyncEngine({
  localPeerId: 'peer-a',
  transport,
  getLocalOps: () => ops,
  onOpsReceived: (newOps) => {
    /* integrate */
  },
  branchPolicy: { linear: false }, // CRDT mode
});

await engine.pushTo('peer-b');
await engine.pullFrom('peer-b');
engine.reconcileWith(remoteOps);

Collaboration & Sync (src/sync/)

Enterprise-grade synchronization with CRDT reconciliation, multiple transport protocols, and multi-repo federation for distributed teams.

import {
  SyncEngine,
  MemoryTransport,
  reconcile,
  HttpSyncTransport,
  WebSocketSyncTransport,
  MultiRepoManager,
  formatCrossRepoRef,
} from './src/sync/index.js';

// CRDT reconciler for conflict-free merging
const result = reconcile(localOps, remoteOps);
result.merged; // Interleaved by timestamp
result.forkPoint; // Last common op hash
result.conflicts; // File-level conflicts

// HTTP transport for network sync
const httpTransport = new HttpSyncTransport('peer-a');
httpTransport.addPeer('peer-b', 'http://192.168.1.10:4200');

// WebSocket transport for real-time collaboration
const wsTransport = new WebSocketSyncTransport('peer-a');
await wsTransport.connect('peer-b', 'ws://192.168.1.10:4201');

// Multi-repo federation — connect knowledge across repositories
const repoManager = new MultiRepoManager(kernel);
await repoManager.linkRepo(
  'backend',
  '/path/to/backend-api',
  'Backend service',
);
await repoManager.addCrossRepoLink(
  'proj:frontend',
  'dependsOn',
  'backend',
  'lib:api-client',
);
// Creates: proj:frontend --dependsOn--> @backend:lib:api-client

// Discover cross-repository relationships
const refs = repoManager.findReferencesTo('backend', 'lib:api-client');

These subsystem guides provide insight into Trellis' internal architecture. They're particularly useful for platform contributors, extenders, or those building custom integrations.

How It Works

Init Flow

trellis init
  → mkdirSync .trellis/
  → write config.json (agentId, defaultBranch, ignorePatterns)
  → create vcs:branchCreate op for "main"
  → scan filesystem → create vcs:fileAdd op per file
  → flush ops to .trellis/ops.json

Watch Flow

trellis watch
  → FileWatcher.scan() populates known-files map
  → FileWatcher.start() sets up Bun fs.watch
  → on change → debounce → SHA-256 hash → emit FileChangeEvent
  → Ingestion.process(event) → createVcsOp(kind, payload)
  → engine.applyOp(op) → EAV store + op log
  → auto-checkpoint if threshold crossed

Milestone Flow

trellis milestone create -m "Add auth"
  → auto-detect fromOpHash (last milestone's toOpHash + 1)
  → collect affected files from ops in range
  → createVcsOp('vcs:milestoneCreate', { message, fromOpHash, toOpHash, affectedFiles })
  → optional: trellis export → Git commit

Semantic Diff Flow

trellis sdiff old.ts new.ts
  → typescriptParser.parse(old) → ParseResult { declarations, imports, exports }
  → typescriptParser.parse(new) → ParseResult
  → typescriptParser.diff(old, new) → SemanticPatch[]
    - symbolAdd / symbolRemove / symbolModify
    - symbolRename (detected via signature similarity)
    - importAdd / importRemove / importModify

Sync / Reconcile Flow

Engine A sends 'have' { heads: { main: 'h42' }, opCount: 42 }
  → Engine B compares to its own heads
  → B sends 'want' { afterHash: 'h38' }
  → A sends 'ops' [ op39, op40, op41, op42 ]
  → B integrates new ops (linear: filter dupes; CRDT: reconcile())
  → B sends 'ack' { integrated: ['h39', …] }

Design Doc

See DESIGN.md for the complete platform architecture specification, including:

• §3 — Causal stream and branch concurrency model
• §4 — Semantic patching: parser adapter interface, patch types, commutativity
• §5 — Milestone narrative model
• §6 — Identity, signing, and governance
• §7 — Idea Garden cluster detection heuristics
• §8 — Knowledge graph and wiki-link system
• §9 — Embeddings and semantic search architecture
• §10 — Decision trace capture and querying
• §11 — Sync protocols and multi-repo federation
• §12 — Core graph kernel and ontology system
• §13 — Agent harness and plugin architecture
• §14 — Open questions and architectural trade-offs

Development & Releases

Prerequisites

• Bun ≥ 1.0
• No other native dependencies

Install

bun install

Test

just test-core
# or run the full suite when working on those areas:
bun test

The release flow currently validates against the targeted passing core suite.

Typecheck

bun run typecheck

Build

# Build for npm (bun build → dist/)
bun run build

# Run CLI directly during development
bun run src/cli/index.ts <command>

Release Workflow

# Validate locally without publishing
just publish-dry-run

# Publish to npm locally, then tag/push/create release metadata
just publish

Requires Bun ≥ 1.0 — Trellis uses bun:sqlite for the vector store and Bun's native TypeScript support for optimal performance.

Roadmap