# Everything Claude Code Agent System Architecture: How Multi-Agent Workflows Work

> Explore the Everything Claude Code agent system architecture. Understand how declarative markdown-based agents and multi-agent workflows orchestrate tasks efficiently for complex development.

- Repository: [WorldFlowAI/everything-claude-code](https://github.com/WorldFlowAI/everything-claude-code)
- Tags: architecture
- Published: 2026-09-07

---

**Everything Claude Code uses a declarative, markdown-based agent architecture where autonomous agents are defined in the `agents/` directory and orchestrated through CLI commands in `commands/`, with shared context managed via hooks.**

The **agent system architecture** in Everything Claude Code enables complex AI-driven workflows by treating each specialized capability—planning, architecture, code review, security—as a modular, self-contained agent. This design, as implemented in [WorldFlowAI/everything-claude-code](https://github.com/WorldFlowAI/everything-claude-code), separates agent definition from orchestration, making the system transparent and extensible.

## Agent Definition: Declarative Markdown Files

Every agent is declared in a markdown file inside the **`agents/`** directory. The front-matter block specifies the agent's identity and capabilities:

- **`name`** — unique identifier used by the orchestrator
- **`description`** — concise purpose statement
- **`tools`** — available low-level operations (`Read`, `Grep`, `Glob`)
- **`model`** — which Claude model powers the agent (`opus`, `sonnet`, `haiku`)

The **Architect** agent at [`agents/architect.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/agents/architect.md) demonstrates the full template. Beyond front-matter, each file details:

- Concrete responsibilities (design, review, planning)
- Step-by-step workflows (e.g., "Architecture Review Process")
- Checklists of **Architectural Principles**
- Common **Patterns** and anti-patterns
- Templates for **Architecture Decision Records (ADRs)**

## The Orchestration Layer

CLI commands in **`commands/`** instantiate and run agents. Key commands include:

| Command | Purpose | Agent Used |
|---------|---------|------------|
| `plan` | Create task breakdowns | [`planner.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/planner.md) |
| `orchestrate` | Chain multiple agents | Multiple |
| `code-reviewer` | Validate implementation | [`code-reviewer.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/code-reviewer.md) |

The orchestrator reads agent definitions, constructs Claude API requests using the specified `model`, and manages the interaction flow.

### Execution Flow

```bash

# User initiates a planning session

opencode plan --project my-app --output plan.json

```

Internally, as implemented in [`commands/plan.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/commands/plan.md):

```javascript
// Pseudocode reflecting actual implementation
const agentDef = await readAgent('agents/planner.md');
const response = await claude.run({
  model: agentDef.model,
  prompt: `${agentDef.description}\n${taskSpecification}`
});
saveSession(response);

```

## Shared Context and Memory Persistence

Agents operate on **shared session context** managed by the hooks system. The [`hooks/hooks.json`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/hooks/hooks.json) registry maps hook events to scripts in `hooks/`.

**Memory-persistence hooks** handle session lifecycle:

```bash

# hooks/memory-persistence/session-start.sh

#!/usr/bin/env bash
SESSION_ID=$(uuidgen)
export CLAUDE_SESSION_ID=$SESSION_ID
mkdir -p .claude/sessions/$SESSION_ID

```

Additional hooks include:

- [`session-end.sh`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/session-end.sh) — finalize and archive session state
- [`pre-compact.sh`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/pre-compact.sh) — compress context before token limits

This shared context enables **multi-agent collaboration**:

```javascript
// orchestrate.js simplified flow
const plan = await runAgent('planner');
const architecture = await runAgent('architect', { plan });
const review = await runAgent('code-reviewer', { architecture });

```

## Extending the System

Adding a new agent requires only:

1. Create [`agents/your-agent.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/agents/your-agent.md) with front-matter and role description
2. The orchestrator auto-discovers it via directory scan
3. Reference it in CLI commands or orchestration workflows

No code changes to the core system are needed.

## Key Files in the Architecture

| File Path | Role |
|-----------|------|
| [`agents/architect.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/agents/architect.md) | Reference agent with full workflow template |
| [`agents/planner.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/agents/planner.md) | Task decomposition specialist |
| [`agents/code-reviewer.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/agents/code-reviewer.md) | Implementation validator |
| [`agents/security-reviewer.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/agents/security-reviewer.md) | Security-focused reviewer |
| [`commands/orchestrate.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/commands/orchestrate.md) | Multi-agent chaining command |
| [`commands/plan.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/commands/plan.md) | Planning workflow entry point |
| [`hooks/hooks.json`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/hooks/hooks.json) | Hook event registry |
| `hooks/memory-persistence/*.sh` | Session context management |
| [`scripts/lib/utils.js`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/scripts/lib/utils.js) | Shared utilities |

## Summary

- **Agent definitions** live as markdown in `agents/` with declarative front-matter
- **Orchestration commands** in `commands/` load agents and drive Claude API calls
- **Hooks in `hooks/`** manage persistent shared context across sessions
- **Multi-agent workflows** chain outputs: Planner → Architect → Reviewer
- **Extensibility** is file-based: add markdown, gain new capabilities

## Frequently Asked Questions

### What makes an agent "autonomous" in Everything Claude Code?

An agent is autonomous because it carries its own decision-making framework—defined in its markdown description and responsibilities—rather than following hardcoded logic. The orchestrator provides the prompt and context, but the agent's response strategy (how it plans, reviews, or designs) emerges from its documented role and the Claude model's reasoning.

### How does context pass between multiple agents?

Context passes through the **session persistence layer**. When `runAgent('architect', { plan })` executes, the `plan` object serializes to the session directory under `.claude/sessions/$SESSION_ID/`. Hook scripts ensure this state survives across process boundaries. Downstream agents read this shared context, building on previous outputs without direct coupling.

### Can I use different Claude models for different agents?

Yes—the `model` front-matter field specifies which Claude model each agent uses. According to the [`agents/architect.md`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/agents/architect.md) source, the Architect uses `opus` for complex reasoning, while lighter tasks might use `haiku`. The orchestrator respects this per-agent configuration when constructing API requests.

### What happens if a session exceeds token limits?

The [`pre-compact.sh`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/pre-compact.sh) hook triggers before context overflow. This script, located at [`hooks/memory-persistence/pre-compact.sh`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/hooks/memory-persistence/pre-compact.sh), summarizes or truncates session history based on configurable heuristics, preserving critical decision points while freeing token budget for continued agent interaction.