Getting Started with cAgents

Created: March 27, 2026 | Modified: March 27, 2026

This is Part 1 of a 10-part series on cAgents. This article covers installation and setup. Part 2 starts using the tools: /designer - Design Before You Build.

The terminal output shown in walkthroughs throughout this series is illustrative - your actual results will vary in format and content depending on the project.

Most AI tools give you one assistant for one task. You describe what you want, it produces something, you edit it yourself. That model works fine for simple requests. It starts breaking down when tasks are genuinely complex - when "build me a feature" really means plan, design, implement, test, and document, where each phase depends on the last.

cAgents is a multi-agent orchestration framework for Claude Code that handles this kind of work. Instead of one AI doing everything, cAgents coordinates specialized agents - planners, executors, reviewers, domain leads - each focused on what it does best. You describe the outcome you want. cAgents figures out which agents to involve, in what order, and coordinates the work.

This article gets you from zero to running your first task. Installation, configuration, a complete command overview, and a first real example.

Setting Up Claude Code

cAgents runs on top of Claude Code, Anthropic's CLI for running AI agents in your terminal.

Follow the official quickstart guide to install and configure Claude Code: Claude Code Quickstart

Installing cAgents

cAgents is distributed as a Claude Code plugin. Installation is a single command. Full plugin docs: Discover Plugins.

Plugin support requires Claude Code 2.1.69 or later. Run claude --version to check.

Install cAgents:

/plugin install CaelanDrayer/cAgents

That's it. Claude Code pulls the plugin, registers the skills, and makes them available immediately. No separate activation step needed.

Verify the installation:

/cagents:helper "What commands are available?"

If the install worked, cAgents responds with a summary of available commands. The full set - /designer, /run, /team, /org, /optimize, /debug, /review - is now available in any project directory.

You can also install manually by cloning the repository and running ./setup.sh - see the cAgents README for details.

Optional: Install Node.js for smarter hooks. If Node.js is installed on your system, cAgents can use hook scripts that run automatically before and after tasks - validating output, enforcing project conventions, and catching mistakes earlier. Node.js is not required. cAgents works without it. But if you want the plugin running at full capability, it's worth the install.

Setting Up Your Project

If you already have a project, you can use the built-in /init command to generate a CLAUDE.md from your existing codebase. If you're starting from scratch, the /designer command is a great way to think through what you're building before diving in.

Before running any cAgents commands, you should create a CLAUDE.md file in your project root. This file is how you give agents persistent context about your project - what it is, how it's structured, what conventions to follow.

Without a CLAUDE.md, agents have to infer everything from the files they can read. With one, they start with a clear picture of what they're working in.

What Goes in CLAUDE.md

A good CLAUDE.md covers:

Project purpose: one or two sentences on what this project is
Structure: where things live and why
Conventions: naming, file organization, key patterns to follow
Technology: the main stack and any constraints
What not to touch: files or directories that should be off-limits

Example CLAUDE.md -- Technical Project

# CLAUDE.md

## Project
E-commerce site for handmade goods. Built with Next.js 14, TypeScript, and Stripe for payments.

## Structure
- /app - Next.js App Router pages
- /components - shared React components
- /lib - utilities and Stripe integration
- /content - product data as markdown files

## Conventions
- Components: PascalCase, one per file
- Utility functions: camelCase, exported individually
- Never modify /lib/stripe.ts without reviewing the test suite first

## Stack
Next.js 14, TypeScript (strict), Tailwind CSS, Stripe, Vercel deployment

Example CLAUDE.md -- Non-Technical Project

# CLAUDE.md

## Project
Content marketing strategy for a B2B SaaS company selling HR software to mid-market companies.

## Target Audience
HR directors and VPs at companies with 200-2000 employees. They care about compliance,
reducing manual work, and making the case to CFOs.

## Content Pillars
1. Compliance and regulation
2. HR automation and efficiency
3. Employee experience

## Voice
Professional but direct. No buzzwords. Cite sources. Avoid "leverage" and "synergy."

## Deliverables
Blog posts, email sequences, LinkedIn content, and one-pagers for sales.

You don't need a perfect CLAUDE.md on day one. Start with the basics - project purpose, structure, and key conventions - and add to it as you discover what agents need to know. The file improves naturally as you work.

The Commands at a Glance

Command	What It Does	When to Use It
`/designer`	Interactive Q&A that produces an implementation-ready design document	Before starting any non-trivial task - when requirements are vague or you want to think through the approach
`/run`	Executes a task through a coordinated pipeline of specialized agents	Single-domain tasks: implement a feature, write a document, fix a bug, refactor code
`/team`	Runs multiple independent tasks in parallel with wave-based quality gates	When you have 3+ parallelizable items and want them done simultaneously
`/org`	Coordinates C-suite agents across business domains for strategic initiatives	Work that spans 2+ domains - engineering + marketing, sales + support, etc.
`/optimize`	Detects and fixes performance, size, and efficiency issues with before/after metrics	Slow pages, large bundles, low engagement - when you need measurable proof of improvement
`/debug`	Systematic 4-phase debugging when root cause is unclear	Bugs that defy quick fixes, intermittent issues, "I've tried twice and it still fails"
`/review`	Parallel specialist agents review for quality, security, performance, and maintainability	Before merging, after a big refactor, or when you need confidence before going live

What's Next

This series covers each command in depth, with step-by-step walkthroughs following the same two projects through every stage:

Getting Started ← you are here
/designer - Design Before You Build - Interactive Q&A that turns vague requirements into implementation-ready specs. Start here before any non-trivial task.
/run - Execute Tasks with Agents - The workhorse. Give it a task, it plans and executes. Covers the full pipeline, key flags, and follow-up patterns.
/team - Parallel Multi-Agent Execution - Wave-based parallel execution for multiple independent tasks. When and why to use it over /run.
/org - Cross-Domain Orchestration - C-suite agents coordinating across business domains. For work that genuinely spans engineering, marketing, legal, or other domains.
/optimize - Performance and Efficiency - Measurable improvements with before/after metrics and rollback safety.
/debug - Systematic Debugging - 4-phase debugging for issues that defy quick fixes.
/review - Quality Review - Parallel specialist review before you ship.
Sessions - Under the Hood - How cAgents tracks every pipeline run on disk.
Hooks - The Event System - The live event-driven machinery behind every pipeline.

If your project has clear requirements and you're ready to go: start with Part 3: /run. If you want to think through the design first: start with Part 2: /designer.

Part 1 of 10 - cAgents series Next: /designer - Design Before You Build