Trellis
The Agentic Framework — a local-first, event-sourced graph engine for code, agents, and decisions.
Docs ·
Studio ·
GitHub
---
Most agent frameworks pour everything into the reasoning engine and treat state
as an afterthought. Trellis inverts that. It is the **system of record for
decisions**: a persistent, queryable, auditable memory where every thought, tool
call, and file change is an immutable operation in a causal graph. It runs fully
offline — servers may relay, accelerate, or back up, but never own your state.
- **Durable memory** — every op is content-addressed and never rewritten or
deleted.
- **Explainable by default** — decision traces record not just _what_ happened,
but _why_.
- **Safe to explore** — branch state to try multiple paths, then merge or
discard.
- **Realtime** — one write updates current state, durable history, and every
live subscriber.
## Install
```bash
npm install -g trellis
```
## Quick start
```bash
mkdir my-project && cd my-project
trellis init # guided or one-shot setup
trellis ui # live graph explorer
trellis code # start an agent coding session
```
Track work as graph-native entities instead of text commits:
```bash
trellis issue create -t "Bootstrap viz"
trellis issue start TRL-1 # branch + lane; worktree when lanes.worktreeBind
trellis protocol send --parent TRL-1 --from executor --to reviewer \
--re TRL-1 --status HANDOFF # graph-backed handoff (3.2.3+)
trellis whereami # re-entry orientation
trellis milestone create -m "Initial release"
trellis garden # discover & revive abandoned work
trellis query 'find ?e where type = "Task"'
```
## Build a realtime app
Scaffold a typed, live-graph app — React, Vue, or Svelte — backed by Trellis:
```bash
npm create trellis@latest
```
```ts
import { defineType } from "trellis/schema";
import { z } from "zod";
export const Task = defineType("Task", {
title: z.string(),
done: z.boolean(),
});
```
```svelte
```
A single mutation produces current state, durable history, and a realtime push
to every subscriber — the same write path.
## API surface
The `trellis` package exposes focused subpaths:
| Import | Purpose |
| ---------------------------------- | ------------------------------------------- |
| `trellis/client` | Local + remote client SDK |
| `trellis/schema` | `defineType`, typed entities, EQL-S queries |
| `trellis/{react,vue,svelte}/typed` | Live, schema-typed reads + mutations |
| `trellis/realtime` | Presence, chat, CRDT text |
| `trellis/cms` | Read content collections over HTTP |
| `trellis/server` | HTTP + WebSocket DB server |
## Documentation
- **[trellis.computer](https://trellis.computer)** — full documentation
- **[The Story](./docs/THE-STORY.md)** — why Trellis exists
- **[Architecture](./docs/ARCHITECTURE.md)** ·
**[Design spec](./docs/DESIGN.md)** · **[Roadmap](./docs/ROADMAP.md)**
## Develop
```bash
bun install # requires Bun ≥ 1.0
bun test
bun run build
```
**In this checkout, prefer `just trellis …` over bare `trellis`.** Global npm
may lag (format skew: array-era CLI + JSONL journal can wipe `ops.json` via
`trellis repair`). Agents are blocked from bare `trellis` here by the Cursor
shell guard; escape hatch: `TRELLIS_ALLOW_GLOBAL_CLI=1`.
```bash
just trellis status # source CLI (bun src/cli) — default
just trellis-dev status # dist CLI after just build
just alias-cli install # adds `trellis-dev` alias; keeps global intact
just link-cli # make global `trellis` → this checkout
just unlink-cli # restore published trellis@latest
```
## License
[AGPL-3.0-or-later](./LICENSE) © Turtle Labs LLC