Introduction

Your work is scattered across apps that don't talk to each other and forget everything when they close. Trellis replaces the app silo with a single local-first graph: every note, file, task, and agent decision is an entity in one substrate you own, and every "app" is just a projection over it a board, a table, a timeline, a canvas rendering the same data. History is append-only, so nothing is ever lost. Identity is a keypair, so nothing is ever hostage. AI agents work in the same graph under the same rules, with every decision traced.

30-second version

Trellis is one graph for everything. Views are projections over it; change the projection and the view changes, the data stays. Every change is an immutable op in a causal stream. Agents are peers same identity system, same rules, every decision recorded as data. Boots with npx trellis studio.

For the long version of this argument, read A Polite Lie Told to Gravity on the brew.build blog.

The three gaps

Trellis exists to close three gaps in how computers treat your work.

Apps are silos

A note in one tool, a task in another, a file in a third the same information, three silos, zero interop. Each one speaks its own dialect and forgets everything the moment you close it. In Trellis, all data decomposes to entities and attributes in one graph. A kanban board, a spreadsheet, a timeline, a network diagram these are projections over the same entities. Change the projection and the view changes. The data stays.

Reasoning was never data

Every change has a reason, and almost all of them die in PR comments, chat threads, and somebody's memory. AI agents make this worse: they generate code, make decisions, and take actions all day, and almost none of that reasoning survives the session. In Trellis, reasoning is data. Decisions are graph entities linked to their rationale, the alternatives considered, and the files they touched recorded in the execution path as changes happen, not reconstructed afterward.

You're a tenant of your own data

Your identity is a row in someone else's database. Your history belongs to someone else's audit log. In Trellis, your identity is an Ed25519 keypair you generated, and your data is .trellis files on your device. Move everything to another machine with cp -r. Nothing is locked in. Nothing is held hostage.

What exists today

• trellis npm package.: The graph engine and all platform APIs through modular subpaths trellis/vcs, trellis/schema, trellis/realtime, trellis/cms.
• trellis CLI.: Repository management and automation from the command line.
• Trellis Studio.: The first projection: a workspace with graph, editor, history, agents, decisions, and issues over the same substrate. Boots with npx trellis studio.
• VS Code extension.: Timeline, issues, and knowledge navigation inside your editor.
• MCP harness.: Model Context Protocol integration for AI agent workflows is in progress; standalone trellis mcp is not a shipped command yet.

The five pillars

1. Causal Stream.: A fine-grained, immutable ledger of every semantic change.
2. Semantic Patching.: Understanding code as a tree (AST) rather than lines of text.
3. Narrative Milestones.: Human-curated stories that sit on top of the stream.
4. Governance Subgraph.: Identity and permissions built into the data structure.
5. Idea Garden.: A permanent, searchable archive of all exploration.

The Five Pillars covers each in depth. If you're coming from Git, Coming from Git maps every Git concept to its Trellis equivalent.

Where to go next

• Installation add Trellis to a project or install it globally.
• Quick Start first repository, first ops, first milestone in five minutes.
• Core Concepts the vocabulary: entities, ops, projections, capabilities.

Why "Trellis"? A trellis is the structure gardeners build for plants that grow fast but can't hold their own weight. Work is like that it sprawls unless something holds it up. The name stuck.