Claude Code Hooks and Multi-Agent Coordination: Building a Development Platform

1. Hooks Primer: Lifecycle Events for Agent Control

Claude Code hooks are scripts that execute at specific points in the agent's lifecycle. They are configured in your project's .claude/settings.json and run as subprocesses, receiving context about the current operation via stdin as JSON. There are four lifecycle events that matter for multi-agent coordination: PreToolUse fires before any tool call, PostToolUse fires after a tool completes, Notification fires when the agent wants to communicate something, and Stop fires when the agent finishes its task.

The critical hook for multi-agent work is PreToolUse on file write operations. This is where you intercept an agent's attempt to modify a file and check whether another agent is currently working on the same file. Without this check, two agents editing the same file will silently overwrite each other's changes. The agent that writes last wins, and the other agent's work disappears without any error.

A basic PreToolUse hook for file locking checks a lock file directory, looks for an active lock on the target file, and returns a non-zero exit code if the file is locked by a different agent. Claude Code interprets the non-zero exit code as a signal to abort the tool call, and the hook's stderr output is shown to the agent as an error message so it can decide how to proceed.

2. Preventing Agents from Stomping Changes

File-level locking is the simplest coordination mechanism, but it is not sufficient for real multi-agent workflows. Agents working on related features might need to modify the same files, like shared type definitions, configuration files, or routing tables. A strict file lock would force sequential execution, defeating the purpose of parallel agents.

The more practical approach is scope-based coordination. Each agent gets assigned a working scope, a set of directories or file patterns that it owns. Agent A owns src/features/auth/**, Agent B owns src/features/billing/**, and shared files like src/types/index.ts are handled through a merge queue. When an agent needs to modify a shared file, the hook appends its changes to a pending queue instead of writing directly. A separate reconciliation process merges pending changes in order.

Git worktrees provide another isolation layer. Instead of running multiple agents in the same working directory, each agent operates in its own worktree branched from the same base. This gives complete filesystem isolation. Agents cannot stomp each other's changes because they are literally working in different directories. The coordination happens at merge time, where standard git merge resolution applies.

3. Custom Skills: Giving Agents Specialized Abilities

Claude Code skills are markdown files that provide instructions, context, and tool configurations for specific tasks. A skill file lives in your project's .claude/ directory and gets loaded when an agent invokes it. The power of skills for multi-agent coordination is that each agent can have its own set of skills that define its role, constraints, and capabilities.

A frontend agent might have a skill that includes your design system tokens, component library documentation, and instructions for running visual regression tests. A backend agent might have a skill with database schema documentation, API design conventions, and instructions for running integration tests. A QA agent might have a skill focused on writing test scenarios, running the full test suite, and reporting failures back to the other agents.

The skill system also supports parameterization. You can write a generic "implement feature" skill that takes a spec file path as input, reads the specification, and follows a defined workflow: create a branch, implement the changes, run tests, and create a pull request. This turns feature implementation into a repeatable, automated process where the human provides the specification and the agent handles everything else.

4. Orchestration Patterns for Parallel Agents

The simplest orchestration pattern is fan-out/fan-in. A coordinator process splits a set of tasks, launches one agent per task, and waits for all of them to complete. This works well for independent tasks like writing tests for different modules, implementing unrelated features, or running parallel code reviews. The coordinator collects results and either merges them automatically or flags conflicts for human review.

A more sophisticated pattern is the pipeline. Agent A generates a specification, Agent B implements it, Agent C writes tests, and Agent D performs code review. Each agent's output becomes the next agent's input. Hooks on the Stop lifecycle event trigger the next agent in the pipeline. This mimics a traditional development workflow but compresses the timeline from days to minutes.

The most complex pattern is the swarm, where agents communicate with each other through shared state. An agent working on the API layer publishes its endpoint signatures to a shared specification file. A frontend agent watches that file and generates client code as endpoints become available. A test agent watches both and generates integration tests. This requires careful hook design to avoid race conditions, but it produces the fastest end-to-end development cycle.

5. Building a Development Platform on Claude Code

When you combine hooks, skills, MCP servers, and orchestration scripts, Claude Code becomes less of a coding assistant and more of a development platform. The CLAUDE.md file at your project root acts as the platform's configuration, defining conventions, tool access, and workflow rules that every agent follows.

A well-configured Claude Code platform includes project-level CLAUDE.md with architecture conventions, coding standards, and operational rules. It includes skill files for each role (frontend, backend, devops, QA). It includes hooks for file locking, pre-commit validation, test execution, and deployment gating. It includes MCP servers for accessing external tools like databases, monitoring systems, and deployment pipelines. And it includes orchestration scripts that launch, monitor, and coordinate multiple agents.

The platform approach also extends beyond code generation. Desktop automation tools like Fazm, an AI computer agent for macOS that is voice-first, open source, and uses accessibility APIs, can complement Claude Code by handling tasks that require interacting with desktop applications, running GUI tests, or automating workflows that span multiple tools outside the terminal.

6. Failure Modes and How to Handle Them

Multi-agent systems fail in ways that single-agent systems do not. The most common failure is a silent merge conflict where two agents modify related code in incompatible ways that both pass their individual tests but break when combined. The fix is an integration test suite that runs after merging all agent branches, with a PostToolUse hook that triggers it automatically.

Another common failure is context drift. Agent A modifies a shared interface, but Agent B started before the change and is working against the old interface. When Agent B's changes land, they reference types that no longer exist. The prevention strategy is a hook that checks whether the agent's base commit is still current before allowing file writes. If the base has changed, the hook forces the agent to pull the latest changes before continuing.

Resource exhaustion is a less obvious failure. Each Claude Code agent consumes API tokens, and five agents running in parallel consume five times the tokens. Without cost monitoring hooks, a runaway agent can burn through your API budget before you notice. A simple PostToolUse hook that tracks cumulative token usage per agent session and halts the agent when it exceeds a threshold prevents this.

7. Practical Setup: From Zero to Multi-Agent

Start with two agents, not five. The coordination overhead scales non-linearly, and starting small lets you debug your hooks and skills before the complexity becomes unmanageable. Run one agent on frontend work and one on backend work with a clear directory boundary between them. Add file locking hooks for any shared files.

Write your CLAUDE.md to be agent-friendly. This means explicit rules instead of implicit conventions. Instead of "follow our coding style," list the specific rules: use named exports, use async/await instead of promises, put types in src/types/, and run tests before committing. Agents follow instructions literally, so vague guidance produces inconsistent output.

Build monitoring early. A simple dashboard that shows which agents are running, what files they are modifying, and their token consumption prevents most multi-agent problems before they become expensive. The Notification hook is useful here, as each agent can report its status to a shared log that your dashboard reads.

Test your coordination system with low-stakes tasks before trusting it with production features. Have two agents independently refactor different modules and verify that the merge is clean. Have a pipeline of agents implement, test, and review a simple feature. Build confidence in the system before scaling it up.