DEV Community: Chauncey Wang

No neural nets, no tree: inside a Go engine that plays 40,000 games per second

Chauncey Wang — Fri, 21 Aug 2026 02:54:37 +0000

In December 2012 — three years before AlphaGo — I wrote a Go AI in C++ called FoolGo. It has no neural networks, no opening book, no hand-crafted evaluation function. Just Monte Carlo tree search with UCB1, and enough systems engineering that it simulates about 40,000 complete games of Go per second — benchmarked on my 2014 MacBook Air.

It never got past beginner strength on 9×9, and I've always been upfront about that. Most of the repo's stars actually arrived after AlphaGo beat Lee Sedol in 2016: once the whole world wanted to know how Go AI worked, people came looking for the pre-intuition machinery in readable form — what the field ran on before neural networks learned to feel a board. This post is a tour of the engineering that makes vanilla MCTS fast — because for vanilla MCTS, fast is the only thing there is.

Why throughput is the whole game

Pure MCTS has no way to evaluate a Go position directly. To judge a candidate move, it plays random games from that position all the way to the end, and counts wins. Strength is roughly a function of how many of these playouts you can afford per move. There's no clever prior to save you — the engine is its simulation throughput. So every design decision below is about the same thing: making "play a full random game of Go" as close to free as possible.

Board size fixed at compile time

Everything in FoolGo is templated on the board length:

template<BoardLen BOARD_LEN>
class FullBoard { /* ... */ };

A 9×9 engine and a 19×19 engine are different types, compiled separately. That sounds like C++ showing off, but the payoff is concrete: every array in the hot path — the board, the chain structures, the hash tables of the hasher — has a size known at compile time. No std::vector growth, no heap allocation during search, no pointer chasing where an array index will do.

Stones as disjoint sets, in flat arrays

In Go, stones of the same color that touch form a string, and the string — not the stone — is the unit of life and death: the moment a string's last liberty (adjacent empty point) is filled, the whole string is captured and removed from the board at once.

Watch what a single move can do:

Before the move, black has two strings — and they are not equal. The pair at c4–c5 shares five liberties as one unit; the lone stone at e5 has been squeezed down to exactly one. In Go terms it is in atari: one White move from being eaten. Connecting at d5 is the rescue — and notice that this single placement fuses two strings and the new stone into one four-stone string with five liberties. Count the rings on the right: the arithmetic isn't additive. Merging liberty sets means deduplicating them — a detail that will matter shortly — and enemy stones don't count: White's four stones block four of what would otherwise be nine. The rescue cost White too: its d4–e4 string just lost one of its own liberties. Push any string's count to zero and it gets eaten — captured and removed from the board at once. A stone has four neighbors, so a single placement can fuse up to four strings (plus the new stone) into one.

And that's the disjoint-set view of the same event — before, two sets; after, one:

before:   set A: head = c5,  stones: c4 → c5,  c5 → c5
                 liberties {b4, b5, c3, c6, d5}
          set B: head = e5,  stones: e5 → e5
                 liberties {d5}

play d5:  union(A, B, d5)

after:    set A: head = c5,  stones: c4 → c5,  c5 → c5,  d5 → c5,  e5 → c5
                 liberties {b4, b5, c3, c6, d6}

Each stone points straight at its set's head, so find is a single array read. The price shows up at merge time: the absorbed side's stones get repointed to the surviving head — and MergeLists chooses sides by size, relabeling the smaller list into the larger (the classic union-by-size trick that keeps total relabeling cheap). So the freshly played stone, a list of one, never wins the election: here d5 and then e5 are repointed into the c4–c5 pair's head. And the liberty sets OR together, minus the point just filled, plus the new stone's own empty neighbors. Hold that picture; the code below is nothing more than this, made fast.

Now count what the engine must answer on every move of every simulated game:

Which string does this neighbor belong to? — find
Did my move drop that enemy string's liberties to zero? If so, remove all of its stones, immediately — an aggregate query plus member enumeration
Is my move suicide? — the same query, pointed at my own string
Did my move connect friendly strings? Merge them — union

At 40,000 games per second, a couple hundred moves per game, that's millions of move-executions per second, each running several of these queries. They all have to be near-O(1).

This is the union-find problem wearing a Go costume — with two extra requirements the textbook version doesn't have: each set needs cheap member enumeration (to delete a captured string from the board) and a cheap aggregate statistic (the liberty count that decides capture and suicide). FoolGo's ChainSet answers all of it with two flat arrays — one node per board point, one list record per potential chain:

struct Node {
  PositionIndex next_, list_head_;
} nodes_[BoardLenSquare<BOARD_LEN>()];

struct List {
  PositionIndex tail_, len_;
  BitSet<BOARD_LEN> air_set_;
  AirCount air_count_;
} lists_[BoardLenSquare<BOARD_LEN>()];

list_head_ is the find pointer — every stone knows its string's representative. The next_ chain makes members enumerable without searching the board — that's the capture-removal path. And the per-list air_set_/air_count_ are the aggregates that answer capture and suicide checks in constant time. Merging two strings is a list splice plus head-pointer updates — index arithmetic on preallocated arrays, no allocation, no tree balancing.

Liberties as bitsets

The expensive bookkeeping is the liberties themselves ("airs" in FoolGo's vocabulary): every placed stone changes the liberties of all its neighbors. FoolGo stores each string's liberties as a bitset over board points. When strings merge, their liberty sets merge with a bitwise OR; counting is a popcount. Some of the hottest bookkeeping in the engine compiles down to word-sized bit operations.

Here is the connection at d5 again, seen through the bitsets:

                    b4 b5 c3 c6 d5 d6      (75 more bits, all 0)
pair {c4,c5}         1  1  1  1  1  0
lone {e5}            0  0  0  0  1  0
new  {d5}            0  0  0  0  0  1

OR                   1  1  1  1  1  1
clear d5 (filled)    1  1  1  1  0  1     popcount → 5

Three ORs, one bit-clear, one popcount. There is no deduplication logic anywhere: d5, a liberty of both black strings, is simply the same bit twice, and OR-ing makes the duplicate vanish by construction. On a 9×9 board the whole set fits in two machine words, so "merge three strings and recount the result's liberties" costs a handful of CPU instructions.

Anatomy of a move

All of that bookkeeping exists to make one operation cheap: actually playing a move. Here is FoolGo's real pipeline, from full_board.h.

First, is the move even legal? IsSuicide looks at the four neighbors of the empty point — and at nothing else:

for each of the 4 neighbors:
    empty?                                 → not suicide (instant liberty)
    friendly string with ≥ 2 liberties?    → not suicide (joins a string that still breathes)
    enemy string with exactly 1 liberty?   → not suicide (the move captures it, freeing space)
none of the above                          → suicide

Four array reads. No board scan, no trial placement — every clause is answered by a per-string air_count_ that the merge machinery has been keeping current all along. The friendly clause needs ≥ 2 because the new stone fills one of that string's liberties on arrival; the enemy clause is the elegant one — a move onto your last-looking point is perfectly legal if it kills the surrounder first.

Here are the clauses on the board:

In the left position, e5 fails every clause: no empty neighbor, no friendly string to join, no enemy string at one liberty — suicide, illegal. Add a single black stone at d3 (middle) and the three-stone white string d4–d5–e4 falls to its last liberty: the same point now passes the kill clause. Play it (right) and the pipeline below runs — the string is eaten first, RemoveChain walking its cyclic list, so by the time the black stone lands it has two liberties: points it just vacated.

Then, play it. PlayBasicMove runs the same four-neighbor scan once more, now with consequences, in a very deliberate order:

Captures first. Any enemy neighbor string down to its last liberty is eaten on the spot: RemoveChain walks its cyclic list and clears the stones — and the newly emptied point next door is immediately recorded as a liberty of the stone about to be placed. The new stone breathes into the space it just vacated.
Place the stone, and clear its point's bit from every adjacent string's liberty bitset — friend and enemy alike.
Merge. AddPiece creates the one-stone set and union-by-size folds it together with its friendly neighbors — the disjoint-set dance from earlier.
Suicide cleanup. If, after all that, the just-built string has zero liberties, it is removed by the very same RemoveChain — suicide isn't a special case, it's a capture whose victim is yourself.

Every step is either a four-neighbor loop or an operation on the structures above — nothing touches the other 76 points of the board. That locality, times forty thousand games a second, is the entire performance story.

There is no tree

The textbook picture of MCTS is a tree of nodes with parent/child pointers. FoolGo doesn't build one. Instead, every game state maps to a 64-bit Zobrist hash, and node statistics live in a flat hash table:

struct StaySelfHasher {
  std::size_t operator()(HashKey hash_key) const {
    return hash_key;   // the key is already a hash — don't hash a hash
  }
};

std::unordered_map<HashKey, NodeRecord, StaySelfHasher> node_record_map_;

(StaySelfHasher is my favorite two lines in the repo: the key is a Zobrist hash, which is already uniformly distributed, so the map's hasher is the identity function.)

This is a transposition table, and it quietly upgrades the search from a tree to a DAG: two different move orders reaching the same position share one node and one set of statistics, for free. Whenever different move orders transpose to the same hashed state, that's not a micro-optimization — it's extra effective simulations without simulating.

Zobrist hashing, incrementally

Recomputing a position's hash from scratch would cost O(board area) per move. Zobrist hashing makes it O(changed stones): XOR out what left, XOR in what arrived.

HashKey GetHash(const FullBoard<BOARD_LEN> &b) const;              // full
HashKey GetHash(HashKey hash, const BoardDifference &chng) const;  // incremental

The scheme is beautifully dumb. At startup, generate one random 64-bit number for every (point, state) pair — FoolGo's table is literally board_hash_[81][3] — plus numbers for the side to move and for each possible ko point. A position's hash is the XOR of the numbers matching its current contents. Everything rests on one property: XOR is its own inverse, so XOR-ing the same number twice removes it. "Update" and "undo" are the same operation, and a move's hash cost is proportional to what the move changed:

h' = h ^ Z[d5][EMPTY]      // d5 stops being empty...
       ^ Z[d5][BLACK]      // ...and becomes black
       ^ Z[BLACK] ^ Z[WHITE]   // turn marker: XOR out "Black to move", XOR in "White to move"
       // plus one pair of XORs per captured stone, if any

The turn-marker pair is there because whose move it is is part of the position. Look back at the diagram: with Black to move, e5 gets rescued; with White to move, e5 gets eaten — opposite fates, identical stones. If those two states hashed the same, the transposition table would merge them and their statistics would be garbage. So exactly one of two random "to move" numbers is always XOR-ed into the hash, and each move swaps them. Our connection at d5 thus touches four numbers; a capture would touch two more per removed stone. Nothing else on the board is looked at — which is what lets forty thousand games per second afford a fresh hash after every single move.

The hasher also carries a table for the ko point (ko_hash_, plus a no-ko number), and the reason is subtle. After a ko capture, one point is temporarily illegal to play. Two boards with identical stones but different ko status therefore have different legal moves — and if they hashed the same, the transposition table would happily merge them into one node, letting statistics gathered in one position answer questions about the other. Getting ko into the hash is the kind of detail that costs you an afternoon of debugging exactly once.

UCB1, verbatim

The selection policy is the classic formula, and the code is honest about it:

float Ucb(const NodeRecord &node_record, int visited_count_sum) {
  return node_record.GetAverageProfit()
      + sqrt(2 * log(visited_count_sum) / node_record.GetVisitedTime());
}

Average observed value plus an optimism bonus that shrinks as a node gets visited: exploitation plus exploration in one line. Here it is with numbers — three candidate moves, a thousand playouts spent so far:

parent visits N = 1000          2·ln N ≈ 13.8

move   visits n   avg profit   bonus √(2·ln N / n)    UCB
A         700        0.52             0.14            0.66
B         250        0.46             0.24            0.70
C          50        0.38             0.53            0.91   ← next playout goes here

The next simulation goes to C — the move with the worst observed average. That's not a bug; the bonus is uncertainty made numeric. After only 50 samples, the search cannot yet distinguish a bad move from an unlucky one, so C's claim on the budget is still large. If C keeps disappointing, its average stays low while its bonus shrinks like √(ln N / n), and the playouts drift back to A, whose higher mean now stands on 700 samples. Spend where confidence is thinnest, harvest where confidence is strongest — the formula does both without a single special case. Everything else in the search exists to make evaluating it cheap, millions of times.

Multithreading by mutual avoidance

FoolGo searches on multiple CPU threads sharing the one transposition table (a mutex guards it). The interesting choice is how threads avoid redundant work: rather than implementing virtual loss — the standard trick of temporarily penalizing a node while a thread explores it — FoolGo simply forbids a thread from descending into a node a peer is currently exploring. Here's what that means at the node we just scored:

thread 1 arrives:  UCB says C (0.91) → descends into C, marks it in-progress
thread 2 arrives:  UCB says C — but C is taken → settles for B (0.70)
thread 3 arrives:  C and B both taken → gets pushed to A (0.66)
threads return:    marks cleared, statistics updated, selection sees fresh numbers

Thread 2 wanted C — the policy's actual choice — and got the runner-up; thread 3 got third-best. That's the distortion: under contention, the search behaves as if the top candidates were briefly invisible. Virtual loss is the gentler version of the same idea — a temporary penalty instead of a wall, so a favorite whose lead is big enough can still absorb several threads at once. FoolGo's wall is cruder. But it's a few lines, it can't deadlock, and it was enough to scale a hobby engine across the cores of a laptop.

How the grown-ups solved the same problems

FoolGo's choices get more interesting next to the famous open-source engines that came after it — Leela Zero (2017, the community AlphaGo-Zero reproduction) and KataGo (one of today's strongest open-source Go engines) — and the ones that came before it: GNU Go (whose board code dates to the 1990s), Pachi, and libego (Łukasz Lew's minimalist MCTS library). I went digging through their codebases to compare notes on the same subproblems.

One skeleton, five engines

Five engines, written independently across more than two decades, landed on the same core data structure — flat arrays over board points, a circular linked list threading each string's stones, one stone as the representative. The names barely differ: GNU Go (1990s) has string_number[] and next_stone[], Pachi has group_at[] and groupnext_at[], FoolGo has list_head_ and next_, Leela Zero has m_parent[] and m_next[], KataGo has chain_head[] and next_in_chain[]. There is no lineage here — the problem shape forces the answer — and GNU Go's comment from the 1990s could caption them all: "the stones in a string are linked together in a cyclic list." Five engines, two decades, one skeleton.

Six ways to count a breath

The chain skeleton converged; liberty bookkeeping went six different ways:

GNU Go keeps an exact count plus the full list of liberty coordinates (string_libs[].list[]) — a classical engine wants to reason about specific liberties, not just count them.
Pachi caps the list at ten, refilled lazily — its own comment admits libs "is only LOWER BOUND for the number of real liberties!!!" Playouts rarely need more than "is this 0, 1, or 2."
libego never dedupes at all: pseudo-liberties plus algebra. Its Chain stores the count, sum, and sum of squares of its pseudo-liberty vertices — a chain is in atari exactly when count · Σx² = (Σx)², and the atari point is sum ÷ count.
FoolGo: the exact set as a bitset — merge is OR, dedup by construction.
Leela Zero: exact scalar counts, paid for with a dedup walk at merge time (plus a pseudo-liberty helper for rough checks).
KataGo: exact scalar counts, incremental, with bound-estimating shortcuts.

Same invariant, six answers — ranked, roughly, by how much each engine wants to know about its liberties versus merely count them.

Three clauses, rediscovered

Playing a move converged even harder than the data structures. FoolGo's three-clause suicide test — empty neighbor: no; friendly with two-plus liberties: no; enemy with exactly one: no — turns out to be structurally identical in Leela Zero's is_suicide and KataGo's isSuicide: the same three clauses, in the same order — independent rediscovery, because the test is simply the minimal correct answer the rules allow. There is no fourth clause to invent: a move survives by gaining a liberty directly, joining something that outlives it, or making room by killing. Leela Zero merely bolts a pseudo-liberty fast path onto the front (if (count_pliberties(i)) return false; — any adjacent empty point settles it immediately). The real differences live at the edges. Pachi caches, for every point, how many of its neighbors are black, white, or off-board — immediate_liberty_count is just 4 minus those counts — so the commonest clause is answered without visiting the neighbors at all. And GNU Go plays moves reversibly: every board mutation is pushed onto a change stack (its comments report 20–30 entries per typical move) so the classical engine can read out a line and take it all back on a single board — whereas the playout engines, FoolGo included, never undo anything: they copy the board and let the copy die with the game.

The wall, the tax, and no locks at all

Parallel search reads as generations of one lineage — though not a chronological one. Fuego, the strong open MCTS engine of FoolGo's own era, had already gone further than everyone: a fully lock-free multithreaded tree search (Enzenberger & Müller, 2009) — three years before FoolGo's global mutex. Its source rewards reading even now: each thread allocates nodes from its own pre-allocated array and links them to the parent only once fully initialized; if several threads expand the same node, the last writer wins and the others' work — including value updates already made — is knowingly thrown away. Correctness traded against ever waiting. Every node field is volatile, virtual loss is already there (m_virtualLossCount), and the in-code docs cite the exact chapters of the Intel manual whose memory-ordering guarantees the whole scheme leans on. The fool was not early; he was simple. Within the lineage of the simple: FoolGo's forbid-peers rule (2012) is the blunt ancestor, Leela Zero (2017) does it properly with textbook virtual_loss() / virtual_loss_undo() folded into node evaluations, and KataGo is the industrial endpoint — virtual loss as a tunable (numVirtualLossesPerThread, an atomic counter per node), over a sharded node table with a mutex pool and fully atomic stats structs.

From tree to graph

The part that surprised me most. Leela Zero, for all its strength, uses a literal pointer tree and does not merge transpositions; there's even a comment in uct_select_child about counting parent visits manually "to avoid issues with transpositions." But in v1.11.0 (March 2022), KataGo shipped what its release notes call "a new stronger MCTS implementation that operates on a graph rather than a tree" — transposed move orders recombined into shared nodes, keyed by hash in a sharded node table. Which is, architecturally, what FoolGo's unordered_map<HashKey, NodeRecord> was doing in 2012.

Before I take a bow: KataGo's author also wrote a first-principles document explaining that naively applying tree-MCTS statistics to a DAG — exactly what FoolGo does — is unsound: shared nodes break the running-statistics formulation in subtle ways, and doing it correctly (plus handling ko and superko) is the actual hard part. So no, my hobby engine did not do graph search before KataGo. It wandered into the right building ten years early, without knowing why the floor needed reinforcing. KataGo's contribution was the reinforcement.

What it adds up to — and where it stops

Flat arrays, bitwise liberty tracking, incremental hashing, a pointer-free "tree," and threads that stay out of each other's way: 40,000 games per second on a laptop from 2014.

And yet: beginner strength. That plateau is the honest lesson of the repo. Uniformly random playouts are a terrible evaluation function, and no amount of throughput fixes their bias — stronger engines of that era spent their effort on playout policy, and then 2016 arrived and neural networks replaced blind rollouts with intuition. AlphaGo kept the tree search; it swapped out exactly the part FoolGo had made fast.

The repo is github.com/chncwang/FoolGo — readable on purpose, PRs welcome, and still, I'd argue, one of the clearer ways to see what game-tree search looks like with the covers off.

These days I build ClinTrialFinder, an AI-powered clinical-trial matcher, and write about building it at chncwang.substack.com.

Claude Code can make videos: it records the app, narrates with ElevenLabs, and syncs audio to video automatically

Chauncey Wang — Sat, 15 Aug 2026 03:40:08 +0000

I'm a solo builder. I needed a 2-minute product demo for ClinTrialFinder — a free tool I built that matches cancer patients to clinical trials. I can fumble through OBS and iMovie, but I'm not proficient — and Claude Code does it faster.

So I asked Claude Code — an agentic coding tool — to make it. And it did: a narrated walkthrough where the voiceover lands exactly on the on-screen action. I never opened a screen recorder. I never opened a video editor. I never manually lined up a single caption to a single frame.

Here's the video it produced. This post is about the three things the agent did to make it — because I think that combination is new.

1. It recorded the app — no screen recording

Instead of me screen-capturing a session by hand, the agent wrote a Playwright script that drives the real, live web app: it opens the site, fills out the 10-step patient wizard with a synthetic case, submits, and records the finished results page — all headless, straight to video.

That means no manual take, no re-shooting when I fumble a click, no "oops the mouse jittered." The recording is code, so it's deterministic and repeatable. When the product changes, the agent re-runs the script and out comes a fresh clip. It even injected a fake cursor that glides between elements, because a headless recording has no real mouse pointer.

2. It generated the narration — no microphone

I didn't record a voiceover. The agent wrote the narration script, then called the ElevenLabs text-to-speech API to synthesize it in a clean, consistent voice. If I want to change a line, it edits the text and regenerates that clip in seconds — no re-recording, no "let me find a quiet room," no matching my tone across takes.

// the agent calls ElevenLabs per narration phrase
const res = await fetch(`https://api.elevenlabs.io/v1/text-to-speech/${VOICE}`, {
  method: 'POST',
  headers: { 'xi-api-key': KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ text, model_id: 'eleven_multilingual_v2' }),
});

3. It aligned audio to video — no timeline editor

This is the part that normally needs a human in a video editor, dragging clips around a timeline until the words match the picture. The agent did it automatically, and this is the genuinely clever bit:

While recording, it logs the timestamp of every key on-screen moment — the submit click, the results appearing, a trial opening, the "copy to AI" dropdown.

const beat = name => console.log(`BEAT ${name} @ ${elapsed()}s`);
// BEAT submit-click   @ 46.83s
// BEAT results-shown  @ 68.73s
// BEAT trial-open     @ 90.17s

Then it cuts the narration into phrases, one per beat, and places each phrase at its beat's timestamp in the final mix (ffmpeg's adelay). The result: when the voice says "now it goes to work," the button is being clicked; when it says "open any trial," the trial is opening. The sync falls out of the recording itself — no dragging, no eyeballing, no manual alignment.

Why this matters

Making a product demo used to mean: screen-record a take, write a script, record a voiceover, then sit in an editor syncing them. Four manual steps, each needing a skill (or a person).

Here it was one conversation with an agent. The whole pipeline is code — record → narrate → align → assemble — so it's:

Repeatable: product changes? Re-run. Fresh, re-synced video.
Deterministic: same framing and pacing every time, no shaky live take.
Faster than me: I can muddle through OBS and iMovie, but slowly and not well — the agent does it faster, and I don't have to.

The agent also quietly handled the fiddly parts I'd never want to — a site that won't render headless (screenshot + Ken Burns instead), audio mixing that silently halves volume, a blank loading frame that throws off the timing. I didn't debug any of it; it did.

The shift, for me, is that making a demo video is now something you ask for, not something you produce. The example here is my own project — ClinTrialFinder, a free clinical-trial matching tool for cancer patients — but nothing about the approach is specific to it. If you have a web app and an agent, you can have a narrated, synced demo without touching a recorder or an editor.

Building a One-Person Software Shop with Claude Code

Chauncey Wang — Thu, 06 Aug 2026 11:30:07 +0000

I build a clinical-trial matching product alone — no cofounder, no team. Just one person, an AI coding agent, and a set of conventions that keep "vibes-based solo dev" from falling apart across weeks of parallel work.

The first version was a command-line tool, open-sourced. Turning it into a real web app — something a patient could open in a browser and trust with their situation — is the jump where a lot of solo projects quietly stall. I made it: today it's a live web app with ~30 drug pages, dozens of disease-specific trial landscapes, and a matcher real cancer patients use to find trials.

I'm also a cancer patient; I built this partly because I needed it to exist. So I care less about it being impressive than correct — a wrong trial match wastes a sick person's time. That constraint is the whole point: the interesting part isn't that an AI writes my code — it's the scaffolding that makes its work trustworthy when I'm not watching every keystroke.

A note on the tool first, then the transferable patterns — most of them scar tissue from something that broke once. Everything's sanitized — fake IPs, generic paths, invented tasks; the real secrets stay home. And the fake IPs aren't only for the article: the real task files never held a raw IP or email, and the server logs that hold IP addresses are purged within 14 days — matching the privacy policy.

Why Claude Code, specifically

People ask why Claude Code and not one of the other coding agents. Two reasons — one soft, one hard.

The soft one: it infers intent from less. I can hand it a terse, half-specified ask — "the ranking's off for first-line patients, dig into it" — and it usually fills the gaps the way I meant, not the way I literally typed. That matters when I'm running several sessions and can't write a full spec for each. Subjective, not a benchmark — but it's what keeps me reaching for it.

The hard one: my review workflow feeds real patient-submission data to the agent — I pull a patient's result set to check whether the matcher did right by them. ClinTrialFinder's privacy policy names Anthropic's Claude as a tool for exactly that — "quality-checking match results, diagnosing issues." Using Claude Code for the review keeps the implementation matched to what patients were told. Other disclosed vendors handle other steps; the point isn't that Claude is the only option — it's that the words I show patients and the tools I run stay in lockstep.

The core bet: your task tracker is a git repo

Most people reach for Jira, Linear, Notion. I keep every task as a plain file in a git repo of its own:

project-manager/            # a git repo
  tasks/
    412-fix-ranking-edge-case.html
    413-wizard-validation.html
    414-review-user-submission.html

One file per task, fixed shape — priority, status, the problem, the fix, verification plan, links to related tasks. No API, no board, no login. Just files in git — 500+ of them now, and the flat directory has never needed anything fancier.

Why this beats a tracker for an AI-assisted solo shop specifically:

Version-controlled. The backlog is plain files in git — every status flip and edit is a diff you can read, branch, or revert, exactly like source. It's a history you own and grep, not rows in someone else's database.
Queryable with the tools the agent already has. "Next free task number?" is ls | sort. "Which tasks touch the ranking bug?" is grep -rl. No integration — just grep.
Linkable and self-documenting. Tasks cross-link; six weeks later the why is one click away, written at the time, not reconstructed from memory.

The insight: when your teammate is an AI agent, your project management should be a git repo of plain files it can grep — not a SaaS it has to poke through an API. (I use HTML for the files — renders and links nicely — but the format is the least interesting part; Markdown would do.)

One file sits on top of that flat directory: a single overview — a hand-maintained index that splits the backlog into the full list and the sprint (what to actually work on now). The task files are the atomic units; the overview is the priority view.

And two kinds of judgment get their own role. Worker sessions append tasks freely as they surface — a bug found mid-fix, a spinoff from a review — but none of them promotes itself into the sprint. That call belongs to a dedicated "CEO" session: a Claude Code session that reads the backlog, decides what's worth doing now (via its own update-active-sprint skill), and proposes the forward-looking work the workers won't file on their own — new features, UI refinements, the product's next move. Reactive filing is mechanical and belongs to whoever hit the problem; setting direction — both prioritizing and proposing — is judgment, so I concentrate it in one named role instead of smearing it across four sessions that each think their task is the important one.

Parallelism — four sessions, each a standing role

Here's where it gets honest. I often run four Claude Code sessions at once, against a shared backlog and shared repos — but they're not four workers chewing through the same queue. Each holds a standing role: a CEO that prioritizes and proposes new work, an SEO/content session that also watches the traffic and files a review task whenever a patient submits, and two full-stack engineers working different tasks in parallel. And full-stack undersells it — one engineer session will write HTML and CSS, write the Python behind it, review a real patient submission and file the fix tasks its defects reveal, and rewrite a matching prompt, all in one afternoon; a single context spans what used to be four specialties.

That engineer session also writes as it works — logging its findings and progress back onto the task file, so the task becomes a running record of what was tried and learned, not a write-once spec. That record earns its keep: when a mid-work diagnostic disproves the task's own premise — the "bug" was correct behavior, the evidence was confounded — the CEO reads the update and demotes the task back to the backlog instead of shipping it. The sprint self-corrects.

And these sessions don't close when a task is done — each stays open and picks up the next thing in its lane, so it accumulates context instead of starting cold each time. A big multiplier for one person — the nearest thing to a team I've got.

They all run from the same home directory — one shared filesystem, not four sandboxes. That's mostly the point: the SEO session opens the analytics export I just downloaded to ~/Downloads, any session can reach any repo in the tree, and nobody has to shuttle files between isolated boxes.

The one place that sharing bites is the two engineers — point both at the same working tree and they'll clobber each other, one's half-finished edit sitting there when the other runs its tests. So each works in its own git worktree: a separate checkout on its own branch, sharing the repo's history but not its uncommitted state. Shared filesystem, isolated working copies — both build, commit, and test at once without ever seeing each other's in-progress files, and each branch merges to main only after I've reviewed it.

Those roles don't act in a vacuum — here's the full lifecycle they move a task through, for both kinds of task the shop runs.

Of those 500-plus task files, about 90 were spawned by reviewing real patient submissions — the rest are features and fixes the CEO session or I dreamed up. That ratio is the part I care about: every genuine submission gets audited, and the ones that expose a gap become fix tasks. Roughly 230 of the whole are done or shipped; the rest are a living backlog. The traffic isn't huge — a few hundred submissions over the tool's life, at least 100 real enough to enter an email to get their results back.

Every change gets its own URL before it's real

The counterpart to building in parallel: every change to the product needs somewhere to run that isn't production and isn't the other tasks in flight. So every task that touches the product gets its own isolated instance — a fresh clone of the repo, its own service on its own port, reachable at its own private review URL behind a reverse proxy.

Under the hood it's one small nginx config: a location block per instance, each routing a private sub-path to that instance's local port (/task-<name>/ → a service on 127.0.0.1:<port>). Spinning one up is a clone, a service on a fresh port, and a few lines of proxy. The honest ceiling is memory — each instance is a full running copy of the app, so the dev box has to hold several at once; that, more than anything, caps how many tasks I can keep live for review at the same time.

At any moment I might have several live, independently-viewable copies of the product up — one per task — each showing exactly that task's changes and nothing else. I open the URL, click through the actual rendered thing, and see the change in situ before it's anywhere near a user.

That's the deploy gate: nothing reaches production until I've looked at it running on its own instance. Build on an isolated branch → spin up an instance → review the real rendered page at its URL → approve → merge → deploy. The agent never pushes to prod on its own — the "approve" is mine, and it's a look at a running thing, not a diff.

The transferable pattern: give every unit of parallel work its own running, reviewable instance. "Does it actually work, rendered, in isolation?" is a question you can only answer if the work has somewhere to live that isn't production and isn't your other tasks. The isolation is what makes parallel and careful compatible.

Skills that encode judgment, not macros

Claude Code lets you define skills — named routines the agent runs on command. The naive use is automation: "deploy the site," "run the tests." Useful, but shallow.

The valuable skills encode how a domain expert thinks — the judgment, not just the steps.

My highest-value one reviews a user submission. It doesn't just dump data. It:

Pulls the result across three pools (shown to the user / computed-but-hidden / rejected).
Reconstructs what the user actually did from the logs — did they wait, did they click through, did they leave.
Checks whether a genuinely-good result got silently dropped before the scoring stage even saw it (a whole class of bug that's invisible if you only look at what was shown).
Cross-references anything it finds against a catalog of known past defects.

That's not a macro. That's a reviewer's worldview — what to suspect, what to verify, what caveat to attach to a claim — written down once and rerun consistently. When I invoke it, I'm not saving keystrokes; I'm borrowing a disciplined second brain that never gets lazy on step 3.

The transferable pattern: your best skills should capture the reasoning of your most careful self, especially the checks you'd skip when you're tired. Automation saves time. Encoded judgment saves you from your own shortcuts.

The operating manual: where corrections become rules

There's a file Claude Code reads at the start of every session — CLAUDE.md. Mine has grown into an operating manual: the project's standing rules, accumulated one mistake at a time.

Deployment discipline. Never deploy to production without explicit sign-off. Never edit files directly on the server — always local, commit, push, pull.
Expected behaviors. How to format a task, when to sync which repo, what "done" means.

Every one of those started as a bug. The first time the agent restarted prod and interrupted a live request, the fix wasn't "don't do that this time" — it was a line in the manual so it never happens again.

That's the load-bearing pattern: a correction that lives only in a chat window evaporates; a correction written to a file that loads next session is a permanent behavior change. The manual is the accumulated scar tissue of the project — the difference between an agent that repeats your mistakes and one that compounds your lessons. The test of a good rule is simple: can the mistake it came from happen again?

What actually transfers

Strip away my specifics and here's what I'd hand another solo builder working with an AI agent:

Make your project management out of primitives your agent is fluent in. Files, grep, git — not a SaaS behind an API. The backlog should be as greppable as the code. Let worker sessions append to it freely, but concentrate direction-setting — both prioritizing and proposing new work — into one role, a dedicated "CEO" session, instead of every session promoting its own.
Run parallel sessions as standing roles, not a shared queue. Give each a lane and let them share one filesystem so they see the same world — then isolate what would collide (a git worktree per engineer) so "more hands" never becomes clobbered work.
Give every change somewhere to run before production. Isolated per-task instances behind a reverse proxy let you review the real rendered product — so "approve" is a look at a running thing, not a diff, and prod stays a deliberate step.
Write skills that encode judgment, not just steps. Capture the careful reasoning you'd skip when tired. That's the compounding asset; automation is just the floor.
Keep an operating manual, and treat every correction as a candidate rule — written to a file that loads next session, not left in a chat window that evaporates. The manual is your project's scar tissue; the test of a rule is whether the mistake it came from can happen again.

None of this is about the AI being the smartest. It's about building the scaffolding that makes an AI agent's work trustworthy — which, when the output affects a sick person looking for a trial, is the only thing that matters.

I build ClinTrialFinder solo, with Claude Code, as a patient myself. If any of these patterns are useful in your own shop, I'd genuinely like to hear how they hold up — the failure modes especially.