FAQ

FAQ

Do I need Telegram?

No. Telegram adds two things: notifications (know when a session finishes without watching the terminal) and phone control (interact with a Claude session by messaging the bot). Neither is required for the inbox system, KB sync, or session board to work. Start without Telegram, add it when the lack of notifications becomes annoying.

Do I need Tailscale?

Only for SSH between machines. If your machines are on the same local network, you can use local SSH hostnames instead. If you're only using one machine, you don't need Tailscale at all.

Does this work on Windows?

Yes. All the bash hook scripts have Node.js equivalents (scripts/*.js). Use templates/settings-windows.json as your settings.json and Node.js paths in the hook commands. See Configuration Reference for details.

Can Claude sessions on different machines talk to each other directly?

No, and this is by design. The Claude Code harness blocks live messaging between sessions in headless/autonomous mode (even with user approval, the MCP tools for this are blocked in --print/-p mode). The only reliable channel is committed files — the inbox system, the session board, and the KB. This is not a limitation to work around; it's what makes the system reliable. A session that wrote wrong information into a shared file is a problem you can fix; a silent runtime message that was dropped is a problem you might never know about.

Sessions keep picking up each other's inbox items — how do I stop this?

Use the inbox claim protocol. When Claude starts working on an inbox item, it should claim the trigger file:

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

This stamps status: in_progress + the session's PID. The kb-inbox-check.sh hook then suppresses that item for all other sessions — but only while the claiming process is alive. If the session crashes, the claim auto-expires and the item resurfaces on the next session start.

How do I handle API costs across a fleet?

The model routing tier is designed for this. Most tasks don't need Claude — they need "good enough, fast, cheap." Route them:

• Summarization / formatting / simple search → local Ollama (free)
• Research, large-file analysis, drafting → Gemini 2.5 Flash ($GEMINI_API_KEY) or NVIDIA NIM ($NVIDIA_API_KEY)
• Orchestration, judgment, novel code → Claude

The CLAUDE.md template includes confidence thresholds: 90%+ confidence a cheaper model handles it → auto-dispatch; 70–89% → ask first; below 70% → Claude handles.

Within Claude itself, use Haiku 4.5 for mechanical edits, Sonnet 4.6 for implementation (the default for ~80% of tasks), and Opus 4.8 only for novel architecture or subtle root causes.

How many machines is too many?

There's no hard limit — the git-based inbox scales to as many machines as you have. Practically, coordination overhead grows with fleet size. With 2–5 machines, everything is manual and obvious. With 10+ machines, you'll want to be more deliberate about role specialization (this machine does builds, this one does research, this one handles Telegram) and about what goes in fleet/roster.md so sessions know who to delegate to.

What should I put in the knowledge base?

The rule: "Would another machine or a future session benefit from knowing this?"

Good KB content:

• Reusable patterns and gotchas from hard-won debugging sessions (intelligence/techniques/)
• Architecture decisions with rationale (intelligence/decisions/)
• Project context that would take time to reconstruct (projects/<slug>/)
• Machine capabilities and roles (fleet/roster.md)

Keep out of the KB:

• API keys, passwords, dollar amounts
• Ephemeral session state ("currently on step 3") — that's the session board
• Raw command output — only the lesson, not the evidence
• Who changed what — git log handles that

My inbox items aren't being processed — what should I check first?

1. Machine name mismatch. Run hostname -s on the machine and compare to the inbox filename. If they don't match, set FLEET_MACHINE_NAME in your shell profile or hook environment.
2. KB pull failure. The kb-inbox-check.sh hook does a git pull --rebase before reading. If authentication fails (expired SSH key, wrong remote), the pull fails silently and the inbox looks empty. Run cd ~/knowledge && git pull manually to check.
3. Hook not firing. Verify the hook is in ~/.claude/settings.json and the path to the script is correct. Test with ~/.claude/../claude-fleet/kb-inbox-check.sh directly.
4. Item already claimed. If the trigger file has status: in_progress, check if the claiming PID is still alive (ps -p <claimed_pid>). If not, reset it: ~/claude-fleet/inbox-claim.sh triggers/my-task.md release.

Can I run this without a private git repo? What about a local-only setup?

The system needs some form of shared storage that all machines can read and write. A private git repo on GitHub/GitLab/Gitea is the simplest option. If your machines are on the same network, you could also use a Samba share or NFS mount — the hooks would just use cp instead of git pull/push — but you lose conflict tracking and history. Git is recommended.

How is this different from running Claude in a CI/CD pipeline?

Claude Fleet is for autonomous, persistent agents that accumulate context over time — not for one-shot pipeline tasks. The KB grows with every session. A session that ran last week left context that helps this week's session make better decisions. CI/CD runs are typically stateless. If you need Claude in a pipeline for a specific task, claude -p "do X" --max-turns 5 works fine for that — but you probably don't need Fleet infrastructure for a single repo's CI.