Run Parallel AI Coding Sessions Across GitHub Repos with Markdown
I run nine GitHub repos as one programme of work. Every project keeps its backlog as plain markdown inside its own repo, one Claude Code or ChatGPT Codex session works each project in parallel, and a single board in VS Code shows all of them moving at once. There is no project tool, no API and no sync job in the middle: the markdown file is the shared state that both I and the agents read and write. Step-by-step: 1. Put the backlog in the repo, as markdown. Every project gets `docstech/users/<me>/todo.md` and `done.md`. A story is a `###` heading. Structured fields ride in an empty markdown link at the end of it: `### Add rate limiting [](?status=doing&epic=api&time_estimated=180)`. GitHub renders an empty link as nothing, so the file still reads as prose in a pull request while carrying real metadata. 2. Write the story before the session starts. Each one has goal, background, scope, out of scope, the files it should touch, a checkbox task list, and acceptance criteria. That story is the prompt, and most of my thinking happens there rather than in chat. It decides whether the session comes back with anything shippable. 3. Open the parent folder in one window, and turn the files into a board. I open the parent folder holding all the projects and open any `todo.md` with NoteThink in Folder mode, which merges every markdown file under it into one view. Group the lanes by project and it is the programme view, one lane per repo. Group them by status and it is the delivery view, one Kanban across the whole portfolio. Each card carries a pill naming the project it came from, and clicking it opens that file at that story. 4. Start one Claude Code session per project. Every session opens with the same instruction: read `todo.md` top to bottom and take the top story. The sessions never talk to each other, because the file on disk is the only shared state. A session that dies costs nothing. 5. Let the board report progress instead of reading the sessions. Agents edit the markdown as they work: tick a task, flip `status=todo` to `status=doing`, move a finished story to `done.md`. The board watches the files, so cards animate into their new column as each change lands, and I can see which sessions are advancing without reading any of them. 6. Steer by dragging. Dragging a card between lanes writes the attribute back into the source markdown, so dropping one in "doing" makes the file say `status=doing` and the next agent turn reads it. Ticking a checkbox does the same. The board is the steering wheel and the file is the wire. 7. Close every story the same way. One slash command runs lint plus the full test suite, checks the story's tasks are ticked, and drafts the commit message; another ships to staging then production. The finished story moves to the end of `done.md`. Over time `done.md` becomes the programme record: what shipped, when, and what it cost. Try the board without installing anything. Here is a live example board, four projects merged into one view, and it is exactly what the screenshot shows: https://www.notegit.com/en/app/notegit.com/notegit/example_repo/blob/ai-board/board.md Results, honestly. Nine repos, about 260 open stories and about 1,400 completed ones, all in markdown inside the repos rather than a tracker. The backlog goes back to March 2024; the parallel sessions on top of it are the last four months. I run eight to twelve sessions at the same time, and the whole thing fits inside one Claude Max 20x subscription over a month of full-time work. Not all of it is code. The same parallel-session habit drives a nuclear reactor design study (https://github.com/cleverlight/mistergy) and several video and design projects. The board part fits best where the work already lives as files in a repo. Limits, honestly. The ceiling is my review capacity, not compute. Eight to twelve is where I sit; past that I stop reading output properly and start rubber-stamping, which is worse than running fewer. It only works when stories are genuinely independent, because two sessions in one file is a merge conflict you wrote yourself. Agents occasionally finish work and forget to move the story, so `done.md` needs a sanity check. And it assumes you will write the story properly first, which is real work that AI does not do for you. The screenshot is the public example board rather than my own, because my real one carries client project names. Disclosure: I build NoteThink, the free, open-source VS Code extension in step 3, and NoteGit, which hosts the example board. NoteThink is on the VS Code Marketplace, Apache-2.0, and genuinely early (v0.3.38, preview quality, a handful of installs). The workflow is tool-agnostic and the markdown is just markdown: any viewer will show it, and you can run the whole thing with no extension. NoteThink is what makes the cross-project board and the drag-writes-back-to-file part work.
0 comments