A structure for growing ideas with agent teams.
Trellis is an agentic pipeline platform. You describe an idea. Agent teams research, build, test, and launch it — running autonomously with human checkpoints between phases. Custom pipelines, sandboxed execution, plugin marketplace, TLA+-verified scheduling.
brew tap terraboops/tap
brew install trellisOr from source:
pip install .trellis init myproject && cd myproject
trellis serve # dashboard + agents at localhost:8000Submit your first idea:
trellis incubate "Cat cafe in Vancouver" -d "A cat cafe targeting remote workers"Or use the web dashboard at localhost:8000/ideas/new.
- Filesystem-first — agents coordinate through files on a shared blackboard, not message passing
- No framework — agents are Claude sessions with plain-text prompts and MCP tools
- Blackboard pattern — context accumulates naturally per idea without a database
- Human-in-the-loop — approval gates between phases via Telegram or the web dashboard
- Agents as plain text — prompts are Python string constants, edit them directly
- TLA+-verified scheduling — the pool scheduler's correctness is formally specified
A pipeline defines which agents work on an idea and in what order. The default pipeline ships with four stages, but you can build your own:
You ──► idea ──► [ stage 1 ] ──► [ stage 2 ] ──► [ ... ] ──► [ stage N ]
│ │ │
▼ ▼ ▼
blackboard/ideas/<slug>/ ← shared filesystem state
The default pipeline (ideation → implementation → validation → release) is just
one template. Create your own in pipeline-templates/ or via the dashboard at
/pipelines/:
# pipeline-templates/research-only.yaml
name: research-only
description: Deep research without building anything
agents: [ideation, competitive-watcher]
post_ready: [research-watcher]
gating:
default: auto
overrides:
ideation: human-reviewEach idea gets its own pipeline config. You can assign different pipelines to different ideas, or modify an idea's pipeline mid-flight from the dashboard.
Pipeline features:
- Custom stages — any agents in any order
- Parallel groups — control which agents can run concurrently on the same idea
- Per-stage gating — auto, human-review, or llm-decides for each transition
- Post-ready watchers — agents that run continuously after the pipeline completes
- Reusable templates — save and share pipeline configurations
The worker pool schedules agents in time-boxed cycles, rotating across ideas by priority. Each agent reads what previous agents wrote and adds its own work.
- Custom pipelines — define agent stages, gating modes, and parallelism per idea
- Pipeline templates — save and reuse pipeline configurations
- Agent wizard — describe what an agent should do and LLM generates the config
- Plugin marketplace — extend agents with MCP servers, hooks, and skills
- Sandboxed execution — kernel-level isolation via nono (Seatbelt/Landlock)
- Priority scheduling — starvation-aware, deadline-pressured, formally verified
- Feedback routing — structured feedback with identity tracking and deduplication
- Knowledge curation — agents accumulate and self-curate learnings across runs
- Real-time dashboard — WebSocket-powered activity feed, cost tracking, pool status
Each agent lives in agents/<name>/ with:
prompt.py— the system prompt (a Python string constant).claude/CLAUDE.md— project-level instructionsknowledge/— structured Knowledge Objects accumulated across runs
The prompts are plain text. No abstractions, no DSLs. Edit them directly.
Copy .env.example to .env:
| Variable | Default | Description |
|---|---|---|
TELEGRAM_BOT_TOKEN |
— | Telegram bot for notifications + approval |
POOL_SIZE |
3 | Concurrent agent slots |
JOB_TIMEOUT_MINUTES |
60 | Worker pool job timeout |
MODEL_TIER_HIGH |
claude-sonnet-4-6 | Model for pipeline agents |
MODEL_TIER_LOW |
claude-haiku-4-5 | Model for watchers |
Agent definitions live in registry.yaml — models, tool access, turn limits,
and token budgets per agent.
trellis init [DIR] Scaffold a new project
trellis incubate TITLE Submit an idea
trellis status IDEA Show idea status
trellis list List all ideas
trellis serve Dashboard + worker pool
trellis serve --background Run as daemon
trellis serve --stop Stop daemon
trellis run Worker pool only (no web UI)
trellis evolve Run knowledge curation
trellis migrate Apply registry migrations
trellis migrate-knowledge Convert learnings.md to Knowledge Objects
trellis migrate-project [DIR] Migrate an incubator project to Trellis
trellis agent upgrade Update agents from package defaults
If you have an existing incubator project, Trellis includes a one-command migration:
pip install trellis # or: brew install terraboops/tap/trellis
cd /path/to/your/project
trellis migrate-projectThis handles everything automatically:
- Renames
.incubator→.trellis(project marker) - Renames
pool/incubator.log→pool/trellis.log - Renames
pool/incubator.pid→pool/trellis.pid - Updates
registry.yamlclaude_home paths - Reinstalls trellis in your project
.venv(if present)
Use --dry-run to preview changes without applying them.
After migrating, replace incubator with trellis in any shell aliases,
cron jobs, launchd plists, or systemd units.
myproject/
.trellis # project marker
.env # config
registry.yaml # agent definitions
pipeline-templates/ # reusable pipeline configs (YAML)
agents/ # prompts and knowledge per agent
ideation/
implementation/
validation/
release/
artifact-check/ # quality checks across all ideas
competitive-watcher/ # monitors competitive landscape
research-watcher/ # tracks relevant research
your-custom-agent/ # add your own
blackboard/ideas/ # per-idea shared state
workspace/ # agent working dirs
git clone https://github.com/terraboops/trellis.git
pip install -e ".[dev]"
pytest -v- Pipelines — custom pipelines, templates, gating modes, parallel groups
- Agent system — customization, creating new agents
- Architecture — blackboard pattern, pool scheduler, phase transitions
- Self-hosting — daemon mode, launchd, systemd, reverse proxy
- Security — sandbox, credential proxy, tool policy, audit, attestation
- Troubleshooting — common issues, diagnostics, copy-paste prompts for Claude Code
Trellis is built in the open by terraboops.
If Trellis saves you time or sparks ideas, consider:
- Star this repo — it helps others discover the project
- Sponsor on GitHub or Ko-fi — supports ongoing development
- Open an issue — bugs, ideas, and feedback all welcome
- Share what you build — tag
#trellisor open a discussion