Claude Code Agents

Claude Code Agent Mode Explained

In a normal interactive session, Claude can read a repository, propose edits, modify files, run allowed commands, and summarize results. Permission mode controls how actions are approved. Plan mode is read-only; default asks as needed; acceptEdits streamlines file changes; auto uses a safety classifier when available; bypassPermissions removes normal safeguards and carries substantial risk.

An agent's effectiveness depends on a clear task, repository instructions, scoped tools, validation commands, and review. Autonomy does not remove the need for acceptance criteria or human responsibility for deployed code.

For installation and startup flags, use the separate Claude Code CLI reference rather than mixing command discovery into agent architecture.

Setting Up agents.md for Custom Behavior

Claude Code does not document a generic agents.md file as its standard configuration. Use CLAUDE.md for persistent project instructions and Markdown files under .claude/agents/ for project-level custom subagents. User-level custom agents can live under ~/.claude/agents/.

A minimal custom reviewer looks like this:

~~~yaml --- name: api-reviewer description: Reviews changed API handlers for compatibility risks tools: Read, Grep, Glob permissionMode: plan --- Report breaking changes, missing validation, and untested failure paths. Do not edit files. ~~~

Choose a precise description because Claude uses it to decide when delegation is appropriate. Keep broad repository conventions in CLAUDE.md rather than copying them into every agent prompt.

Multi-Agent Orchestration Patterns

Use subagents for bounded work that returns to one parent conversation. Use agent view when you want to dispatch and monitor independent background sessions. Use worktrees to isolate file edits. Use agent teams only when workers need shared tasks and direct messaging, and account for their experimental status.

Useful patterns include parallel read-only discovery, sequential specialist review, an implementer followed by an independent verifier, and worktree-isolated changes by subsystem. Avoid splitting tasks that share a tight dependency chain; coordination overhead can exceed any concurrency gain.

Agent Permissions & Safety Controls

Give each agent the smallest useful tool set. A reviewer normally needs Read, Grep, and Glob, not shell writes. Define allow, ask, and deny rules for commands, and keep secrets out of prompts and logs. Treat web content, issue text, and repository files as possible prompt-injection sources.

The --dangerously-skip-permissions flag enables bypassPermissions. It is not a performance switch, and “yolo mode” is an informal community label rather than the official mode name. Run autonomous work in a sandbox, use a non-root account, restrict credentials, and require a final diff and test review.

Parallel Agent Execution Limits

There is no universal published number of Claude Code agents that every account can run. Parallel work increases token consumption and can encounter subscription capacity, API rate limits, machine resources, tool bottlenecks, and merge conflicts. More agents are useful only when the work can be partitioned cleanly.

Start with two independent tasks, measure completion time and review effort, then scale. Put editing workers in separate worktrees. Ask each worker to return a concise artifact so the coordinating context does not fill with repeated logs.

In Verdent

Verdent organizes parallel coding through tasks and workspaces. Tasks have separate conversation context; different workspaces are backed by git worktrees for file isolation. Claude Code offers a broader set of orchestration surfaces inside its own CLI ecosystem, including subagents and experimental teams. Verdent's differentiator is the product workflow for viewing and managing multiple isolated coding tracks, not ownership of Claude or Claude Code.

Sources: Claude Code parallel agents, Claude Code subagents, Claude Code permission modes, Verdent agents.