> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basemode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Commands for work that spans sessions or runs in several at once: handoffs that resume where you stopped, forks that park side-work, and the full relay surface for sessions talking to each other.

Three commands, three different problems. `base handoff` is for stopping and picking up again later. `base fork` is for side-work you want to keep visible without derailing what you are doing now. `base relay` is for two or more sessions running at the same time and needing to reach each other.

Handoffs and forks both surface at the start of a session, and both are exempt from the character budget that trims other injected content, so they keep appearing until you act on them.

<Warning>
  `base relay dispose` deletes a project's relay store. It prints what it would remove and changes nothing until you pass `--force`. Everything else on this page either writes or reads; nothing else here removes data.
</Warning>

## Handoffs

A handoff is a document that says where you stopped and what happens next. Register one when you finish a session, and it is offered back to you when you start the next one.

`base handoff` carries `-g` / `--global` on the command itself, before the verb.

### base handoff create

Register a document as this project's handoff.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base handoff create --project basemode --doc "/home/you/basemode/.base/handoffs/2026-08-25-docs.md"
base handoff create --project basemode --doc "/home/you/basemode/.base/handoffs/2026-08-25-docs.md" --slug docs-pickup
base handoff -g create --project basemode --doc "/home/you/notes/pickup.md"
```

| Flag                  | What it does                                                      |
| --------------------- | ----------------------------------------------------------------- |
| `--project <PROJECT>` | The project this handoff belongs to. Required.                    |
| `--doc <DOC>`         | Absolute path to the document. Required.                          |
| `--slug <SLUG>`       | The title you summon it by. Defaults to the document's file name. |

Creating a handoff archives any handoff already open for that project. That is the difference from a fork, and it is deliberate: a project has one current place to pick up, not five.

### base handoff list

Show open handoffs from the global tier and this workspace together, with the tier each one lives in.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base handoff list
```

### base handoff snooze

Hide a handoff for a number of days.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base handoff snooze docs-pickup 7
```

Both arguments are positional: the slug, then the number of days. Use this when something is real but not now.

### base handoff archive

Stop a handoff resurfacing, permanently.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base handoff archive docs-pickup
```

### base fork create

Register a build specification as a fork: side-work that stays visible without replacing anything.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base fork create --project basemode --doc "/home/you/.base-gbl/forks/docs-site.md"
base fork create --project basemode --doc "/home/you/.base-gbl/forks/docs-site.md" --slug docs-site
base fork -g create --project basemode --doc "/home/you/.base-gbl/forks/docs-site.md"
```

| Flag                  | What it does                                                      |
| --------------------- | ----------------------------------------------------------------- |
| `--project <PROJECT>` | The project this fork belongs to. Required.                       |
| `--doc <DOC>`         | Absolute path to the document. Required.                          |
| `--slug <SLUG>`       | The title you summon it by. Defaults to the document's file name. |

Forks are additive. Creating one does not archive its siblings, so several can be open at once and each is picked up by name.

### base fork list

Show open forks across both tiers.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base fork list
```

### base fork snooze

Hide a fork for a number of days.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base fork snooze docs-site 14
```

### base fork archive

Stop a fork resurfacing.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base fork archive docs-site
```

## Relay

Relay is for sessions running at the same time. Each session registers under a stable title, and everything else addresses that title rather than a session id you would have to look up.

The store is per project and deliberately disposable. It is a working surface for a milestone, not a permanent record.

### base relay init

Create the relay store for a project.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base relay init --project basemode
```

| Flag                  | What it does                                |
| --------------------- | ------------------------------------------- |
| `--project <PROJECT>` | The project the store belongs to. Required. |

### base relay register

Give this session a stable title, so other sessions can address it.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base relay register --as docs-builder
base relay register --as docs-builder --project basemode
base relay register --as docs-builder --phase 3
```

| Flag                  | What it does                                                                      |
| --------------------- | --------------------------------------------------------------------------------- |
| `--as <TITLE>`        | The stable identity: `docs-builder`, `orchestrator`, `worker-phase-11`. Required. |
| `--session <SESSION>` | Override the session id, which otherwise comes from the environment.              |
| `--phase <PHASE>`     | Tag the session with a phase, so `phase:<n>` addressing reaches it.               |
| `--project <PROJECT>` | Tag the session with a project.                                                   |

Register early. Until a session has a title, nothing can be sent to it by name.

### base relay send

Send a typed message to a session, a title, a phase, or everyone.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base relay send --to orchestrator --type question --msg "Which block merges first?"
base relay send --to phase:3 --type unblock --msg "Reference is green"
base relay send --to all --type notify --msg "Branch site is at bca72a4" --refs "docs.json"
```

| Flag                  | What it does                                                                                                         |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `--to <TO>`           | A title, a session id, `phase:<n>`, or `all`. Required.                                                              |
| `--type <MTYPE>`      | One of `claim`, `release`, `notify`, `unblock`, `contract-change`, `ready-to-merge`, `question`, `answer`. Required. |
| `--msg <MSG>`         | The message. Required.                                                                                               |
| `--from <FROM>`       | Override the sender, which defaults to this session's title.                                                         |
| `--refs <REFS>`       | File paths or phase ids the message is about.                                                                        |
| `--project <PROJECT>` | Which project's store to use.                                                                                        |

### base relay poll

Read pending messages without blocking. Reading them consumes them.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base relay poll
base relay poll --peek
base relay poll --for orchestrator
```

| Flag                  | What it does                                             |
| --------------------- | -------------------------------------------------------- |
| `--for <FOR_TITLE>`   | Read as a different title instead of this session's own. |
| `--peek`              | Read without consuming, so the messages stay pending.    |
| `--project <PROJECT>` | Which project's store to use.                            |

### base relay wait

Block until a matching message arrives. This costs no tokens while it waits, which is what makes it better than polling in a loop.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base relay wait
base relay wait --from orchestrator --type unblock
base relay wait --timeout 900
```

| Flag                  | What it does                                       |
| --------------------- | -------------------------------------------------- |
| `--from <FROM>`       | Only wake for messages from this sender.           |
| `--type <MTYPE>`      | Only wake for this message type.                   |
| `--timeout <TIMEOUT>` | Seconds to wait before giving up. Defaults to 300. |
| `--for <FOR_TITLE>`   | Wait as a different title.                         |
| `--project <PROJECT>` | Which project's store to use.                      |

### base relay claim

Take an advisory claim on a path or a phase, so other sessions can see you are working there.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base relay claim "docs/reference"
base relay claim "docs/reference" --note "writing the six family pages" --ttl 7200
```

| Flag                  | What it does                                            |
| --------------------- | ------------------------------------------------------- |
| `--note <NOTE>`       | What you are doing with it. Empty by default.           |
| `--ttl <TTL>`         | How long the claim lasts, in seconds. Defaults to 3600. |
| `--project <PROJECT>` | Which project's store to use.                           |

Claims are advisory. Nothing enforces them, and a claim that expires simply stops appearing. The point is that `base relay board` shows who is where before two sessions edit the same file.

### base relay release

Give a claim back.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base relay release "docs/reference"
base relay release "docs/reference" --force
```

| Flag                  | What it does                                |
| --------------------- | ------------------------------------------- |
| `--force`             | Release someone else's claim, not your own. |
| `--project <PROJECT>` | Which project's store to use.               |

### base relay board

The operator view: every session, whether it is alive, what it has claimed, and how many messages are waiting for it.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base relay board
base relay board --project basemode
```

| Flag                  | What it does                   |
| --------------------- | ------------------------------ |
| `--project <PROJECT>` | Which project's store to show. |

### base relay export

Write the current spool out as `inbox.nq`, a read-only snapshot.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base relay export
```

| Flag                  | What it does                     |
| --------------------- | -------------------------------- |
| `--project <PROJECT>` | Which project's store to export. |

Do this before `base relay dispose` if you want to keep any of it.

### base relay dispose

**Destructive. Preview by default.** Tear down a project's relay store at the end of a milestone.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base relay dispose --project basemode
base relay dispose --project basemode --force
```

| Flag                  | What it does                                                                     |
| --------------------- | -------------------------------------------------------------------------------- |
| `--project <PROJECT>` | The store to tear down. Required.                                                |
| `--force`             | Actually delete. Without it, the command prints what would be removed and stops. |

### base relay task

Hand a briefed task to another live session. It keeps firing in that session until it is picked up, and it crosses workspaces through the global tier.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base relay task --to docs-builder --slug reference-block --summary "Write the six reference family pages"
base relay task --to docs-builder --slug reference-block --summary "Write the reference pages" --doc "/home/you/.base-gbl/forks/docs-site.md" --priority high
```

| Flag                    | What it does                                                                |
| ----------------------- | --------------------------------------------------------------------------- |
| `--to <TO>`             | The target session's registered title. Required.                            |
| `--slug <SLUG>`         | Kebab-case task slug, matching the briefing document's file name. Required. |
| `--summary <SUMMARY>`   | The one line shown in the alert. Required.                                  |
| `--doc <DOC>`           | Absolute path to the full briefing the receiver should read.                |
| `--priority <PRIORITY>` | `high` or `medium`. Defaults to `high`.                                     |
| `--from <FROM>`         | The origin label the receiver sees. Defaults to this session's title.       |

A task is the right shape when there is a document behind it. If everything you need to say fits in three sentences, send a ping instead.

### base relay ping

Send an instant message to a live titled session. No document, no completion ceremony. It interrupts the receiver mid-turn, and their reply clears it.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base relay ping --to orchestrator --msg "Reference block is green on all three scripts"
base relay ping --to orchestrator --msg "Reference block is green" --refs "reference/setup.mdx"
```

| Flag            | What it does                                               |
| --------------- | ---------------------------------------------------------- |
| `--to <TO>`     | The target session's registered title. Required.           |
| `--msg <MSG>`   | The message, carrying all of its context inline. Required. |
| `--refs <REFS>` | File paths or entity ids the ping is about.                |
| `--from <FROM>` | The origin label the receiver sees.                        |

Keep a ping to a sentence or three. More than that is a task, and sending it as a ping means the context has nowhere to live afterwards.

### base relay done

Mark a relayed task finished, which clears the alert in the receiving session and closes its record in the graph.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base relay done reference-block
```

### base relay tasks

List inbound relay tasks across every live session.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base relay tasks
```

### base relay sessions

List every titled session in the global registry, with liveness.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base relay sessions
```

Check this before sending a task. A title that is not listed here has nothing behind it, and the task will sit unread.