trellis/README.md

Agentic State Engine — event-sourced causal graph with branching, decision traces, and realtime sync for AI-native applications

<div align="center">
  <img src="./logo.svg" alt="Trellis" width="88" height="88" />
  <h1>Trellis</h1>
  <p><strong>The Agentic Framework</strong> — a local-first, event-sourced graph engine for code, agents, and decisions.</p>
  <p>
    <a href="https://trellis.computer">Docs</a> ·
    <a href="https://studio.trellis.computer">Studio</a> ·
    <a href="https://github.com/trentbrew/trellis">GitHub</a>
  </p>
</div>

---

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
<script>
  import { entitiesStore, mutations } from 'trellis/svelte/typed';
  const tasks = entitiesStore(client, Task);  // re-renders live, across every client
  const task = mutations(client, Task);
</script>
```

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