Configuration Reference

Configuration Reference

Environment Variables

Set these in your shell profile (~/.zshrc, ~/.bashrc) or a sourced env file.

Variable	Required	Default	Description
ANTHROPIC_API_KEY	Yes	—	Your Anthropic API key
FLEET_MACHINE_NAME	Recommended	hostname -s	Machine name for inbox routing. Must match inbox/<name>.md in your KB
KB_ROOT	No	$HOME/knowledge	Path to your knowledge base repo
GEMINI_API_KEY	No	—	Gemini 2.5 Flash API key — enables mid-tier routing
NVIDIA_API_KEY	No	—	NVIDIA NIM API key — 134 models under one key for code/classification tasks
TELEGRAM_BOT_TOKEN	No	—	Telegram bot token from @BotFather
TELEGRAM_CHAT_ID	No	—	Your Telegram chat ID (DM the bot /start to get it)
SESSION_STALE_MIN	No	15	Minutes before a session board entry is flagged as stale

settings.json

The only file that lives in ~/.claude/settings.json. Everything else lives in ~/claude-fleet/ or ~/knowledge/.

{
  "permissions": {
    "defaultMode": "bypassPermissions",
    "deny": [
      "Bash(rm -rf /)",
      "Bash(sudo rm -rf *)"
    ]
  },
  "skipDangerousModePermissionPrompt": true,
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{
          "type": "command",
          "command": "$HOME/claude-fleet/session-board-show.sh",
          "timeout": 15,
          "statusMessage": "Checking session board..."
        }]
      },
      {
        "hooks": [{
          "type": "command",
          "command": "$HOME/claude-fleet/kb-inbox-check.sh",
          "timeout": 30,
          "statusMessage": "Checking inbox..."
        }]
      }
    ],
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "$HOME/claude-fleet/kb-session-end.sh",
          "timeout": 30,
          "statusMessage": "Syncing knowledge base..."
        }]
      },
      {
        "hooks": [{
          "type": "command",
          "command": "node $HOME/claude-fleet/notify-human.js",
          "timeout": 10,
          "statusMessage": "Sending notification..."
        }]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [{
          "type": "command",
          "command": "$HOME/claude-fleet/session-board-checkout.sh",
          "timeout": 10,
          "statusMessage": "Checking out of session board..."
        }]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [{
          "type": "command",
          "command": "$HOME/claude-fleet/check-notifications.sh",
          "timeout": 5,
          "statusMessage": "Checking fleet notifications..."
        }]
      }
    ]
  }
}

bypassPermissions: Prevents Claude from pausing for approval prompts, which is essential for autonomous/headless fleet operation. Claude still cannot run explicitly denied commands (like rm -rf /). If you want a supervised session, temporarily set defaultMode to default.

Hook Scripts

All scripts live in ~/claude-fleet/. They reference KB_ROOT (default: ~/knowledge) and FLEET_MACHINE_NAME (default: hostname -s).

Script	Hook	What it does
session-board-show.sh	SessionStart	Register on the board; print active sessions
kb-inbox-check.sh	SessionStart	Pull KB; inject pending inbox items into context
kb-session-end.sh	Stop	Commit + push any KB changes
notify-human.js	Stop	Send Telegram notification (status icon + summary)
session-board-checkout.sh	SessionEnd	Remove entry from session board
check-notifications.sh	PostToolUse	Poll local notification directory for mid-session messages
fleet-inbox-check.sh	Manual / cron	SSH to all machines and trigger their inbox check in parallel

Inbox Claim Protocol

When Claude starts processing an inbox item, it should claim the trigger file to prevent sibling sessions from picking up the same item:

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

# Mark done when finished (also commit and push)
~/claude-fleet/inbox-claim.sh triggers/my-task.md done

Trigger file format (triggers/my-task.md):

---
title: My task title
status: pending          # pending | in_progress | completed | blocked
target: beta             # which machine should process this
claimed_by:              # auto-filled by inbox-claim.sh
claimed_pid:             # auto-filled — used for liveness checking
claimed_at:              # auto-filled
completed_at:            # auto-filled on done
---

Task description. One paragraph is ideal. Reference any files in the KB the agent will need.

Session Board Commands

# Register (done automatically by the hook, but useful for manual sessions)
~/claude-fleet/session-board.sh checkin my-slug -s "Claude Sonnet" -r ~/my-project -S active -w "reviewing PRs"

# Update status and what you're doing
~/claude-fleet/session-board.sh heartbeat my-slug -S building -w "compiling..."

# Claim a singleton (prevents others from starting the same resource)
~/claude-fleet/session-board.sh claim my-slug "ue-build-engine, sim-booted"

# Print the board
~/claude-fleet/session-board.sh board

# Remove your entry (done automatically by the hook)
~/claude-fleet/session-board.sh checkout my-slug

Model Routing

See docs/13-model-routing.md for full routing logic, curl commands, and confidence threshold examples.

Quick reference:

# Gemini 2.5 Flash (1M context, good for large-file analysis)
GEMINI_API_KEY=$GEMINI_API_KEY gemini -p "summarize: $(cat big-file.txt)" -y

# NVIDIA NIM (code gen, 134 models)
curl https://integrate.api.nvidia.com/v1/chat/completions \
  -H "Authorization: Bearer $NVIDIA_API_KEY" \
  -d '{"model": "meta/llama-3.1-70b-instruct", "messages": [{"role":"user","content":"..."}]}'

# Local Ollama (free, runs on any fleet machine)
curl http://localhost:11434/api/generate -d '{"model": "llama3.2", "prompt": "..."}'

Windows Configuration

Use settings-windows.json as your template — it swaps all .sh hooks for .js equivalents:

cp templates/settings-windows.json ~/.claude/settings.json

Node.js scripts are in scripts/*.js. They have the same behavior as the bash versions.