# Getting started

Install brainplane, connect your agents in 3 screens and get your first card.

Canonical: https://brainplane.app/docs/getting-started/

## What you need

- A Mac with Apple silicon (M1 or later) and macOS 26 or later.
- At least 1 AI agent on your own account: Claude Code, Codex or Grok. brainplane sells no AI subscription.
- Nothing else for brainplane itself. The app carries its own Node runtime.

## Install

Download the disk image from the [download page](/download/). Open the disk image and drag brainplane to Applications. The app is signed with an Apple Developer ID and notarized by Apple, so macOS opens it with no warning.

On first launch brainplane starts a small local service. It listens on your Mac only, on `127.0.0.1` and a private socket, and runs in the background with your user account.

## Start your trial

Enter your email. brainplane sends a 6-digit code, and your 14-day trial starts with every feature. No card. If you bought a licence, paste your key instead, or sign in with the email you used at checkout.

## The first run, in 3 screens

1. **Welcome.** brainplane looks for the agent tools on your Mac and for your work folders. Files stay on your Mac.
2. **Your agents.** Each agent shows as signed in, or with 1 button: Install, or Sign in. Sign-in opens the vendor's own login in Terminal. brainplane never reads their keys.
3. **Your work.** Your work folder, the skills it found and your voice setup. 1 switch connects Claude Code, Codex and Grok when you press Start. The screen names the 3 files it changes and keeps a backup of each.

On a Mac where your agents are already installed and signed in, that is 3 presses of Return.

## What connect changes

Start adds 1 entry named `brainplane` to the MCP servers of each agent, with each agent's own command. Your other servers, hooks and settings stay as they were. The backups sit in your brainplane folder, and Settings undoes the change for 24 hours.

Hooks are optional. They let an agent tell brainplane when a session starts, when you type a prompt and when a turn ends. Each hook runs in 1 or 2 seconds at most and fails open: if brainplane is not running, the agent carries on.

## Your first topic

A topic is 1 piece of work you follow: a deal, a trip, a repo, a hire. If you already keep Markdown notes per project, brainplane imports them read-only:

```
bp import --dry-run
```

The dry run lists what it would read and changes nothing. Topics keep their state in 4 blocks: done, waiting on you, waiting on others, next step.

## Your first card

Start a Claude Code, Codex or Grok session as you always do. When it needs you, its question arrives in the Inbox as 1 card, with why it reached you. Answer with 1 key. Every answer waits 2 seconds, or 5 seconds when the risk is high, so you can take it back.

## The bp command

`bp` is the command line companion. A few to start:

| Command | What it does |
|---|---|
| `bp doctor` | Checks the local service and prints versions |
| `bp open` | Opens the app page in your browser with a one-time login |
| `bp delegate codex --mode review` | Hands work to Codex with a context pack |
| `bp stats` | Questions asked per day and the share answered without you |