Bot Crossing: a colony map for every coding-agent thread on your machine

The problem Bot Crossing solves for people running several agent threads

A coding agent that stops to ask a question looks the same as one that is still working, as long as you are looking at a terminal tab you are not currently reading. Run four or five threads across two harnesses and the question of which one is blocked on you becomes a manual sweep. Bot Crossing's answer is spatial: each session becomes an astronaut standing on a hex plot, and the state of the thread is the posture of the figure. A thread that needs input stops and holds a question mark above its head; clicking it opens the thread back in whichever harness it came from. The audience is narrow and specific. It is one developer on one machine, running Claude Code, Codex or Cursor, who wants to see the shape of their work rather than read a list. It is not a team dashboard and not a hosted service. The README is explicit that it reads the harness's own files on your own machine, that nothing is uploaded, that there is no account, and that it never writes to a harness at all. The only file it writes anywhere is `data/colony.json`, where the map lives.

How the colony maps to your threads, and why the layout is sticky

The mapping is one-to-one and documented as a table. One hex zone is one repo; one astronaut plus one building is one session. How finished a building looks tracks the size of its transcript on a log scale, and scaffolding appears at a site when somebody is working there right now. A thread that just appeared is an astronaut walking out of the ship; a thread you archived is one walking back in. Repo size drives plot count: a bigger repo claims more tiles, one per seven threads, grown as a contiguous blob from the middle outward. The design decision worth noting is that the layout is sticky rather than recomputed. The previous arrangement is an input to the next one. A repo that still needs the same number of tiles keeps exactly the tiles it had, one that grew keeps them and claims neighbours, and one that shrank gives back whatever it claimed most recently, so growing and shrinking again returns a zone to precisely its starting shape. Only a repo that has never been placed is placed at all, and it takes the innermost tiles still free. A zone's origin is its root tile, not the centre of the tiles it currently holds, so gaining a tile does not drag the buildings, crew and name sideways. The README contrasts this with the previous version, where the arrangement was a pure function of thread counts and a session appearing anywhere could change the sort order, the tiles, and the whole colony layout, so a zone you were watching could jump to the far side of the map because a different repo gained a thread. That is a real usability argument, and the persistence to `data/colony.json` is what makes it hold across a reload, including for a repo whose last thread you archived.

Astronaut states use strict precedence, so a thread only ever does one thing

The state model is not a set of independent flags. It is a strict precedence list where the first match wins, which means an errored thread that is also unread shows as errored rather than as waiting on you. The order documented in the README is: errored first (the astronaut slumps, eyes red, fault light stutters), then running now (hammers at its building, sparks fly), then PR merged (jumps, confetti, heart eyes), then unread (stops and waits on you), then nothing for three days (sits down and sleeps). This is a design choice with a cost. If a thread has failed and is also waiting for your input, the map tells you about the failure and not the wait, so the unread marker you were relying on to triage your attention is suppressed by the error. The precedence order is defensible, since a broken thread is the more urgent fact, but it is worth knowing before you treat the unread state as a complete queue of what needs you. The rest of the rendering is geometry with consequences. Terrain inside the colony runs from about -0.3 to +0.24 on the Moon and half again as far on Mars, and a deck's top face has to sit above the roughest ground any plot can be dealt or the ground comes through it: the slab reads as sunken, props are buried to the waist, and the seams tear. So the slab is 0.45 tall and everything on a plot, buildings, kerbs, clutter and boots, is measured from that one number. Ground scatter is rebuilt whenever a zone's footprint changes, because the world is built before the first roster arrives and there are no plots to miss at that moment; without the rebuild, boulders and trees end up under decks laid afterwards and poke through in fragments.

Installing Bot Crossing and watching your first thread appear

The README gives one command pair for the whole thing. Node 22.13 or newer is required, and `package.json` sets the same floor in its `engines` field, so check your version first.

node --version
npm install && npm run dev

The second line installs dependencies and starts the Vite dev server. There is no second process to start: the README states that `npm run dev` is the whole thing and that the API lives inside the Vite dev server. It binds to `127.0.0.1` by default and answers only its own page. Open that address and the colony renders; any harness that is installed shows up at once, because the colony is the union of all of them and each astronaut carries the name of the harness it belongs to. For a built version there are two other scripts, `npm start` for build and serve, or `npm run serve` if `dist/` already exists.

npm test

The README states that `npm test` runs the suite, which is the quickest way to confirm the scanning half works on your machine before you trust the map. If you want to add support for a harness that is not covered, the README says it takes one new file in `server/harnesses/` and one line in its `index.mjs`, with the interface written down in `server/harnesses/README.md`. It also asks that a pull request mention any edit to the scanner or anything under `src/`, on the grounds that it signals the seam needs widening rather than a workaround.

Where Bot Crossing stops being the right tool

Harness coverage is the hard limit. The README marks Claude Code, Codex and Cursor as supported and lists OpenCode, Antigravity CLI, Amp, Aider, Goose, Qwen Code and Amazon Q Developer CLI as not yet. If your threads live in any of those, the colony will be empty or partial, and the fix is writing an adapter rather than configuring something. Cursor support is itself partial: the README says agent transcripts are read, but the composer and sidebar threads are not read yet, so a Cursor user should expect a subset of their sessions to appear. The maintenance posture is the second limit, and the README is unusually direct about it. It says the project is published as-is, that the author built it for himself and cannot promise to maintain it, that issues and PRs are welcome but may go unanswered, and that forking is an entirely reasonable thing to do, with CONTRIBUTING.md setting out what to expect. The last push to the repository was on 2026-09-09, so the code is recent, but recency of the last push is not a maintenance commitment and the README does not offer one. There are no retrieved releases, so there is no changelog to read for upgrade guidance. The third limit is scope. This is a single-machine tool with no account and no upload, which is a privacy property and also means there is nothing to share with a teammate, no history beyond what `data/colony.json` holds, and no remote view of a colleague's agents.

Bot Crossing compared with reading your harness session files directly

The obvious alternative is not another colony sim but the files themselves. Claude Code, Codex and Cursor each keep local session records, and those records are the source Bot Crossing reads through its adapters. Reading them directly with `jq`, `grep` or a short script gives you exact fields, full transcripts and no rendering layer, and it works for any harness whose format you are willing to parse. What it does not give you is the state summary. Bot Crossing's contribution is the reduction of each session to one of five states and the placement of those states on a map you can learn, with the sticky layout making the position itself a memory aid. The trade is fidelity for glanceability. A script tells you precisely what a session contains; the colony tells you which of your threads is stuck, at the cost of a precedence rule that can hide a wait behind an error and a rendering pipeline that only knows three harnesses. If you already have a terminal workflow that surfaces blocked threads, Bot Crossing adds a second view rather than replacing the first.

Licence, upgrade cost and what the MIT terms leave you

Bot Crossing is MIT licensed, with `package.json` declaring `"license": "MIT"` and a LICENSE file at the repository root. In practical terms that permits use, modification and redistribution with the licence and copyright notice retained, but this is a description of the licence identifier and not legal advice; read the LICENSE file for the actual terms. Dependencies are `@mdi/js` and `three` at runtime, with `@gltf-transform/core`, `@gltf-transform/functions` and `vite` as dev dependencies, all under permissive licences as far as the manifest shows, though each dependency carries its own terms. The upgrade cost is shaped by the missing release history: with no retrieved releases, there is no versioned changelog to consult, so an upgrade means tracking commits on `main`. The `engines` field pins the floor at Node 22.13 and the `os` field lists darwin, win32 and linux, so the supported surface is stated in the manifest rather than discovered at runtime. Because the README says it never writes to a harness and writes only `data/colony.json`, the blast radius of an upgrade that goes wrong is your colony layout, which the sticky algorithm rebuilds from the thread counts on the next run. Deep links are the one place the tool reaches outside its own process: opening a thread, revealing a folder and starting a new session go through a `harness://` scheme handed to the OS opener, `open(1)` on macOS, `xdg-open` on Linux, ShellExecute on Windows. On Linux, where a desktop app is often not installed, the scheme is checked first and a terminal running the harness's own CLI opens instead when nothing answers it.

Editorial conclusion

Adopt Bot Crossing if you run Claude Code, Codex or Cursor on one machine and want a spatial read on which threads are waiting on you, rather than a list in a terminal. Skip it if your agents live in OpenCode, Aider, Goose, Amp, Qwen Code or Amazon Q Developer CLI, since the README marks all of those as not yet supported, or if you need a tool with a maintenance commitment: the README says it is published as-is and that issues and PRs may go unanswered. Before installing, confirm Node 22.13 or newer with node --version, and check whether your harness keeps its sessions where the adapter expects, because the README points to server/harnesses/README.md for that detail rather than listing the paths itself.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. Station-Sciences/bot-crossing on GitHub