Introduction
[object Object]
Plants compete fiercely for sunlight. Many build sturdy, woody trunks to reach the sky. Some species are structurally flimsy. They grow as vines that can't hold their own weight. Left alone, they sprawl across the dirt where their fruits rot or get devoured by tiny ground-dwelling pests.
Humans built the trellis, a vertical grid of wood or metal, to help the thing sustain itself so it can sustain us.
This documentation is about the kind of work that grows like a vine (code, decisions, and the reasoning of AI agents) and the structure that lets it bear fruit instead of rotting on the ground.
30-second version
Trellis is a local-first graph for things that grow but can't hold their own weight. Trellis Studio is the workspace where you tend them. Code, agents, and the reasoning behind every change live in one substrate. Boots with
npx trellis studio.
For the long version of this argument, read A Polite Lie Told to Gravity on the brew.build blog.
Why Trellis?
Traditional engines and version control treat your state as snapshots or disjointed logs. Trellis treats it as an Agentic State Engine, where everything is a living graph entity with relationships, an immutable history, and full auditability.
| Use Case | How |
|---|---|
| AI agent runtime | Tool registry + decision traces + branching |
| Collaborative app backend | CRDT sync + multi-tenancy + realtime subscriptions |
| Version control for code | Semantic patching + milestones + Idea Garden |
| Auditable data platform | Immutable op log + time travel + governance |
| TrellisDB content apps | Schema-aware collections + references + computed formula fields |
The Five Pillars
Trellis is built on five architectural pillars:
- Causal Stream. A fine-grained, immutable ledger of every semantic change.
- Semantic Patching. Understanding code as a tree (AST) rather than lines of text.
- Narrative Milestones. Human-curated stories that sit on top of the stream.
- Governance Subgraph. Identity and permissions built into the data structure.
- Idea Garden. A permanent, searchable archive of all exploration.
How It Differs from Git
| Git Concept | Trellis Equivalent |
|---|---|
git add + commit | Automatic. Every file change creates ops in real time. |
git log | trellis log. Causal op stream with content-addressed hashes. |
| Tag / release | trellis milestone create. Narrative checkpoint. |
| Branch | trellis branch. Same concept, with CRDT support. |
git diff | trellis sdiff. AST-level semantic diff. |
git merge | trellis merge. Three-way with semantic conflict resolution. |
| Stash / abandoned | trellis garden. Discovers and revives abandoned work. |
| Issues (external) | trellis issue. First-class task tracking. |
Key Differences
- No staging area. Ops are created automatically when files change.
- Ops are immutable. They are never rewritten, rebased, or deleted.
- Three-tier ops. File-level (Tier 0), structural (Tier 1), semantic/AST (Tier 2).
- Milestones ≠ commits. A milestone spans a range of ops and carries a narrative message.
- Idea Garden. Automatically detects abandoned work and lets you revive it.
Project Surfaces
Trellis exposes multiple integrated surfaces:
trellisnpm package. All platform APIs through modular subpaths.trellisCLI. Command-line interface for repository management and automation.trellis/cmsSDK. Collection-oriented TrellisDB client for websites and apps.- VS Code extension. Visual interface for timeline, issues, and knowledge navigation.
- MCP harness. Model Context Protocol integration for AI agent workflows is in progress; standalone
trellis mcpis not a shipped command yet.