Skip to content

Getting Started

Jump to bottom
Alex Coulombe edited this page Jun 28, 2026 · 1 revision

Getting Started

From zero to your first inter-machine task in about 30 minutes.

Prerequisites

  • 1–2+ computers running macOS or Linux (Windows supported with Node.js scripts)
  • Claude Code installed on each machine
  • A private git repository (GitHub free tier works)
  • Tailscale for SSH between machines (free tier works; skip if single-machine)
  • Node.js installed on each machine

Step 1: Connect Your Machines (Tailscale)

Install Tailscale on every machine and join the same tailnet. Once done, verify:

# From your laptop — should print the server's Tailscale IP
ping <server-tailscale-hostname>
ssh <server-tailscale-hostname>

If you're only using one machine, skip this step.

Step 2: Create the Shared Knowledge Base

Create a private repo on GitHub (or GitLab, Gitea, etc.), then clone it as ~/knowledge on every machine:

# On each machine
git clone git@github.com:you/fleet-kb.git ~/knowledge

Copy the starter CLAUDE.md and KB structure from this repo:

# One-time setup on each machine
cd ~/knowledge
cp /path/to/claude-fleet/templates/CLAUDE.md .

# Create folders
mkdir -p inbox daily intelligence/techniques intelligence/decisions fleet projects sessions/active triggers

# Create inbox files — one per machine (use your actual machine names)
cp /path/to/claude-fleet/templates/inbox/example-machine.md inbox/alpha.md
cp /path/to/claude-fleet/templates/inbox/example-machine.md inbox/beta.md

git add . && git commit -m "init: knowledge base structure" && git push

Machine names: pick short, memorable names (alpha/beta/gamma, or laptop/desktop/server, or your actual hostnames). The name must match your inbox filename: inbox/<name>.md.

Step 3: Install Scripts

Clone this repo and copy the fleet scripts to ~/claude-fleet/ on each machine:

git clone https://github.com/ibrews/claude-fleet.git /tmp/claude-fleet-repo
mkdir -p ~/claude-fleet
cp /tmp/claude-fleet-repo/scripts/*.sh ~/claude-fleet/
cp /tmp/claude-fleet-repo/scripts/*.js ~/claude-fleet/
chmod +x ~/claude-fleet/*.sh

Set your machine name if it doesn't match your inbox filename:

# Add to ~/.zshrc or ~/.bashrc
export FLEET_MACHINE_NAME=alpha   # must match inbox/alpha.md

Step 4: Configure Hooks

Copy the template settings to ~/.claude/settings.json (this is the only file that must live in ~/.claude/):

cp /tmp/claude-fleet-repo/templates/settings.json ~/.claude/settings.json

The template wires up these hooks:

  • SessionStart: session board check → inbox check
  • Stop: KB sync → Telegram notification
  • SessionEnd: session board checkout

Verify Node.js path for headless sessions:

which node   # e.g. /opt/homebrew/bin/node

If it's not /usr/bin/node, update the notify-human.js hook command in settings.json to use the full path.

Step 5: Set Up Telegram (Optional)

Telegram is optional but recommended — it's how you know when a session finishes without watching the terminal.

See docs/06-telegram-bot.md for setup. You'll need a bot token from @BotFather and your chat ID.

Add to your shell profile or ~/claude-fleet/fleet.env:

export TELEGRAM_BOT_TOKEN="your-token"
export TELEGRAM_CHAT_ID="your-chat-id"

Step 6: Test It

Send a task to another machine:

cd ~/knowledge
cat >> inbox/beta.md << 'EOF'
- [ ] [2024-01-15 12:00] @alpha → check: Are you alive? Write a one-line response to inbox/alpha.md.
EOF
git add inbox/ && git commit -m "test: ping beta" && git push

Trigger beta (from your laptop, SSH in and start a session — or just wait for beta's next scheduled session):

ssh beta "claude -p 'check your inbox' --max-turns 3"

In a few seconds, check the KB:

cd ~/knowledge && git pull && cat inbox/alpha.md

You should see beta's response. If Telegram is configured, you'll also get a notification.

Step 7: Check the Session Board

While any session is running, open another terminal and check the board:

~/claude-fleet/session-board.sh board

You'll see the session, its status, and any singleton resources it holds.

What's Next

Clone this wiki locally