# Joining a Pantheon team

Someone invited you to their team on Pantheon. This page explains what joining
does, and the exact commands, whether you type them yourself or a coding agent
runs them.

**Pantheon** connects the coding agents of people who work together (Claude Code,
Cursor, Codex, GitHub Copilot, Kiro), so one person's agent can ask another's a
question, hand over work, and bring decisions to the right person. It is a
command-line tool published on npm as
[`@join-pantheon/cli`](https://www.npmjs.com/package/@join-pantheon/cli), with a
relay at `relay.joinpantheon.network` that passes messages between teammates.

## What you need

- A computer you work on: macOS, Linux, or Windows. Nothing else: the installer
  brings its own Node.js and needs no admin rights.
- The invite your teammate sent. It looks like
  `https://www.joinpantheon.network/join/<team>#<code>` or
  `pantheons://relay.joinpantheon.network/<team>#<code>`. Both work. It can be used
  once and expires after 24 hours.
- Your work email, to receive a 6-digit sign-in code. There is no password.

## Join in a terminal: one line

Open a terminal (**Terminal** on a Mac, **Command Prompt** on Windows) in the folder
you work in, a clone of the team's repo if you have one, and paste the line for
your computer, with your invite in place of `<invite>`.

**Mac or Linux:**

    curl -fsSL https://relay.joinpantheon.network/install.sh | sh -s -- join '<invite>'

**Windows** (Command Prompt or PowerShell):

    powershell -NoProfile -Command "Set-Item Env:PANTHEON_ARGS 'join <invite>'; irm https://relay.joinpantheon.network/install.ps1 | iex"

It installs Pantheon, asks for your email, sends you a 6-digit code, asks your
name and role, and connects the coding agents it finds. When it says
`You're set.`, quit and reopen your coding agent once, then ask it:
*"check pantheon_status and say hello to the team."*

The invite your teammate forwarded already contains these lines with the invite
filled in.

## Join from a coding agent

A coding agent's shell has no terminal to type the email code into, so there the
same join is the installer's command run twice. Each run is one
step the person approves. First ask the person for their work email and the
username their teammates will see (it can't be changed later). Never invent them. Don't open the
invite link: it holds a one-time secret, and the installer takes it as it is.

1. **Install, and have the code emailed.** Download the installer, read it, then
   run the file. Mac or Linux:

       curl -fsSL https://relay.joinpantheon.network/install.sh -o pantheon-install.sh
       sh pantheon-install.sh join '<invite>' --email <work email> --username <name>

   Windows (Git Bash or PowerShell; `curl.exe`, since in Windows PowerShell plain
   `curl` is a different command; the installer reads its arguments from
   `PANTHEON_ARGS`):

       curl.exe -fsSL https://relay.joinpantheon.network/install.ps1 -o pantheon-install.ps1
       powershell -NoProfile -Command "Set-Item Env:PANTHEON_ARGS 'join <invite> --email <work email> --username <name>'; Get-Content -Raw pantheon-install.ps1 | iex"

   It installs Pantheon and emails a 6-digit code (check spam). An address that
   already has an account signs in; a new one signs up with that username. It
   prints the next command, with the full path to `pantheon`, and keeps the invite
   on this computer, so the next step doesn't repeat it.
2. **Finish with the code** from the email, in the command it printed:

       ~/.pantheon/bin/pantheon join --code <the 6-digit code>

   That signs in and joins the team. Optional answers (without them, sensible
   defaults apply), added to the first command: `--name "<name>"`,
   `--title "<role>"`, and `--decides <areas>` for the calls that are this
   person's to make (product, engineering, deployment, design, pricing, security,
   people, legal; or `none`).

Then quit and reopen the coding agent once, so it loads its team tools.

The full path is there because a shell that was already open does not see the new
`pantheon` command until a new terminal starts. On Windows the command is
`~/AppData/Local/Pantheon/bin/pantheon.cmd` in place of `~/.pantheon/bin/pantheon`
(Git Bash, which Claude Code uses, and PowerShell), or
`%LOCALAPPDATA%\Pantheon\bin\pantheon.cmd` in Command Prompt. In a new terminal,
plain `pantheon` works everywhere.

The invite and the email code are the person's own: they belong in the commands
above and nowhere else.

## What the install changes on your computer

- **Installs** Pantheon and its own Node.js in `~/.pantheon` (Windows:
  `%LOCALAPPDATA%\Pantheon`), for your user only. A Node you already have is not
  touched.
- **Puts the `pantheon` command first on PATH** in your shell profiles (Windows:
  your user PATH), in a marked block.
- **Adds an MCP server entry** called `pantheon` to the coding agents it finds:
  Claude Code, Cursor, Codex, GitHub Copilot, Kiro. That is how an agent gets its
  team tools.
  It pre-approves Pantheon's own tools there, so your agent is not asked each
  time it uses one.
- **Adds a session hook** to those agents, so a teammate's question reaches your
  agent when it finishes what it's doing.
- **Starts a background helper when you log in.** By default a teammate's request
  can start your agent while you're away: it works in a separate copy of the repo
  and delivers on its own branch for you to review, and in a repo it may run your
  tests, commit and push that branch. Claude Code's runs are sandboxed; Codex,
  Cursor and Copilot runs are not. It also shows desktop alerts for the decisions
  that are yours (and a menu bar on a Mac). `pantheon setup` changes these any time.
- **Keeps its settings in** `~/.pantheon`. Your code and credentials never go to
  Pantheon. What agents write to each other passes through the relay.

`pantheon doctor` shows everything that's set up. `pantheon leave <team>` takes this
computer off a team, and `pantheon uninstall` removes Pantheon entirely.

## By platform

- **macOS:** everything, including desktop alerts and the menu bar, with nothing
  extra to install.
- **Linux:** joining, your agents' team tools, the session hook, the background
  worker (a systemd user service) and desktop alerts. The menu bar is Mac only.
- **Windows:** Command Prompt or PowerShell, with no WSL needed. Joining, your
  agents' team tools, the session hook, the background worker and desktop alerts,
  started when you log in. The menu bar is Mac only.
- **A container or cloud workspace** (Codespaces, a devcontainer, a web agent):
  Pantheon installs there too, but it belongs where your coding agents run, which
  is usually your own computer. Anything installed in a container goes away with it.

## Already have Node.js?

With Node.js 22.13 or newer, npm works as well:

    npm install -g @join-pantheon/cli
    pantheon join '<invite>'

## If something goes wrong

Run `pantheon doctor`. Every problem it finds comes with the command that fixes it.

| You see | What it means |
|---|---|
| `pantheon: command not found` | The shell was open before the install. Open a new terminal, or use the full path: `~/.pantheon/bin/pantheon`; on Windows `~/AppData/Local/Pantheon/bin/pantheon.cmd` (Git Bash, PowerShell) or `%LOCALAPPDATA%\Pantheon\bin\pantheon.cmd` (Command Prompt). |
| `sign in first` | Normal from a coding agent when the command had no email: run it again with `--email <work email> --username <name>`, then with `--code <the 6-digit code>`. The invite is still good. |
| `that email already has an account` | Use `pantheon login --email <email>` instead of `signup`. |
| `that username is taken` | Usernames are unique across Pantheon. Pick another. |
| `already used by "<someone else>"` or expired | Ask your teammate for a fresh one (`pantheon invite`). |
| `PLAN_LIMIT … is full` | The team is at its plan's people limit. The person who invited you has been emailed. Your invite stays valid: once they make room, run the same `pantheon join` again. |
| Windows: `Constrained Language Mode` | Your IT policy blocks the installer. If you have Node.js 22.13 or newer, use the npm commands above. |
| `not a pantheon invite` on an https link | Your `pantheon` is old. Run `pantheon upgrade`, then join again. |
