CodeTrellis

A way to plan, watch, and keep AI coding agents on track — and a
way to keep yourself on track too, even when no agent is involved.

⬇️ Download

Desktop

Mobile companion

The companion lets you watch agents, browse plans, drive terminals, and explore the graph from your phone — pairs to the desktop over your LAN or your own VPN (e.g. Tailscale).

All builds + release notes live on the Releases page →

First-launch notes

• macOS — signed & notarized by Apple (Developer ID: AILAR Limited) since v0.1.10, so it should just open: open the DMG, drag CodeTrellis to Applications, and launch. If you still hit a Gatekeeper warning ("unidentified developer") or an "app is damaged / can't be opened" message — which can happen with an older build, or if the download stripped Apple's quarantine attributes — clear the flag once in Terminal and reopen:

  xattr -cr /Applications/CodeTrellis.app
  

• Windows — the installer isn't code-signed yet, so SmartScreen may warn once — click More info → Run anyway.
• Linux (AppImage) — chmod +x CodeTrellis-0.1.15*.AppImage && ./CodeTrellis-0.1.15*.AppImage. Portable, no install. Pick the file matching your CPU (-arm64 for ARM, otherwise x64).
• Linux (.deb) — Debian / Ubuntu: sudo apt install ./codetrellis_0.1.15_*.deb.
• Linux (.rpm) — Fedora / RHEL: sudo dnf install ./codetrellis-0.1.15.*.rpm.
• Android — the APK isn't from the Play Store (Play listing is in progress), so when you open it, allow "Install unknown apps" for your browser/file manager, then install. It's signed with a stable key, so future versions upgrade in place.
• iOS — distributed via TestFlight while we finish App Store review; you'll get an email invite with a code.

Linux: the AppImage runs without the Chromium sandbox

Worth knowing before you pick a Linux download, and an earlier version of
this note undersold it by framing it as an Ubuntu 24.04 problem.

The AppImage runs with the Chromium sandbox off — on every distro, not
just Ubuntu. That is our own doing, not a fallback: from v0.1.4 the app
passes --no-sandbox whenever it detects it is running from an AppImage,
because AppArmor's unprivileged user-namespace policy on modern Linux
breaks Chromium's setuid sandbox inside one. Without it you get:

FATAL:setuid_sandbox_host.cc(...) The SUID sandbox helper binary
was found, but is not configured correctly.

It is the same trade Cursor, Obsidian and most other Electron AppImages
make, and for a local tool loading its own bundled HTML the practical risk
is low. But it is a real reduction in defence-in-depth, and you should know
you are taking it.

The .deb and .rpm keep the sandbox. Where you have the choice —
Debian, Ubuntu, Fedora, RHEL — prefer those. The AppImage is for distros
where you don't.

Why I built it

I prefer to focus on architecture and conformity. When I started
working with AI coding agents I noticed two things really fast:

1. The sessions where I got the cleanest output were the ones where
   I'd put serious effort into the plan first — defining the
   CRUD blocks, mapping how things connected, writing the executive
   summary, the architecture doc, the UX journey, the testing
   parameters, the success metrics. The more I scaffolded up front,
   the less the agent drifted.
2. Even with a great plan, the agent would still wander — picking up
   weird side-quests, forgetting earlier decisions, occasionally
   undoing what it had just built.

So I started building CodeTrellis as an internal tool to track the
plans I was making and watch what the AI was doing in real time. If
I asked it to centralise a service or refactor a module, I wanted to
know it was actually still on that plan and not somewhere else.

That grew into what's here now.

The "AI agent harness" idea has been picking up. CodeTrellis is my
own take on it — one that's simple, gets out of the way, and works
with or without an AI agent. If you're not doing AI-assisted
development at all, it's still useful as a way to track your own
work against a plan and see what's actually changing in your
codebase.

What it does

• Visualises your codebase as a dependency graph — packages,
  files, and symbols (functions, classes, methods), with cross-system
  edges where one service calls another over HTTP/SQL. Eleven
  languages on one canvas: TypeScript, JavaScript, Python, Go, Rust,
  Java, Kotlin, Swift, C#, Ruby, PHP — plus your SQL schema.
• Reads as code, not only as a picture. There's a mode where the
  graph never mounts: your files, a diff editor, and the plan drawn
  onto the code. Cheaper to render on a large repo, and more legible
  if you think in files.
• Lets you write plans that scale from a one-line "do this thing"
  to multi-phase migrations with spec docs, acceptance criteria,
  prerequisites, and templates. As simple or as complex as you want.
• Hosts a local MCP server so any MCP-capable AI agent — Claude
  Code, Codex, Cursor, aider, anything that speaks MCP — can read
  the plan, ask questions about your architecture, and report what
  it's doing.
• Watches your repo via git and shows you exactly what changed,
  diffed against any commit you pick. The whole core ethos is built
  on version control — you can be as high-level or low-level as you
  want.
• Surfaces drift in real time — if the agent wrote a file that's
  not in the plan, or the plan said "create function X" and that
  function still doesn't exist, you see it.
• Proves what actually landed. Compare any two points in the
  project's history, check the diff against the plan that claimed it —
  every item comes back landed, partly landed or untouched, files
  nobody planned get called out, and the whole thing drafts your pull
  request description.
• Comes with a phone. The companion app pairs to the desktop by QR
  over a peer-to-peer connection, so you can watch agents, browse
  plans and drive terminals from your phone. No central server.

How I actually use it

These are real workflows that have shifted my hit-rate with AI
agents. Your mileage will vary, but they're the shape of what's
possible.

• Re-running a plan with a different agent. I run a plan with one
  agent, don't love the output, then point a different agent at the
  same plan and see how it does. The plan stays put; the executor
  changes.
• Splitting work across agents. Claude for the heavy refactor,
  Codex for the test scaffolding, Cursor for the UI tweaks — each
  agent owning specific parts of the plan. Useful for picking the
  best tool per job, and for working around per-agent usage limits.
• Recursive runs. I set up an agent to work the plan, then let
  it loop until it hits a stop condition. Every tool call lands in
  the timeline so I can review the run after the fact.
• High-level monitoring. When an agent is mid-build I keep the
  graph open. If I see the blast radius spreading somewhere it
  shouldn't, I can interrupt, give feedback, and steer it back —
  this has saved me from a lot of "now I'm in too deep" moments.
• Context refresh. When an agent's context starts to thrash, I
  clear it out and have it re-ingest the plan from MCP. Same for
  switching machines — the plan is on disk, not in some browser
  tab, so I can pick up on a different device and an agent there
  reads the same source of truth.

Privacy & cost

This is the part I want to be very direct about:

• The app sends no data anywhere. It scans your local repo,
  writes to a local SQLite file, and runs a local MCP server. No
  telemetry, no cloud, no analytics, nothing leaves your machine.
• All AI features are powered by your AI agent, not CodeTrellis.
  The agent connects to CodeTrellis over MCP locally; the AI
  processing happens inside whatever agent you're using.
• AI costs come out of your existing AI usage. Because CodeTrellis
  uses MCP, the agent calls the local MCP server to build plans,
  get architecture context, address drift — all of that traffic
  stays between you and your agent. There is no TOS violation —
  you're using your own agent the way you already do, just with
  more structure.
• Data concerns — manage them where you already manage them: in
  the agent. CodeTrellis is just a view.

Requirements

• Git installed on your machine (the diffing engine relies on it).
• An MCP-capable AI agent if you want the AI features (Claude
  Code, Codex, Cursor, aider, etc.). Optional — if you're not
  using an AI agent the app still works fine for hand-authoring
  plans and watching your own changes.

Source

The source is open. All of it — desktop app, mobile companion, MCP
server, every parser — lives at
lionroseway/codetrellis
under Apache 2.0. Read it, fork it, build it yourself, send a patch.

This repo stays where the downloads live. That split is on purpose:
distribution shouldn't depend on the source repo being reachable, so
installers keep working regardless of what happens over there.

Feedback is still the most useful thing you can send:

• Are there workflows you tried that didn't fit cleanly?
• Anything that crashed or behaved weirdly?
• Plan templates you wish were built in?
• Features you assumed would be there and weren't?

Open an issue on the
source repo — even a one-liner helps.

License

Apache License 2.0.