Bot Crossing: a local map of your agent threads, one astronaut per session
A video game for AI agents. Created by Jarren Rocks
At a glance
- What is it?
- Bot Crossing reads the session files that Claude Code, Codex and Cursor already keep on your machine and renders each thread as an astronaut on a hex colony. It is a single-user, read-only visualiser with a small adapter seam and an honest no-maintenance promise.
- Who is it for?
- Adopt Bot Crossing if you run Claude Code, Codex or Cursor locally and want to see which thread is waiting on you without opening each harness in turn; the read-only design and the single written file, data/colony.json, keep the blast radius small.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is thread sprawl, not agent capability
If you run more than one coding agent, the sessions accumulate faster than you close them. Claude Code keeps its own transcripts, Codex keeps its own, Cursor keeps its own, and nothing gives you a single place to see that one of them stopped three hours ago with a question. Bot Crossing takes the position that the answer is already on disk and only needs a view. It scans each harness's local session files and turns every thread into a small astronaut standing on a hex plot. When a thread needs a human, the astronaut stops and holds a question mark over its head; clicking it hands the thread back to the harness it came from. The audience is narrow by design: one person, on one machine, running several harnesses at once. There is no account, nothing is uploaded, and the README states the tool never writes to a harness at all. The only file it writes anywhere is data/colony.json, which holds the map.
How the colony is built: adapters, precedence and a sticky layout
A harness, in this project's vocabulary, is whatever actually runs your threads. Each supported harness gets one adapter file under server/harnesses/, registered with a single line in that directory's index.mjs. The adapter reads the harness's own session files and returns a thread shape; the scanner does not need to know anything else about the harness. That seam is the whole architecture, and the README is explicit that adding a harness should mean one new file and one line, nothing more. Astronaut behaviour is a strict precedence rather than a set of independent flags, so a thread can only ever be doing one thing. First match wins: an errored thread slumps with red eyes and a stuttering fault light and carries a ! badge; a running thread hammers at its building with sparks and carries the hammer badge; a merged PR produces a jump, confetti and heart eyes with a check badge; an unread thread stops and waits on you with a question mark; a thread with nothing for three days sits down and sleeps. The map itself is deliberately sticky. The previous arrangement is an input to the next one, so a repo that still needs the same number of tiles keeps exactly the tiles it had, one that grew claims neighbours, and one that shrank gives back whatever it claimed most recently. A zone's origin is its root tile rather than the centre of its current tiles, so gaining a tile does not drag the buildings, the crew and the name sideways. The README explains the motivation directly: the earlier version was a pure function of thread counts, so one session appearing anywhere changed the sort order, and a zone you were watching could jump to the far side of the map because a different repo gained a thread.
Getting it running: two commands and a Node floor
The documented path is short. npm install && npm run dev is described as the whole thing, because the API lives inside the Vite dev server rather than in a second process. Node 22.13 or newer is required, and npm test runs the suite. For a built version, npm start performs a build and serves it, while npm run serve skips the build when dist/ already exists. The server binds to 127.0.0.1 by default and, per the README, answers only its own page. Opening a thread, revealing a folder and starting a new session all go through a harness:// deep link handed to the OS opener: open(1) on macOS, xdg-open on Linux, ShellExecute on Windows. On Linux, where a desktop app often is not installed, the scheme is checked first and a terminal running the harness's own CLI opens instead when nothing answers it. The one configuration-shaped thing worth knowing before you install is where your harness keeps its sessions; server/harnesses/README.md is where the project documents the thread shape, the ground rules and how to find that location for a given harness.
The write surface is one file, and the read surface is everything
The security posture is the most interesting design decision here, and it is stated plainly: it reads the harness's own files, on your own machine, nothing is uploaded, there is no account, and it never writes to a harness at all. data/colony.json is the only file it writes anywhere. That inverts the usual trust conversation. The risk is not that the tool corrupts a transcript; the README says it cannot, because it does not write to one. The risk is that a local process is parsing session files from three different vendors, and those files contain whatever you typed into your agents. Binding to 127.0.0.1 and answering only its own page limits exposure to other machines, but it does not limit what the process can see. If your transcripts contain secrets, the colony view inherits them. The README does not claim otherwise, and it does not describe a redaction layer.
Where it stops: three supported harnesses and a maintenance warning
Three harnesses are marked supported: Claude Code, including worktrees and live-process detection; Codex, covering desktop, VS Code and CLI sessions opened through codex://; and Cursor, for agent transcripts only, with composer and sidebar threads explicitly not read yet. Everything else in the table is marked not yet, including OpenCode, Antigravity CLI, Amp, Aider, Goose, Qwen Code and Amazon Q Developer CLI. That is a coverage limitation, not a bug, and the README frames it as a matter of somebody writing the adapter. The sharper limitation is maintenance. The status line says the project is published as-is, built for the author, with no promise to maintain it; issues and PRs are welcome but may go unanswered, and forking is called an entirely reasonable thing to do. CONTRIBUTING.md is described as setting out what to expect. There are no retrieved releases, so there is no changelog to read for upgrade guidance. Anyone treating this as infrastructure should read that status line as the primary constraint, not as boilerplate.
The Cursor gap is a real trade-off, not an oversight
Cursor is listed as supported, but the qualifier matters: agent transcripts are read, composer and sidebar threads are not yet. For a Cursor user, that splits the colony in two. The threads that appear are the ones Cursor writes as agent transcripts; the ones that do not appear are the ones you may actually be living in. The README does not explain why the split exists, only that it does. My reading is that the adapter reads a file format that is available and stable, and leaves the rest for later. That is a defensible line for a single-author tool, but it means the union-of-all-harnesses promise comes with an asterisk per harness. If your work is mostly in composer threads, Bot Crossing will show you a colony that is missing most of your work, and no amount of clicking will fix it.
What a harness adapter actually costs you
The alternative to Bot Crossing is not another colony visualiser; it is reading each harness's own session list, or writing a scanner yourself. The difference in approach is the adapter seam. A hand-rolled scanner tends to grow a special case per harness inside one file, and every new harness touches the same code path. Bot Crossing pushes that into one file per harness under server/harnesses/ behind a documented interface, which is why the README can claim that adding a harness is one file and one line. The trade-off is that the interface has to be general enough for formats the author has not seen. The README anticipates exactly this: if landing a new adapter means editing the scanner or anything under src/, the author asks you to mention it, because it means the seam needs widening and fixing that is preferred over a workaround. That is the honest version of an extensibility claim, and it is also a warning that the current interface may not fit the harness you care about.
Licence, upgrades and who should install this
The repository is MIT licensed, which permits forking, modification and redistribution under the terms of that licence; consult the LICENSE file and your own counsel for anything beyond that, since this is not legal advice. Upgrades are the weak point. With no retrieved releases and a stated no-maintenance posture, there is no version cadence to plan around. The practical upgrade path is to watch the main branch, run npm test after pulling, and be prepared to fork if a change you need stalls. On the rendering side, the README documents a constraint that will bite anyone editing the world: terrain inside the colony runs from about -0.3 to +0.24 on the Moon and half again as far on Mars, so the deck slab is 0.45 tall and everything on a plot is measured from that one number rather than a height of its own. Ground scatter is rebuilt whenever a zone's footprint changes, because the world is built before the first roster arrives and at that moment there are no plots to avoid. These are the details a fork inherits. Adopt it if you run Claude Code, Codex or Cursor locally and want a single view of which thread is waiting; skip it if your harness is on the not-yet list or you need a dependency with a support commitment.
Editorial conclusion
Adopt Bot Crossing if you run Claude Code, Codex or Cursor locally and want to see which thread is waiting on you without opening each harness in turn; the read-only design and the single written file, data/colony.json, keep the blast radius small. Skip it if you need OpenCode, Amp, Aider, Goose, Qwen Code or Amazon Q Developer support today, or if you require a maintained dependency: the README says it is published as-is, issues and PRs may go unanswered, and forking is described as reasonable. Before installing, verify that your Node version is at least 22.13, that the harness you care about writes its sessions where the adapter expects them, and that server/harnesses/README.md documents an interface you are willing to implement yourself if your harness is missing.
Community notes