Trellis: Training wheels for your AI coding agent

On the first day of Tet, I sat undoing the commit that Claude Code had automatically pushed to main at 2am.

It deleted the entire validation layer, renamed several handlers from GetMenuByID to fetchMenuByID - breaking the Go exported function PascalCase convention that the whole team had agreed upon. It wasn’t exactly a bug, but the code looked like a mess. Review rejected, pull rolled back, the whole team lost half a day.

Was the error due to Claude Code? Not exactly. It did exactly what it was asked to do. The problem is that it didn’t know about project convention - it didn’t know the team used PascalCase for exported functions, it didn’t know the validation layer had to be kept intact, it didn’t know there were specs that prohibited demolishing and rebuilding.

A few months later, I found Trellis. A GitHub repository that called itself “training wheels for AI coding assistants.” After reading the README, I knew - the hole my team was falling into, someone had already dug an exit tunnel beforehand.

Agents are fast, but Harness is what keeps them from falling

There’s a common misconception that I see everywhere: people think Trellis is an AI coding agent. Not so.

Trellis is an Agent Harness - a workflow layer that sits between you and the coding agent (Claude Code, Codex, Cursor, OpenCode, Copilot, Gemini CLI, etc.). It doesn’t write code. It manages context, spec, task, journal - all the things that the coding agent “forgets” every time it starts a new session.

You → Trellis (.trellis/) → Claude Code / Codex / Cursor → Code

The way Trellis solves the problem is a bit unconventional: file-based knowledge. No database. No vector store. No cloud service. Everything is stored in the .trellis/ folder in your repo - markdown, JSON, YAML - all git-tracked. Anyone who clones the repo gets the spec immediately.

Extremely simple. Extremely inspectable.

Setup: 30 seconds, painless

Install Trellis via npm:

npm install -g @mindfoldhq/trellis@latest

Initialize in your project:

cd my-project
trellis init --claude --codex --cursor

This command creates the following structure:

.trellis/
├── workflow.md           # executable workflow contract
├── spec/                 # coding standards, conventions
├── tasks/<slug>/         # PRD, design, implement/check manifests
├── workspace/<dev>/      # per-developer journals
└── .runtime/             # active session pointers

It takes 30 seconds. No additional configuration is needed. --claude --codex --cursor tells Trellis to support all three platforms, allowing a single .trellis/ to run everything.

Internal Architecture: Spec, Task, and the Learning Loop

Trellis has 3 main concepts, understanding these 3 concepts means understanding the entire system.

1. Spec Library (.trellis/spec/)

This is where the project’s coding standards are stored. Each spec file describes the conventions for a specific package or layer. You don’t have to write it by hand - Trellis can auto-draft specs from the current codebase, you just need to tighten up the important parts.

For example, spec for backend Go with Gin + gRPC:

# spec/backend/go-conventions.md
## Naming
- Exported functions: PascalCase (`GetMenuByID`, `CreateOrder`)
- Unexported functions: camelCase (`fetchMenuByID`, `saveOrder`)
- Proto files: snake_case (`menu_service.proto`)

## Validation
- All input from the client **MUST** be validated through the `binding:"required"` tag + custom validator
- Do not use `interface{}` for the request body - define a concrete DTO struct

When you create a new task, Trellis compos spec: only takes the specs related to that task, injects them into the context of the coding agent. The agent codes correctly from the first time.

2. Task Tree (.trellis/tasks/)

Each task is a folder slug, inside which there are:

• prd.md - Product Requirement Document
• design.md - Technical design decisions
• implement.json - Manifest for sub-agent implementation
• check.json - Manifest for sub-agent checking

When you run trellis start task/<slug>, it kicks off a 4-phase workflow:

Plan → Implement → Verify → Finish

• Phase 1 (Plan): Brainstorm skills, ask questions one by one, write PRD. Sub-agent trellis-research (read-only) looks up specs, researches, and proposes solutions.
• Phase 2 (Implement): Sub-agent trellis-implement reads the context manifest, writes code. Does not commit, does not push. Only git diff to a patch file.
• Phase 3 (Verify): Sub-agent trellis-check reviews the diff, runs lint + typecheck + test. If it fails, it automatically fixes and runs again (self-fix loop).
• Phase 4 (Finish): trellis-update-spec analyzes whether there is new learning, if so, proposes an update to the spec. Archives the task. Writes a journal.

The interesting thing is that each phase has its own sub-agent with limited permissions - trellis-research cannot write files, trellis-implement cannot commit, trellis-check cannot push to remote. Similar to the code management model in a team: dev writes, reviewer checks, only the lead merges.

3. Journal & Knowledge Capture

Each time a task is performed, Trellis writes a journal to workspace/<dev>/. This is not just a log for fun - it is input for the feedback loop.

There is a skill that I find most impressive: trellis-break-loop. After debugging a difficult bug, Trellis automatically analyzes 5 dimensions:

• What is the root cause?
• Why did the previous attempt fail?
• How to prevent future occurrences?
• Systematic expansion (does this bug appear elsewhere?)
• Knowledge capture: writes it into the spec immediately

The more you use it, the thicker the spec library becomes, and the fewer mistakes the agent makes.

Trying it out: First Impressions

I tested Trellis with Claude Code on a Go microservice for processing merchant menus - Gin + gRPC, around 20 files. The workflow ran smoother than I expected.

The first bright spot is the task plan. When running trellis start, instead of Claude Code jumping straight into coding (and often coding in the wrong direction), Trellis stops it and asks questions one by one: “what is the goal of the task?”, “are there any specs that affect it?”, “what approach is suitable?” - similar to a senior engineer guiding a junior, rather than AI running wild.

Result: the first implementation passed the test. It feels… strange. I’m used to the style of “running AI, reading output, fixing it on the 2nd, 3rd try, getting frustrated”. Trellis makes me skeptical - maybe the task was just easy. But trying a harder task (adding a Redis caching layer for the API to get menus by merchant, considering cache invalidation when the menu changes) and it still passed on the 2nd try. Not magic, but a clear improvement.

Developer Experience: Is it enjoyable?

The biggest advantage: Multi-platform from the start. A .trellis/ runs on Claude Code, Codex, Cursor, Copilot, Gemini CLI - 16+ platforms. Divided into 3 classes:

• Class 1 (hook-based): Claude Code, Cursor, OpenCode, Kiro - auto-inject context each session
• Class 2 (pull-based): Codex, Copilot, Gemini, Qoder - use prelude injection
• Class 3 (extension): Pi Agent

If your team uses Claude Code, and your friend uses Cursor - both can still share the same .trellis/. Collaborate without needing to agree on tools.

The second advantage: Parallel execution via git worktrees. Each agent runs in its own worktree. Want 2 tasks to run concurrently? Just spawn an additional worktree. No need for a complex orchestrator.

The downside: The initial workflow is a bit lengthy. If you just want to “AI, please fix this bug quickly”, you have to go through 4 fairly heavy phases. Fortunately, Trellis allows skipping phases if desired.

Comparison with Hermes Agent and OpenClaw

I have used both Hermes Agent and OpenClaw, so I’ll share my comparative perspective.

Hermes Agent (from Nous Research) is also a harness, but it’s oriented differently. Hermes was born to be a personal agent - chatting with you, using tools, having memory, and running on multiple platforms. It’s more like a personal assistant. Trellis is not - Trellis is an engineering framework for coding workflows. If Hermes is a friend sitting next to you, helping you search Google and summarize emails, then Trellis is the playbook your team uses when coding - where specs are, which conventions to follow, and how to perform tasks.

OpenClaw, which I’ve written about before, is closer to Trellis - also a harness for coding agents. However, OpenClaw is weak in multi-platform support: it mainly supports Claude Code. Trellis has 16+ platforms out of the box. In terms of spec management, Trellis is also more structured with a spec library + compos pattern.

As for maturity: Trellis v0.6.x has reached General Availability (GA), with 10.8k stars and a fairly active community. OpenClaw is smaller. Hermes is newer but developing quickly.

Weaknesses: Nothing is Perfect

Trellis has a few weaknesses that I’ve noted:

1. AGPL-3.0 license. This is an issue if you’re working on a commercial product. AGPL requires that if you modify the code and deploy it in a network-accessible manner, you must open-source the entire project. Startup teams need to check with their legal team beforehand.

2. Spec management is the team’s responsibility. Trellis automatically drafts specs, but finalizing them is still a human task. If the team is lazy, the spec library will become outdated, and Trellis will lose its effectiveness. Garbage in, garbage out.

3. Workflow overhead. The 4-phase workflow is great, but for very small tasks (fixing typos, renaming variables), it’s a bit overkill. Trellis allows skipping phases, but you need to know how to use it.

4. Windows support. The community has reported some issues with file paths on Windows. If your team uses Windows, you should test it thoroughly before committing.

I’ve also seen some bugs reported on GitHub issues (#234-#277) related to codex sub-agent recursion and manifest over-hashing. The nature of open-source projects in the growth stage is that features are often developed faster than bug fixes.

When to use and when not to use?

Should use if:

• Your team uses AI coding agents and wants to generate standardized code
• You want to share conventions between Claude Code, Codex, Cursor without rewriting configurations for each tool
• You are scaling from a single developer using AI to an entire team using AI - needing a standardized workflow
• Your project has many parallel tasks and you want to utilize git worktrees

Should not use if:

• You are a solo developer, only needing AI to quickly fix code - Trellis overhead is not worth it
• Your project does not have clear conventions (still in the early stage, exploring)
• You need a commercial license that is not AGPL
• Your team uses Windows and no one is willing to debug

Bottom line

Trellis solves a real problem: AI generates code quickly, but the code doesn’t follow conventions. If your team has ever reverted a commit from Claude Code at 2 am, you’ll understand the pain.

File-based, git-tracked, and no need for the cloud - these are design decisions that I highly respect. They make Trellis easy to experiment with, easy to roll back, and easy to understand. No magic, no black box.

Compared to Hermes Agent and OpenClaw, Trellis is the most specialized for engineering workflows. It has a spec library, a 4-phase workflow, and a feedback loop for self-learning. It’s true to its niche.

The number of GitHub stars (10.8k) doesn’t lie - the community is voting.

If you want to try it, run npm install -g @mindfoldhq/trellis@latest, execute trellis init, and give your Claude Code a spec to make it code more disciplined. If you don’t like it, uninstalling is easy, with no lingering effects.

Repo: https://github.com/mindfold-ai/trellis

If you’ve used it, leave your comments below. I’m currently testing Trellis for my new food delivery project (menu service + merchant portal) with OpenCode - if there’s anything interesting, I’ll write a follow-up.