Skip to content

Instantly share code, notes, and snippets.

@raoulbia-ai

raoulbia-ai/claude-flow-codespace-setup-guide.md

Last active September 18, 2025 07:53
Show Gist options
  • Save raoulbia-ai/ec00967e8d9da4cfec22371655972acf to your computer and use it in GitHub Desktop.
Save raoulbia-ai/ec00967e8d9da4cfec22371655972acf to your computer and use it in GitHub Desktop.
Download ZIP
Complete setup guide for Claude-Flow AI agent swarms in GitHub Codespaces. Includes universal dev container config for Docker/Kubernetes/Codespaces, authentication workflow, and community-tested troubleshooting. Based on AI Code Chat community discussions.
Raw
claude-flow-codespace-setup-guide.md

Complete Claude-Flow Setup Guide for GitHub Codespaces

A comprehensive guide to setting up and using Claude-Flow with swarms in GitHub Codespaces, based on real community discussions and proven workflows.

Table of Contents

  1. Overview
  2. Prerequisites & Setup
  3. Step-by-Step Installation
  4. Authentication Workflow
  5. Getting Started with Swarms
  6. Frequently Asked Questions
  7. Advanced Configuration
  8. Troubleshooting

Overview

What is Claude-Flow?

Claude-Flow is an enterprise-grade AI orchestration platform created by rUv (@ruvnet) and agentics.org that coordinates multiple Claude Code instances to create powerful "swarms" of AI agents working together on complex development tasks.

Repository: https://github.com/ruvnet/claude-flow

Universal Dev Container Configuration

The multi-platform dev container configuration in this guide was contributed by Jed (@jedarden) and works seamlessly across:

  • Local Docker instances
  • Kubernetes clusters
  • GitHub Codespaces

A comprehensive resource from the author can be found here: jedarden/agentists-quickstart

Key Capabilities

  • 🐝 Advanced Swarm Orchestration: Deploy up to 100+ AI agents simultaneously
  • 🧠 Distributed Memory Sharing: Cross-agent knowledge sharing with persistent state
  • ⚡ Intelligent Task Scheduling: 7+ scheduling algorithms with load balancing
  • 🔄 Multi-Agent Coordination: Specialized agents for different development roles
  • 📊 Real-Time Monitoring: Comprehensive metrics and performance tracking

Architecture

┌─────────────────────────────────────────────────────────┐
│ Claude-Flow Orchestrator                                │
├─────────────────────────────────────────────────────────┤
│ Agent 1 Agent 2 Agent 3 Agent 4 Agent 5                │
│ Architect │ Coder │ TDD │ Security │ DevOps             │
├─────────────────────────────────────────────────────────┤
│ Shared Memory Bank & Coordination                       │
├─────────────────────────────────────────────────────────┤
│ Claude Code Integration Layer                           │
└─────────────────────────────────────────────────────────┘

Prerequisites & Setup

System Requirements

  • GitHub account with Codespaces access
  • Claude subscription (Pro or Max recommended for swarms)
  • Basic understanding of terminal commands

GitHub Codespaces Terms Compliance

✅ This setup is fully compliant with GitHub Codespaces terms of service:

  • Used for legitimate software development
  • No prohibited activities (mining, malware, etc.)
  • Within resource usage guidelines
  • Follows security best practices

Step-by-Step Installation

Step 1: Create Dev Container Configuration

In your blank repository, create the necessary directory and file.

Copy and paste this single command into your terminal:

mkdir -p .devcontainer && curl -o .devcontainer/devcontainer.json https://gist.githubusercontent.com/raoulbia-ai/29be17f83f5d8101e7b09036b75678c6/raw/devcontainer.json

Step 2: Commit and Push Configuration

git add .devcontainer/devcontainer.json
git commit -m "Add Claude-Flow dev container configuration"
git push origin main

Step 3: Rebuild Codespace

  1. Press Ctrl+Shift+P (Command Palette)
  2. Search for "Codespaces: Rebuild Container"
  3. Select and confirm rebuild
  4. Wait for container to rebuild with new configuration

Step 4: Verify Installation

# Check Node.js
node --version

# Check Python
python --version

# Check Claude-Flow (should show v2.0.0+ enterprise version)
claude-flow --help

# Check Claude Code (command is 'claude', not 'claude-code')
claude --version

# Check Docker
docker --version

Expected output:

  • Node.js: v22.17.1+
  • Python: 3.11.2+
  • Claude-Flow: v2.0.0-alpha.53+ (Enterprise version)
  • Claude: 1.0.56+ (Claude Code)
  • Docker: 28.3.2+

Authentication Workflow

Critical Authentication Steps

⚠️ Important: You MUST authenticate Claude first before using Claude-Flow. This is confirmed by community testing.

Step 1: Authenticate Claude

# Start Claude and authenticate
claude --dangerously-skip-permissions
  • Complete the login process with your Anthropic account
  • Choose subscription (default) or API key option
  • Exit Claude after authentication completes

Step 2: Why Exit Claude?

Authentication persists in secure storage (keychain/auth files) after exit:

  • ~/.claude/ - Session data and configurations
  • macOS Keychain or ~/.config/claude-code/auth.json - Secure tokens
  • Claude-Flow can access stored authentication without re-login
  • Prevents conflicts between interactive Claude and swarm orchestration

Step 3: Initialize Claude-Flow

# Initialize with SPARC methodology
claude-flow init --sparc

This creates:

  • ✓ .claude/ directory with configuration
  • ✓ CLAUDE.md (project instructions)
  • ✓ .roomodes (17 pre-configured SPARC modes)
  • ✓ Swarm command documentation

Getting Started with Swarms

Basic Swarm Commands

Simple Swarm Test

claude-flow swarm "create a simple hello world application"

Two-Phase Development (Recommended)

# Phase 1: Research
claude-flow swarm "research how to build a web app that does X. Put findings in project-requirements.md" --parallel

# Phase 2: Implementation  
claude-flow swarm "implement the application described in project-requirements.md" --parallel

Advanced Swarm with Options

claude-flow swarm "build full-stack web application with authentication" \
  --max-agents 10 \
  --strategy development \
  --parallel \
  --monitor

Agent Number Control

Default and Recommendations

  • Default: 5 agents (--max-agents 5)
  • Beginner: 5-7 agents (safe, prevents rate limiting)
  • Intermediate: 10-15 agents (proven sweet spot)
  • Advanced: 20+ agents (resource intensive)
  • Rate Limit: ~42-50 agents (community-tested maximum)

Scaling Guidelines

# Conservative start
claude-flow swarm "simple task" --max-agents 5

# Medium complexity
claude-flow swarm "moderate task" --max-agents 10

# Complex projects
claude-flow swarm "complex task" --max-agents 15 --strategy development

SPARC vs Basic Swarms

With SPARC (Recommended)

  • ✅ 17 specialized agent roles (Architect, Coder, TDD, Security, DevOps)
  • ✅ Structured development methodology
  • ✅ Better coordination and proven patterns
  • ✅ More community examples and support

Without SPARC (Alternative)

claude-flow init --force  # Basic swarms without SPARC methodology

Frequently Asked Questions

Q: Do I need Claude-Code for swarms to work?

A: Yes, absolutely. Claude-Flow is an orchestration layer that coordinates multiple Claude-Code instances. The relationship is:

  • Claude-Code = Individual AI coding agent
  • Claude-Flow = Orchestration platform that manages multiple Claude-Code agents
  • Swarms = Multiple Claude-Code agents coordinated by Claude-Flow

Q: Is the command claude or claude-code?

A: The command is claude (not claude-code). While the npm package is @anthropic-ai/claude-code, the actual command is claude.

Q: Do I need to start Claude first before running claude-flow commands?

A: Yes, for authentication only. The workflow is:

  1. claude --dangerously-skip-permissions (authenticate)
  2. Exit Claude (authentication persists)
  3. claude-flow init --sparc (initialize)
  4. claude-flow swarm "task" (run swarms)

Q: If I logout of Claude, how does claude-flow authenticate?

A: Authentication persists after logout. Tokens are stored in:

  • macOS Keychain (secure storage)
  • ~/.claude/ session files
  • ~/.config/claude-code/auth.json Claude-Flow accesses these stored credentials without re-authentication.

Q: Is SPARC required for swarms?

A: No, but highly recommended. You can run basic swarms with claude-flow init --force, but SPARC provides:

  • Better structure and coordination
  • 17 specialized agent roles
  • Proven community patterns
  • More examples and documentation

Q: Can I control the number of swarm agents?

A: Yes, with --max-agents parameter:

  • Default: 5 agents
  • Community sweet spot: 10-15 agents
  • Rate limit threshold: ~42-50 agents
  • Start with 5, scale up based on performance

Q: Does this violate GitHub Codespaces terms?

A: No, this is fully compliant. The setup is for legitimate software development, uses standard tools, and falls within usage guidelines.

Q: What's the difference between Claude-Flow and regular Claude?

A: Scale and coordination:

  • Claude = Single interactive AI agent
  • Claude-Flow = Orchestrates multiple Claude agents working together
  • Benefits = Parallel development, specialized roles, complex project coordination

Q: Are swarms different from claude-flow?

A: Swarms are a feature within Claude-Flow. They're not separate tools:

  • Claude-Flow = Overall orchestration platform
  • Swarms = Multi-agent coordination mode within Claude-Flow
  • Usage = claude-flow swarm "task" deploys coordinated agents

Q: Can I experiment with swarms using the dev container setup?

A: Yes, perfectly! The dev container provides:

  • ✅ All necessary tools pre-installed
  • ✅ Docker-in-Docker for advanced orchestration
  • ✅ Isolated cloud environment
  • ✅ No local resource constraints

Advanced Configuration

Hive Mind System (Enterprise Features)

Your installation includes advanced Hive Mind capabilities:

# Interactive setup wizard
claude-flow hive-mind wizard

# Create intelligent swarm with objective
claude-flow hive-mind spawn "build complex application"

# View active swarms and metrics
claude-flow hive-mind status
claude-flow hive-mind metrics

Full Swarm Options

claude-flow swarm "objective" \
  --strategy <type>          # auto, research, development, analysis
  --mode <type>              # centralized, distributed, hierarchical
  --max-agents <n>           # Maximum agents (default: 5)
  --timeout <minutes>        # Timeout in minutes (default: 60)
  --parallel                 # Enable parallel execution
  --distributed              # Enable distributed coordination
  --monitor                  # Enable real-time monitoring
  --ui                       # Launch terminal UI interface
  --background               # Run in background mode
  --verbose                  # Enable detailed logging

Memory and Coordination

Swarms create coordination directories:

  • memory/ - Cross-agent knowledge sharing
  • coordination/ - Agent coordination state
  • Important: Don't add these to .gitignore

Troubleshooting

Authentication Issues

# Reset authentication if problems persist
rm -rf ~/.config/claude-code/auth.json
claude --dangerously-skip-permissions

Installation Problems

# Verify installation locations
which claude-flow
which claude

# Reinstall if needed
npm install -g claude-flow @anthropic-ai/claude-code

Rate Limiting

  • Reduce --max-agents number
  • Use --timeout to limit session length
  • Monitor usage with Claude subscription limits

Resource Constraints

  • Start with fewer agents (5-7)
  • Monitor Codespace CPU/memory usage
  • Use --background mode for long-running tasks

Common Error Solutions

"claude-code: command not found"

  • ✅ Command is claude, not claude-code

"OAuth account information not found"

  • ✅ Run claude --dangerously-skip-permissions first
  • ✅ Complete authentication before claude-flow

"Credit balance too low"

  • ✅ Usually authentication issue, not credits
  • ✅ Ensure proper Claude subscription authentication

Community Resources

Success Stories

  • 12-hour autonomous development: 100M tokens, 38,000 lines of code, $68 cost
  • Client projects: "Several months" → completed in hours/days
  • 100% test coverage: Automated testing and documentation

Community Links

  • AI Code Chat WhatsApp: Technical discussions and troubleshooting
  • General AI Chat WhatsApp: Broader AI concepts and trends
  • GitHub Repository: https://github.com/ruvnet/claude-flow
  • SPARC Methodology: Comprehensive development framework

Quick Start Summary

  1. Create dev container with provided configuration
  2. Rebuild Codespace to install tools
  3. Authenticate Claude: claude --dangerously-skip-permissions
  4. Initialize Claude-Flow: claude-flow init --sparc
  5. Test basic swarm: claude-flow swarm "create hello world app" --max-agents 5
  6. Scale up gradually based on performance and resources

You're now ready to orchestrate AI agent swarms for autonomous development! 🚀

This guide is based on real community discussions, proven workflows, and successful implementations from the AI Code Chat WhatsApp group.

@Kalle80
Copy link

Kalle80 commented Sep 14, 2025

Why you have the /project as a starting folder? Why just not use the workspace root?

@raoulbia-ai
Copy link
Author

Why you have the /project as a starting folder? Why just not use the workspace root?

Hi, I agree it is not strictly necessary and probably not that useful. Background: I was trying to keep project files separate from "system files" generated by the claude-flow install. I will look into it when I get a chance. Thanks for the feedback.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment