Recipes

Recipes

Common workflows with example commands.

Delegate a Task to Another Machine

Write a task to the target machine's inbox, commit, and push. The machine picks it up on its next session start.

cd ~/knowledge
cat >> inbox/beta.md << 'EOF'
- [ ] [2024-01-15 14:30] @alpha → build: Run the test suite on the current branch and write results to daily/2024-01-15-beta.md
EOF
git add inbox/ && git commit -m "inbox(beta): run tests" && git push

For immediate execution (if you have SSH access), use the fleet task script:

node ~/claude-fleet/scripts/fleet-task.js beta "Run the test suite" --tools Bash,Read

Results stream back to your terminal in real time.

Route Heavy Work to Gemini 2.5 Flash

When a task involves a large file, long document, or bulk summarization — route it to Gemini's 1M context window instead of burning Claude tokens:

# Summarize a large codebase file
GEMINI_API_KEY=$GEMINI_API_KEY gemini -p "Summarize the architecture in this file and list the key abstractions: $(cat src/core/engine.ts)" -y

# Analyze a log dump
GEMINI_API_KEY=$GEMINI_API_KEY gemini -p "Find all ERROR lines in this log and group them by type: $(cat /tmp/build.log)" -y

# Batch research across multiple files
files=$(cat docs/*.md)
GEMINI_API_KEY=$GEMINI_API_KEY gemini -p "What are the 5 most important design decisions documented here? $files" -y

Tell Claude to route specific subtasks: "Use Gemini for the summarization step — here's the pattern: GEMINI_API_KEY=$GEMINI_API_KEY gemini -p '...' -y"

Coordinate Two Sessions Without Conflicts

When two sessions need to work in the same repo simultaneously:

# Session A — on branch feat/api
git worktree add ../project-api -b feat/api

# Session B — on branch feat/ui (in a separate worktree)
git worktree add ../project-ui -b feat/ui

Each session commits to its own branch. When done, merge:

cd ~/my-project
git merge feat/api feat/ui

Meanwhile, on the session board:

# Session A announces itself
~/claude-fleet/session-board.sh checkin api-work \
  -s "Claude Sonnet" -r ~/my-project -b feat/api \
  -S active -w "building REST endpoints"

# Session B checks who else is there before starting
~/claude-fleet/session-board.sh board

Claim a Singleton Before Starting a Long Build

If you're about to start something that can't run twice (a GPU-intensive build, an install to a physical device, a long compile), claim it:

# Check the board first
~/claude-fleet/session-board.sh board

# If clear, claim the resource
~/claude-fleet/session-board.sh checkin my-build -s "Xcode 26" -r ~/MyApp -S building \
  -c "xcode-build, iPhone-device" -e "~15 min"

# Update status at checkpoints
~/claude-fleet/session-board.sh heartbeat my-build -S verifying -w "running test suite"

# Release when done (or let the SessionEnd hook do it automatically)
~/claude-fleet/session-board.sh checkout my-build

Any other session that checks the board will see claim: xcode-build, iPhone-device and know not to start a competing build.

Claim an Inbox Item Before Starting

When you pick up a task from the inbox, claim it immediately so sibling sessions don't also pick it up:

# Claim
~/claude-fleet/inbox-claim.sh triggers/my-task.md

# Do the work...

# Mark done when finished (and commit + push the trigger)
~/claude-fleet/inbox-claim.sh triggers/my-task.md done
cd ~/knowledge && git add triggers/ && git commit -m "chore: complete my-task" && git push

Write a Technique Inline (Don't Lose the Fix)

The moment you resolve a hard debugging session, write it down:

# Copy the template
cp ~/knowledge/resources/templates/technique.md \
   ~/knowledge/intelligence/techniques/xcode-derived-data-cache-corrupt.md

# Edit it with the problem, fix, and why it happens
# Then commit immediately — don't wait until session end
cd ~/knowledge
git add intelligence/techniques/
git commit -m "docs(technique): xcode derived data cache corrupt after SPM update"
git push

Next time any session on any machine hits the same wall, it finds the fix instead of spending an hour re-debugging.

Build a Daily Habit (Checkpoint Logs)

The most valuable KB content comes from checkpoint logging — not one big dump at session end.

Triggers for writing a log:

• Something compiled for the first time
• A bug is fixed
• A decision is made
• A gotcha is hit (even if not yet resolved)

# Append to today's log at each checkpoint (don't wait for session end)
cat >> ~/knowledge/daily/2024-01-15-alpha.md << 'EOF'

## 14:32 — Xcode build passing
Fixed the SwiftUI layout issue — the problem was `GeometryReader` inside a `LazyVStack` which forces immediate rendering. Replaced with `ViewThatFits`. Build green, tests passing.
EOF

cd ~/knowledge && git add daily/ && git commit -m "chore(daily): xcode layout fix checkpoint" && git push

The kb-session-end.sh hook pushes everything at session end as a backstop, but don't rely on it — a session that crashes loses the session-end push, and a session-start hook that fails silently skips the pull. Write at checkpoints.

Set Up a Telegram Channel on One Machine

Pick one always-on machine (home server, always-on desktop) to run the Telegram channel:

# Install the official channel plugin
claude --channels plugin:telegram@claude-plugins-official

# Add the channel add-ons for rate-limit awareness
mkdir -p ~/claude-fleet/telegram/channel-addons
cp ~/claude-fleet-repo/telegram/channel-addons/*.sh ~/claude-fleet/telegram/channel-addons/
cp ~/claude-fleet-repo/telegram/channel-addons/statusline.py ~/claude-fleet/telegram/channel-addons/
chmod +x ~/claude-fleet/telegram/channel-addons/*.sh

Add to ~/.claude/settings.json:

{
  "statusLine": "python3 $HOME/claude-fleet/telegram/channel-addons/statusline.py",
  "hooks": {
    "StopFailure": [{
      "hooks": [{ "type": "command",
                  "command": "$HOME/claude-fleet/telegram/channel-addons/rate-limit-autosleep.sh",
                  "timeout": 10 }]
    }]
  }
}

See telegram/channel-addons/README.md for the full setup and what each script does.