How to Run Multiple Claude Code Agents Together with Crewly

Claude Code is powerful on its own. But what if you could run multiple Claude Code instances as a coordinated team — with a backend developer, a frontend developer, and a QA engineer all working on the same project simultaneously?

That's exactly what Crewly does. Crewly is an open-source AI agent orchestration platform that launches multiple Claude Code instances, assigns each one a specialized role, and coordinates their work through a real-time web dashboard.

In this tutorial, you'll set up a 3-agent development team and watch them collaborate on a real project.

Crewly is an open-source platform that orchestrates multiple Claude Code instances as a coordinated team. Each agent gets a specialized role (backend developer, frontend developer, QA engineer), runs in its own terminal session, and communicates through structured bash skills. A web dashboard provides real-time terminal streams, task tracking, and agent status monitoring.

What You'll Build

By the end of this tutorial, you'll have:

• A running Crewly instance with a web dashboard
• A team of 3 Claude Code agents (backend dev, frontend dev, QA engineer)
• Agents assigned to a real project directory
• Real-time monitoring of all agents from a single browser tab

Prerequisites

Before starting, make sure you have:

• Node.js v20+ — Check with node --version
• Claude Code CLI — The Anthropic coding assistant

Install Claude Code if you haven't already:

npm install -g @anthropic-ai/claude-code
claude --version

Step 1: Install and Launch Crewly

Install Crewly globally and start it:

npm install -g crewly
npx crewly start

This starts the Crewly backend server and opens the web dashboard in your browser at http://localhost:3000.

You'll see the dashboard with an empty state — no teams or projects yet. That's about to change.

Step 2: Create a Project

First, tell Crewly which codebase your agents will work on.

1. Go to the Projects page from the sidebar
2. Click "New Project"
3. Fill in:
   • Name: e.g., "My Web App"
   • Path: The absolute path to your project directory (e.g., /Users/you/projects/my-web-app)
   • Description (optional): A brief note about the project
4. Click Create

Crewly creates a .crewly/ directory inside your project folder to store tasks, agent memory, and coordination files.

Step 3: Create Your Agent Team

Now create a team of 3 Claude Code agents, each with a specialized role.

1. Go to the Teams page
2. Click "New Team"
3. Set the team name: e.g., "Web App Squad"
4. Assign it to the project you just created
5. Add 3 team members:

For each member:

• Type a name in the Agent Name field
• Select the Role from the dropdown
• Leave Runtime as "Claude Code" (the default)
• Optionally pick an Avatar

6. Click Create Team

Each role comes with a pre-built system prompt that tells the agent how to behave. The backend developer knows to focus on APIs and server code. The QA engineer knows to write tests and review for bugs. You don't need to write any prompts yourself.

Step 4: Start the Team

With the team created, it's time to launch the agents.

1. Open your team (click on it from the Teams page)
2. Click the "Start Team" button
3. Watch the agent status indicators change:
   • inactive → starting → active

Behind the scenes, Crewly is:

1. Opening a PTY terminal session for each agent
2. Running claude --dangerously-skip-permissions in each session
3. Injecting the role-specific system prompt
4. Waiting for each agent to signal readiness
5. Registering each agent on the dashboard

Within 30-60 seconds, all 3 agents should show as active on the dashboard.

Step 5: Delegate Tasks

Now you can assign work to your agents. There are two ways to do this:

Option A: Via Chat UI

Go to the Chat page. You'll see a conversation interface connected to the Crewly orchestrator. Type a natural language request:

Build a REST API with user authentication. The backend dev should handle
the Express routes, the frontend dev should build a login page, and QA
should write integration tests.

The orchestrator will break this down and delegate to each agent automatically.

Option B: Via the Orchestrator's Skills

If you have an orchestrator agent running, it can delegate tasks programmatically:

bash config/skills/orchestrator/delegate-task/execute.sh '{
  "to": "web-app-squad-backend-dev",
  "task": "Create Express.js REST API with /auth/login and /auth/register endpoints using JWT tokens",
  "priority": "high",
  "projectPath": "/Users/you/projects/my-web-app"
}'

Each agent receives the task in their terminal session and begins working immediately.

Step 6: Monitor Progress in Real Time

Go back to the Dashboard or Team Detail page. You'll see:

• Agent status cards — Each agent shows whether they're idle or working
• Live terminal streams — Click on any agent to see their terminal output in real time
• Task progress — Track which tasks are open, in progress, or done
• Working status — See at a glance who's busy and who's idle

Agents report their progress back automatically. When an agent finishes a task, it runs:

bash config/skills/agent/report-status/execute.sh '{
  "sessionName": "web-app-squad-backend-dev",
  "status": "done",
  "summary": "Created /auth/login and /auth/register endpoints with JWT authentication"
}'

This updates the dashboard and notifies the orchestrator, who can then assign the next task.

How Agents Communicate

Agents don't talk to each other directly. Instead, they communicate through Crewly's backend using bash skills — small scripts that call the Crewly API.

Key communication skills:

This architecture means agents are completely decoupled. Each one runs in its own terminal session and communicates through structured API calls. No shared memory, no race conditions, no conflicts.

Built-in Roles

Crewly includes 14 pre-built roles, each with a tailored system prompt:

You can also create custom roles by adding a new directory under config/roles/ with a prompt.md file.

Tips for Effective Multi-Agent Teams

Start small. A 2-3 agent team is easier to coordinate than 6+. Begin with a developer and a QA engineer — that alone is a powerful combination.

Use the orchestrator. The orchestrator agent has 48+ skills to manage teams, delegate tasks, monitor progress, and react to events. Let it coordinate rather than manually assigning everything.

Leverage persistent memory. Agents can remember patterns and decisions across sessions. Over time, your team gets smarter about your codebase.

Mix runtimes if needed. While this tutorial uses all Claude Code agents, Crewly also supports Gemini CLI and OpenAI Codex. You can mix runtimes in the same team — for example, Claude Code for backend and Gemini CLI for frontend.

What's Next

• Getting started in 60 seconds — A faster quickstart if you want the shortest path to a running team
• Add Slack integration — Talk to your team through Slack instead of the Chat UI
• Set up the knowledge base — Store architecture docs and SOPs that agents can query
• Try mixed runtimes — Add a Gemini CLI or Codex agent to the same team
• Explore the Marketplace — Install community-built skills and role configurations
• Schedule automated check-ins — Have the orchestrator check on agents periodically
• See how Crewly compares to CrewAI — Understand the differences between these two multi-agent approaches

Quick Reference

# Install
npm install -g crewly

# Start (opens dashboard)
npx crewly start

# Start without opening browser
npx crewly start --no-browser

# Start on a custom port
npx crewly start --port 3001

Crewly is open source under the MIT license. Star the project on GitHub and join the community.