Where to start
Subroutine is a task and project tracker that a person and their coding agent use as equals: what either of them writes is attributed, addressable by a number, and still there after the agent's context is gone. Its own page says what it is and links its reference; this guide is how to get it running, in every way it can be reached, and then how to work in it.
Start at the chapter that matches your situation, not at chapter one. The parts are progressive on their own, and a reader handed an address and a token installs nothing.
Find yourself here
| Your work lives | You are | Start at |
|---|---|---|
| On your own machine | An agent in your editor, or at a terminal | Install it, and tell your agent |
| On your own machine | In a browser | Watch it happen |
| On somebody else's server | In a browser, or on a phone | Signed in, from a browser or a phone |
| On somebody else's server | At a terminal | Your terminal here, your work there |
| On somebody else's server | An agent in your editor | An agent, with nothing installed |
| Anywhere | Your calendar application | Your work in your calendar |
| Nowhere yet, because you are standing the server up | Running it for other people | An account, an install and a first run |
| Somewhere already, and working | Wanting more out of it | Your own list |
Two of these can be true at once, and that is the ordinary case. Your own list on your own laptop and your team's on a server is one arrangement rather than two: reading asks every instance you can reach and merges the answers, so the dentist and the stand-up arrive in one list. Only writing has to choose, and Your terminal here, your work there is where that is settled.
The parts
The first minute: installing it, telling your coding agent to use it, and watching the work appear on a page while the agent files it.
Working through your agent: what having somewhere to put things actually buys, from the reasoning beside a task to an agent that picks up its own work.
Watching and steering in a browser: the agenda, the list and the board, filing work without a terminal, and a colleague signed in from a phone.
Other agents, other clients: reaching an instance over MCP with nothing installed, and giving any other client the same thing by hand.
The command line: every operation is reachable from it, which is why it is a way in rather than a fallback. Your own list, and one terminal reaching work that lives somewhere else.
Running one for other people: an account and a first run, PostgreSQL, TLS and a proxy and systemd, the people and their agents, credentials, backups and upgrading.
The same example throughout
One team, so that the same work reaches you in each way in.
| Who | What they do here |
|---|---|
| Laurence | runs init, owns the instance the others reach, and administers it |
| Keanu | is added to it, and reaches it from a desktop of his own |
| claude | Laurence's coding agent, with an account of its own |
Their workspace is metacortex, written MetaCortex where a display name is asked for, and their project is web, the website rebuild. An account is lower case and a person has a name, so a command reads laurence and a sentence reads Laurence.
How every example here is checked
Every command on these pages was run, and what you see is what it printed. Not transcribed, not tidied: each time this site is built, every chapter is run as a session, twice, and both runs are compared against the page. A page that shows something the commands did not print cannot be published.
Four things are worth knowing about how that is done, because they are the difference between these pages and a set of examples that only prove they ran:
- Each chapter runs on a machine made for it, with no network and nothing else on it, so a command reaches the instance the chapter made and nothing else.
- The clock is the same on every run, which is why a date a command prints is shown as it came out rather than hidden.
- Every chapter is a run of its own. Where a chapter needs an instance that an earlier one built, the commands that build it are at the top, folded away under The work so far, so you can start from any chapter and get what the page shows.
- The one thing the run adds to what you type is an empty home. No configuration you cannot see, and no state from a previous chapter.
A value that changes from run to run, such as a token, a sign-in link or a process number, is written …, and so is a line left out of what a command printed. Nothing is ever added or reordered.
The release these examples ran against is named at the foot of each page. An install line here names no version, so you get the current release, as you would from the project's own instructions.
If you have lost track
Five commands that say what is actually true of this machine, which is more useful than any of the chapters when something is not behaving:
subroutine doctorsays what this installation is and whether it holds together.subroutine connectionslists every instance this machine can reach and where each credential came from. It never prints one.subroutine whoamisays who you are on the instance you are pointed at, and which versions of the plugin, the program and the instance are in play. It says so when two of them disagree.claude mcp listsays whether your editor actually started a Subroutine server, which is a different question from whether the plugin installed.subroutine explain connectingis the short version of this page, without leaving the terminal.