What is Tug

tl;dr

The Tug Thesis: To get better at larger software projects with AI, coding assistants need to model more a complex workflow than is possible with a handful of prompts in a single context window. Tug aims to provide this support. Tug is about creating an AI-assisted software construction system, thinking through and delivering the tools and techniques humans and coding assistants need to make better software together.

The journal tracks my progress in thinking about these ideas and acting on them with code you can see.

Table of Contents

• Origin Story: How Tug started
• How Tug Works: Orchestrator skills + subagents
• Roadmap: Projects in the pipeline

Origin Story

In December 2025, I started working on a new software project to mash up some ideas from some software I like a lot: JSON, Polars, jq, DuckDB. The idea was to framework that can process tree-structured data, store it in files, re-load it super fast, query it, reshape it... the works. Rust core with Python bindings. In about five weeks, working with Claude Code and Cursor with GPT 5.2, I wrote over 200k lines of code and 8000 tests. I think the software was, and is, cool. (Note to self: I should open-source this project.)

But I also decided to set it aside for now. My reason: the end goal was too abstract. I still don't really know who the software is for and who might want to use it.

Even so, I made three interesting discoveries:

1. WOW! You can write a lot of code these days using AI coding assistants.
2. Because the LLMs relieved me from having to concentrate about every line of code that needed to get written, I could think at a more high level about the work I was doing. This allowed me to push boundaries more. I had more cognitive overhead available, which I used to discover new things, like: write amplification, Multiversion concurrency control/(MVCC) , Optimistic concurrency control (OCC) , and the Arrow columnar format. This was great fun.
3. Writing that much code in such a short amount of time led to the need to refactor way more than would have been necessary if the code evolved more slowly and incrementally. I found I needed to move things around, do mass renames of file and functions, trim off dead ends that weren't worth keeping.

This last discovery hit me while I was watching Claude Code do its work in the terminal. ¹ I saw how the AI assistants really struggled at refactoring. They could write code fluently—almost effortlessly—but then couldn't always read back what they had written. The problem became more profound as the number of lines of code involved became larger, which makes sense, given the size of context windows. However, there was also a struggle with the semantic and conceptual connections between code, which lead to greps for code “analysis” or sed/awk call chains to do a complex refactor.

I started this project to give AI the tools to supply language semantics and a codebase-wide view they don’t have. I dug into that, but after a couple of weeks, I became far more interested in the process of creating a coding environment that takes full advantage of the new possibilities of AI coding assistants. I wrote a 20-step workflow that detailed the way I was using AI to help me write code.

I became far more interested in the process of creating a coding environment and workflow that takes full advantage of the new possibilities of AI coding assistants, something that I can use for all projects all the time—not just when I'm refactoring code.

This brings me to the Tug Thesis: To get better at larger software projects, AI coding assistants need more structure and more complex workflows than are possible with a handful of prompts in a single context window. Tug aims to provide that.

How Tug Works

Tug is a workflow for building software with AI coding assistants. It lives in Claude Code as a small set of orchestrator skills that spawn a suite of specialized subagents.

The workflow is an automated version of the planning/implementation loops described in How I Write Code With AI, and discussed more fully in A Bigger Vision For Tug.

• Plan: You run /tugtool:plan with an idea. Tug iterates on a plan until it’s ready, then writes a tugplan markdown file (a structured design + step list).
• Implement: You run /tugtool:implement on that tugplan. Tug creates an isolated git worktree + branch, then walks steps one-by-one using agents (architecture → coding → review → commit), producing a PR for you to review.
• Merge: If you like the PR, you run /tugtool:merge to bring the work back onto your main branch and clean up the worktree.

The key idea is that the “work product” isn’t just code: it’s also the structured artifacts and the history of how the change came to be—decisions, steps, reviews, and commits—so larger projects stay understandable as they grow.

Roadmap

Today, Tug is centered around tugplan (the intended path) and tugtool (the engine that does the work). In the future, additional components will make this feel less like “a few commands” and more like a full software construction environment.

• tugcast: an event stream of what happened during planning and implementation.
• tugcard: a user interface widget that displays information in tugcast.
• tugfeed: a “channel” that produces the content sent out over a tugcast, sourcing data from the filesystem, git, agents, and more.
• tugdeck: a control/observation surface—where you can watch progress and steer.
• tugdots: a connective execution model that preserves the narrative of work (actions, decisions, state snapshots, dependencies). Today this is partly backed by `beads`; the goal is a richer, more explicit model.

Over time, these pieces will support more features as the need for them arises. If these ideas hold true, tugcode will become a place where humans and models collaborate to write software together.