Busabase Setup Guide: Let Agents Write, Review Every Change

npx busabase server

#   ➜  Server   http://127.0.0.1:15419
#   ➜  Data     ~/.busabase/data
#   ➜  Access   bound to 127.0.0.1, this machine only

# Docker (also on GHCR as ghcr.io/busabase/busabase)
docker run --rm -p 15419:15419 -v ~/.busabase/data:/data busabase/busabase

# Global install
npm i -g busabase && busabase server

# A second, throwaway workspace on another port
npx busabase server --port 15420 --data ~/busabase-sandbox

Read and follow the Busabase Agent Skill, it is the single source of truth:
http://localhost:15419/SETUP_SKILL.md

Follow its onboarding to connect to this workspace. Don't choose a merge policy
yourself unless I ask for one: submit the change and let Busabase apply my
permissions to decide whether it merges now or waits for review.

claude mcp add --transport http --scope user busabase http://localhost:15419/api/mcp

{
  "mcpServers": {
    "busabase": { "url": "http://localhost:15419/api/mcp" }
  }
}

[mcp_servers.busabase]
url = "http://localhost:15419/api/mcp"

npx busabase-cli login --base-url "http://localhost:15419"

# 1. A folder (structure changes are Change Requests too)
curl -X POST http://localhost:15419/api/v1/nodes/change-requests \
  -H 'content-type: application/json' \
  --data '{"message":"Create the Sales folder","autoMerge":true,
           "operations":[{"kind":"create","nodeType":"folder","slug":"sales","name":"Sales"}]}'
# -> read mergeSummary.mergedNodeIds[0], that is the folder id

# 2. The Base inside it
curl -X POST http://localhost:15419/api/v1/bases \
  -H 'content-type: application/json' \
  --data '{
    "slug": "leads", "name": "Leads", "parentNodeId": "<FOLDER_ID>", "autoMerge": true,
    "fields": [
      { "slug": "name",    "name": "Name",      "type": "text", "required": true },
      { "slug": "company", "name": "Company",   "type": "text" },
      { "slug": "stage",   "name": "Stage",     "type": "select",
        "options": { "choices": [
          { "id": "lead", "name": "Lead", "color": "slate" },
          { "id": "qualified", "name": "Qualified", "color": "amber" },
          { "id": "customer", "name": "Customer", "color": "emerald" } ] } },
      { "slug": "deal",    "name": "Deal size", "type": "number" },
      { "slug": "notes",   "name": "Notes",     "type": "longtext" }
    ]
  }'

curl -X POST http://localhost:15419/api/v1/bases/<BASE_ID>/change-requests \
  -H 'content-type: application/json' \
  --data '{"fields":{"name":"Dana Ortiz","company":"Northwind Labs","stage":"lead","deal":4800},
           "message":"Add Dana Ortiz from the inbound form",
           "idempotencyKey":"seed:v1:dana","autoMerge":true}'

npx busabase-cli install https://github.com/busabase/templates/tree/main/templates/busa-crm

// tools/call record_change_request
{
  "recordId": "<RECORD_ID>",
  "operation": "update",
  "fields": { "stage": "qualified", "deal": 9600,
              "notes": "Signed up from the pricing page. Booked a demo for Thursday, team of 12." },
  "message": "Qualify Dana Ortiz: demo booked, team of 12",
  "requireReview": true
}
// -> "status": "in_review"

## Busabase
- Every write to Busabase waits for my review.
- Updates: record_change_request with requireReview: true.
- New records: bases_create_change_request with autoMerge: false.
- Write the message as "<verb> <what>: <why>", it is what I read in the inbox.
- Never call change_request_review or change_request_merge. Approving is my job.

curl -X POST http://localhost:15419/api/v1/change-requests/reviews \
  -H 'content-type: application/json' \
  --data '{"verdict":"approved","reason":"Demo is on the calendar.","changeRequestIds":["<CR_ID>"]}'
# -> "status": "approved"   (not merged yet)

curl -X POST http://localhost:15419/api/v1/change-requests/merge \
  -H 'content-type: application/json' \
  --data '{"changeRequestIds":["<CR_ID>"]}'
# -> "status": "merged"

npx skills add busabase/skills --skill busabase busabase-app-creator

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>com.busabase.server</string>
  <key>ProgramArguments</key>
  <array><string>/bin/sh</string><string>-lc</string><string>npx -y busabase server</string></array>
  <key>RunAtLoad</key><true/><key>KeepAlive</key><true/>
</dict></plist>

launchctl load ~/Library/LaunchAgents/com.busabase.server.plist

# Linux: a user service in ~/.config/systemd/user/busabase.service
#   [Service]
#   ExecStart=/usr/bin/env npx -y busabase server
#   Restart=on-failure
#   [Install]
#   WantedBy=default.target
systemctl --user enable --now busabase.service
loginctl enable-linger "$USER"   # keep it up without a login session