TeaNode · Documentation · Source

Coding sessions

If you keep several Claude Code and Codex sessions open at once, each in a terminal of its own, your agent can work in them beside you. It sees every session on every computer you attached, reads what each one did, types an instruction into one where you can see it, and brings you the questions they stop to ask, so you can answer from the drawer, from your phone, or from a chat app that speaks MCP while you are away from the desk.

It does this through herdr, a terminal workspace manager for coding agents, which holds the terminals in panes and recognizes the coding agent in each.

What you need

• herdr running on your computer, with your coding sessions in its panes.
• teanode computer start running on that computer, from a current teanode. The program on the computer watches herdr's socket and reports to your server; nothing else is installed.

Each person's sessions are their own: the program signs in as you, and only your agent sees your panes.

What it does

Lists them. The Herdr sessions card on the Connections tab of your agent page, teanode computer herdr list, and the agent's herdr tool all show every session: its name as you find it in herdr, whether it is working, idle or asking, which coding agent it is, the computer, the directory and the title. A session asking a question comes first.

Reads them. The last turns of a session's history, or what its pane shows now.

Types into them. An instruction is typed into the pane in front of you, the same as if you had typed it, and a session at work reads it as a message in its turn. There is one process, one history and one screen, which you and the agent share, and you can take over at any moment.

Brings you their questions. When a session stops to ask something (which option to take, whether it may run a command or make an edit, whether you approve its plan), the question is written into your main conversation. The drawer opens with the options as buttons, and the same question goes to the chat app you linked. Whoever answers first wins: the program on the computer reads the screen again before pressing your answer, and refuses one whose question has gone or changed.

Tells you when one finishes. Ask the agent to watch a session, and the conversation you asked in is woken when that session finishes its turn, so "tell me when the tests pass, then have it open the pull request" works.

Opens and closes them. A new Claude Code or Codex session in a directory, in a new tab of the workspace named after it, or with its permission prompts off when you ask. A session is closed only when it is not working.

From anywhere

Every one of these actions is on the agent's herdr tool, so anything that reaches your agent reaches your coding sessions. A voice call in the drawer can ask what each session is doing and answer the one that is waiting. So can ChatGPT, Grok, or any other assistant that speaks the Model Context Protocol, once it is connected to your server: ask it from your phone, by voice in the car if you like, what your sessions are up to, and tell one what to do next.

To an MCP client the tool says it is read-only, at your word, so these assistants run it without asking each time; most would not let you always allow a tool that writes. Sending and answering raise no confirmation card in the dashboard either, because a card for every answer was more than people wanted. If you want one, put herdr on your own "ask me first" list.

What your agent knows, in the session

The other direction needs no herdr. teanode hook install claude-code (or codex) has every session on that computer shown what your agent knows about the checkout it runs in: the project's page and where the last session there stopped when it starts, what each prompt recalls from that project alone, and its own transcript read within a minute of each answer. Memory in coding sessions has the details.

How it knows a session is asking

From the screen. The program recognizes the forms the current Claude Code and Codex draw for a question, an approval and a plan, and decides each session's state itself rather than taking herdr's, because typing an instruction into a form would answer it. A coding agent that draws its forms differently is not recognized until the recognizer learns it; the session then shows as idle or unknown, and its screen can still be read.

teanode computer herdr setup can also put reporting hooks into Claude Code's settings on that computer, beside the ones there and with a copy of the file kept first. They report what happens and decide nothing. They are put in only when you ask, since they change your Claude Code settings.

A restart of the program on the computer, which every upgrade causes, loses neither a question still waiting nor a watch.

Next

• The command line lists every teanode computer herdr command.
• Memory in coding sessions is the sessions being shown what your agent knows.
• Voice is talking to your agent in the drawer.
• MCP is connecting ChatGPT, Grok or an editor to your server.
• docs/subsystems/devices.md says how the computer program works in detail.

Documentation

Getting started

• What is TeaNode: Send and receive mail at your own domains: mailboxes read here or over IMAP, forwarding, what it does, and what you need to run it.
• Quick start: TeaNode running with docker compose in a few minutes: the assistant first, with no domain, then mail at your own domain if you want it.
• Getting started: Standing up a mail server for one domain, from nothing to mail arriving in a mailbox you can read in a mail program, including the DNS records and the port 25 problem.

Running it

• Deploying: The container image and the compose file, what runs beside the server, how it upgrades itself, and what to back up.
• Configuration: Where the settings live, the environment variables that say how to reach them, and every field an operator can set.
• Agents: The personal agent: what it needs, what it does with a mailbox, and what to weigh before turning it on.
• Memory: What your agent keeps between conversations: a graph of pages it writes without being asked, the places it reads from, and what it does with all of it in its dreams.
• Voice: Call your agent from the chat drawer: say what you want, hear the answer as it is written, and cut in when you like. On a laptop or a phone.
• Coding sessions: Your Claude Code and Codex sessions in herdr, on every computer you attached: your agent reads them, types into them where you can see, and brings you their questions to answer from anywhere.
• Memory in coding sessions: Claude Code and Codex shown what your agent knows about the checkout they run in: the project page and the last session when one starts, recall kept to the project before each prompt, and the transcript read within a minute.
• Model Context Protocol: TeaNode on both ends of the protocol: answering it, so your editor can use your agent's tools and ask it questions, and connecting out to servers of your own.
• Finance: Your banks, cards and brokerages linked through Plaid or SimpleFIN: transactions in your own categories, budgets that say where the month is heading, savings targets, net worth, and a tax year put together from your paystubs, W-2s, 1099s and 1098s, all kept in your own database.
• The command line: The two programs: the server and the few things only its host can do, and the client that administers it from anywhere through the API.

Security

• Reporting a security problem: Where to report something exploitable, what is in scope, and what is not.
• Security review: A review of the whole program: what was examined, what was found, what was fixed, and what is still open.

Contributing

• Contributing: Naming, comments, the invariants that bite, tests, commits and the changelog that cuts a release.
• Local development: Getting a working build and a database to point it at, a development server that cannot send mail, and the optional scanners.
• Project structure: What each package is for and which way the dependencies point.

Every document is also plain markdown, listed in /llms.txt.