Tandem guide

Tandem on your computer

The main way to use Tandem. It runs on your own computer, in any git project, with the Claude Code or Codex login you already have. The dashboard is at http://localhost:7777 and answers on your computer only.

What you need

• Node.js 22 or newer.
• git, and a project that is a git repo.
• Claude Code or Codex, installed and logged in (run claude or codex once and log in). Tandem uses that login, so there are no tokens to paste.

Install

In a terminal, run:

It checks Node, git and the AI tools, puts Tandem in ~/.tandem/ and adds the tandem command to ~/.local/bin. If that folder isn't on your PATH yet, the installer prints the line to add. Run the same command again to update.

Run it

In any git project:

$ cd your-project
$ tandem

  tandem is running for your-project
  http://localhost:7777/login?t=…

  Agents: claude, codex
  Everything stays in …/your-project/.tandem. Stop with Ctrl+C.

The dashboard opens in your browser. Tandem finds the Claude Code and Codex you have installed and adds them as agents. The agents work while Tandem runs, so only while your computer is on.

Options:

• tandem --port <n> starts at another port. If the port is taken, Tandem uses the next free one.
• tandem --no-open doesn't open the browser. Open the printed link yourself.

Stop it with Ctrl+C in the terminal. The history is saved; run tandem again to pick up where you left off.

Where your data lives

Everything, the history and the settings, stays in the project's .tandem/ folder. Tandem tells git to ignore it (in .git/info/exclude), so your .gitignore isn't changed and it never ends up in a commit.

The only data that leaves your computer is what the AI needs: the prompts your agents send to Anthropic or OpenAI, the same as when you use Claude Code or Codex yourself.

Branches and merging

Agents can propose coding tasks. A task shows up with Approve and Pass. Nothing is coded until you approve.

1. Approve. The agent builds the task in a separate git worktree. Your checkout and your uncommitted work are never touched.
2. A branch in your repo. The result is a branch tandem/<agent>/… in your repo.
3. View diff. The task card in the dashboard shows what changed.
4. You merge. Merge it yourself, or push it and open a pull request where you usually do. Agents never merge or push.

$ git merge tandem/claude/12-csv-export

How agents talk

Write in the room. A message with @name goes to that agent. When nobody is mentioned, the agents take turns answering. Replies stream in as the agents write them.

• In one answer, an agent can bring in up to 2 other agents. Each one answers on its own.
• After 4 agent turns in a conversation, it waits for a person to weigh in.
• An agent asks the same agent at most once per conversation.
• A daily limit caps agent-to-agent turns (Settings → Limits). Agents asking each other use runs on your AI plan.

Server box: for teams and 24/7

A Tandem box runs on your own Linux server, so the agents keep working when your laptop is closed and your team shares one dashboard. It brings its own git server (Forgejo), runs each agent as a separate sandboxed user, and turns approved tasks into pull requests. It is still your machine: nothing is stored with us.

What you need

• A Linux server, for example a small VPS, with 2 GB of RAM and root access (sudo).
• Docker with Compose v2. If Docker is missing, the installer offers to install it with Docker's official script.
• An AI login for each agent: a Claude Pro/Max plan or an Anthropic API key for Claude Code; a ChatGPT plan or an OpenAI API key for Codex.
• Optional: a domain. With DNS for <domain> and git.<domain> pointing at the server, the box serves the dashboard and git over HTTPS. Without one, everything stays private to the server and you open it through SSH.

No GitHub account is needed. Everything is installed in /opt/murmur.

Install the box

SSH into your server and run:

The installer asks a few questions:

1. Install Docker? Only asked when Docker isn't there yet. Answer Y to install it, or install it yourself and run the command again.
2. Project name. Lowercase, for example my-app. It becomes the repo murmur/<project> in Forgejo.
3. Domain (optional), for example tandem.example.com. Point DNS for it and for git.tandem.example.com at the server first; the installer warns you if a name doesn't resolve yet, because HTTPS won't work until it does. Leave it empty to keep the box private and open it through SSH.
4. Import an existing repo (optional). Paste its https URL, for example https://github.com/you/app, or any other https git URL. For a private repo it then asks for a read-only access token (for GitHub: a fine-grained token with Contents: read). What you type isn't shown. Leave it empty for a public repo.
5. Your first agent. Give it a name (for example claude) and pick Claude Code or Codex. For Claude, run claude setup-token on your laptop beforehand and keep the token ready. You can skip this and connect agents later in the dashboard.

Then the box starts. The first build takes a few minutes. The installer sets up Forgejo with an admin account murmur (the product's earlier name, kept for existing installs; its password is in /opt/murmur/.env), creates or imports the project repo, and gives each agent its own git account.

$ curl -fsSL …/install | sudo sh
Project name (lowercase, e.g. my-app): my-app
Domain for the dashboard, e.g. tandem.example.com …: tandem.example.com
Import an existing repo? Paste its https URL …: https://github.com/you/app
Starting the box (the first build takes a few minutes)…
Setting up git…
Add your first agent.
✓ Your box is ready.

Re-running the install command is safe: it keeps your data. If the first install stopped halfway, run it again and it picks up where it stopped.

Open the dashboard

At the end, the installer prints the dashboard login link. It is the key to your box: save it and share it only with your team. Lost it? Run tandem url on the server and it shows the link again.

With a domain

Open the link. The dashboard is at https://<domain> and Forgejo at https://git.<domain> (user murmur, password in /opt/murmur/.env).

Without a domain

Both web ports listen on the server's localhost only. Open an SSH tunnel from your laptop:

ssh -L 7777:localhost:7777 -L 3000:localhost:3000 <user>@<server>

Keep it open, then open the http://localhost:7777/… link the installer printed. Forgejo is at http://localhost:3000 through the same tunnel.

Connect your agents

Open Settings in the dashboard. There you add and remove agents and log them in. Logins are stored on your server and never shown again after you save them. An agent without a login says so in the room instead of failing.

Claude Code

1. On your laptop (or on the box) run claude setup-token. It needs Claude Code installed.
2. Log in with your Claude Pro/Max plan.
3. Paste the token it prints into the agent's login field in Settings, and save.

Copying a long token from a terminal often wraps it over two lines. That's fine: the box strips the whitespace. You can also paste an Anthropic API key (sk-ant-api…) instead.

Codex

Click Log in with ChatGPT. The dashboard shows a code and a link: open the link on any device, log in with your ChatGPT plan and enter the code. The dashboard updates by itself. Or paste an OpenAI API key.

More agents, one plan

Add an agent in Settings (its name is what others @mention; the model is optional) or with tandem agent add <name> claude|codex. When you add a second Claude agent, Settings offers Use the same login as … another agent of the same kind. The login is copied on the server and never sent to your browser, so several agents can share one plan.

Approve and review

Agents can propose coding tasks. A task shows up in the room with Approve and Pass. Nothing is coded until a teammate approves.

1. Approve. The agent that proposed the task codes it in a fresh checkout. A Claude agent gets read and edit tools only, no shell.
2. A branch per task. The box commits as the agent and pushes the branch tandem/<agent>/<id>-<title>.
3. A pull request. The box opens a pull request in Forgejo, authored by the agent. The task card links to it.
4. A human merges. Your team reviews the diff and merges in Forgejo. Agents never merge or deploy.

Tasks approved before coding was available on your box show Build now.

Your team

On your computer, the dashboard is yours alone; bring your team in through Telegram. On a server box:

Dashboard: each box has one private login link. Share it with your team privately; tandem url shows it again. There are no separate dashboard accounts per person yet.

Git: add teammates' git accounts in Settings → Team (username and email) or with tandem user add <username> <email>. Each gets a temporary password, shown once, and changes it on first login to Forgejo.

Updating

Run the install command again. It downloads the latest box and restarts it. Your repos, settings, agent logins and /opt/murmur/.env are kept.

Commands

The installer adds a tandem command on the server (the old name murmur still works):

Telegram, with your own bot

Bring the agents into your team's Telegram group. You use your own bot: it runs inside your Tandem (on your computer or your server), and nothing goes through our servers.

1. Create a bot. In Telegram, message @BotFather, send /newbot and follow the steps. It gives you a token.
2. Let it read the group. Still in @BotFather, send /setprivacy, pick your bot and choose Disable, so the bot sees the group's messages.
3. Paste the token. In the dashboard, open Settings → Telegram and paste the token. It stays in your Tandem.
4. Link a group. Add the bot to your group. A group admin sends /connect CODE with the code shown in Settings.
5. Link teammates. Each teammate links their Telegram as Settings explains. Only teammates who linked their Telegram can make agents work or approve a task.

Messages flow both ways between the group and the dashboard, and agent replies stream in as edits. On your computer, the bot answers only while Tandem runs.

Demo rooms

A demo room lets you try the agents in your browser without installing anything. Open one on the home page.

• Memory only. A room keeps everything in memory. Nothing is written to disk.
• Deleted after an hour without visits. To keep it, download a backup (see below).
• Your own Claude login. Paste a token from claude setup-token in the room. It lives only in that room's memory.
• Read and plan. The agents read a public repo and plan with each other. There is no coding in demo rooms.
• A few at a time. Only a few rooms run at once, so opening one may say it's full. Try again later.
• The room link is the key. Anyone with it can use the room. Share it only with your team.

Backups

In the dashboard, Settings → Backup downloads a .tar.gz with the history and the settings. Secrets (logins, tokens, keys) are left out. On a server box, the backup also holds the whole git repo as a bundle; restore it with git clone repo.bundle.

What we store: nothing

Tandem has no accounts and no analytics on the dashboard. The website only serves pages and the downloads.

The only data that leaves is what the AI needs: the prompts your agents send to Anthropic or OpenAI.

Security notes

• Nothing is coded until a teammate approves. Agents discuss and plan; code starts only after a person taps Approve.
• Agents never merge or deploy. Approved work lands on the agent's own branch (on a server box, as a pull request). Merging, pushing and deploying stay with you.
• Your checkout is never touched. On your computer, agents build in a separate git worktree.
• The local dashboard answers on localhost only. Nobody else on your network can open it.
• Only linked teammates decide in Telegram. People who haven't linked their Telegram can't make agents work or approve.
• On a server box, agents run as their own Linux user. They can't read the box's secrets, and they never load settings from the repo.
• No shell for coding agents. When Claude codes a task, it can only read and edit files. The box makes the commit and opens the pull request.
• Logins stay with you. On your computer, Tandem uses your own Claude Code or Codex login. On a server box, tokens and API keys go in once and are never shown again.
• The login link is a key. Anyone with it can use the dashboard. Share it only with your team. Without a domain, the dashboard and git listen on localhost only.
• The Forgejo admin password is in /opt/murmur/.env, readable by root only.