Agents
CodeForge provides 21 specialized agents, each configured with a focused system prompt, specific tool access, and domain expertise. Claude automatically delegates to the appropriate agent based on your request — ask about architecture and you get the architect; ask for a security review and you get the security auditor.
How Agents Work
Section titled “How Agents Work”Each agent is defined as a Markdown file in the agent system plugin’s agents/ directory. The file contains a YAML frontmatter header specifying the agent’s name, tools, model, permission mode, and associated skills, followed by a detailed system prompt that shapes the agent’s behavior, expertise, and constraints.
When Claude receives your request, the agent system evaluates which specialist best matches your intent and spawns that agent as a subagent. The specialist operates within its defined boundaries — a read-only agent cannot modify files, and a full-access agent in a worktree cannot touch your main branch.
Built-In Agents, Replaced and Upgraded
Section titled “Built-In Agents, Replaced and Upgraded”Claude Code ships with six built-in agent types: Explore, Plan, general-purpose, Bash, claude-code-guide, and statusline-setup. These are functional but generic — they carry no domain skills, have no safety hooks, and run with default tool access.
CodeForge entirely replaces all six built-in agents with enhanced custom specialists. This happens transparently through a PreToolUse hook that intercepts every agent spawn request and redirects it before execution. You never interact with a stock agent — every request is silently upgraded to a purpose-built specialist with frontloaded skills, calibrated model selection, and hook-based safety enforcement.
| Built-In Agent | Replaced By | What Changes |
|---|---|---|
Explore | explorer | Haiku model for speed, ast-grep patterns skill, read-only enforcement |
Plan | architect | Opus model for deep reasoning, api-design skill, structured 4-phase workflow |
general-purpose | generalist | Full skill stack, spec workflow integration, plan mode support |
Bash | bash-exec | Git safety protocols, path quoting enforcement, command validation |
claude-code-guide | claude-guide | Pre-loaded Claude SDK and headless mode skills, documentation-first approach |
statusline-setup | statusline-config | Sonnet model, focused tool access for status line configuration |
The redirect is fully transparent — you can use either the built-in name or the custom name interchangeably. Asking Claude to “explore the codebase” triggers the same enhanced explorer agent whether the system selects the Explore type or the explorer type.
Beyond the six replacements, CodeForge adds 15 entirely new specialists that have no built-in equivalent: debug-logs, dependency-analyst, doc-writer, documenter, git-archaeologist, implementer, investigator, migrator, perf-profiler, refactorer, researcher, security-auditor, spec-writer, tester, and test-writer. These are available only in CodeForge.
Key Properties
Section titled “Key Properties”Every agent definition includes:
- Tools — which Claude Code tools the agent can use (Read, Write, Edit, Bash, Glob, Grep, WebSearch, etc.)
- Model — which Claude model powers the agent (opus, sonnet, or haiku)
- Permission mode —
plan(read-only),acceptEdits(can write with approval), ordefault(full access) - Isolation — some agents run in git worktrees so their changes are isolated from your working branch
- Background — some agents run asynchronously, returning results while you continue working
- Skills — domain knowledge packs automatically loaded for the agent
- Memory — whether the agent remembers context across sessions (project-scoped or user-scoped)
Agent Reference
Section titled “Agent Reference”architect
Section titled “architect”Read-only Opus api-design
A senior software architect that designs implementation plans, analyzes trade-offs, and identifies critical files for proposed changes. The architect follows a structured four-phase workflow: understand requirements, explore the codebase, analyze and design, then structure the plan. It produces detailed implementation plans with phased steps, risk assessments, and testing strategies — but never modifies any files.
When activated: Architecture questions, design reviews, “plan the implementation,” “how should we architect this,” system structure analysis.
bash-exec
Section titled “bash-exec”Full Sonnet
A command execution specialist for terminal operations. Handles git operations, build commands, test execution, process management, and complex shell scripting. Follows strict git safety protocols — never force-pushes, never amends without explicit permission, always quotes paths with spaces.
When activated: Shell scripting tasks, git operations, build automation, “run this command.”
claude-guide
Section titled “claude-guide”Read-only Haiku claude-code-headless claude-agent-sdk
Your go-to expert for questions about Claude Code itself, the Claude Agent SDK, and the Claude API. Provides documentation-based guidance with specific examples and configuration snippets. Proactively suggests related features you might find useful.
When activated: Questions about Claude Code features, “how do I configure hooks,” “how do I use the Agent SDK,” “can Claude do X.”
debug-logs
Section titled “debug-logs”Read-only Sonnet debugging
A log analysis specialist that finds and analyzes log files across Docker containers, application frameworks, and system services. Follows a priority-based discovery strategy — Docker container logs first, then application log files, then system logs. Establishes chronology across sources to identify root causes in error cascades.
When activated: Debugging sessions, “check the container logs,” “why did this crash,” error investigation, log analysis.
dependency-analyst
Section titled “dependency-analyst”Read-only Haiku dependency-management
Analyzes project dependencies for outdated packages, security vulnerabilities, version conflicts, unused dependencies, and license compliance issues. Supports Node.js, Python, Rust, and Go ecosystems. Runs in the background so you get results without waiting.
When activated: “Check for outdated dependencies,” “audit dependencies,” “npm audit,” “pip audit,” dependency health checks.
doc-writer
Section titled “doc-writer”Full (worktree) Opus documentation-patterns
A technical writing specialist that creates and maintains README files, API documentation, inline comments (docstrings, JSDoc), and architectural guides. Reads and understands your code first, then produces documentation that reflects actual verified behavior — never aspirational or assumed behavior. Works in a git worktree for safe isolation.
When activated: “Write a README,” “document this module,” “add docstrings,” API documentation requests.
documenter
Section titled “documenter”Full Opus documentation-patterns specification-writing
A documentation and specification lifecycle agent. Handles READMEs, API docs, inline documentation, and architectural guides alongside the full spec workflow — creating, refining, reviewing, and closing specifications. Carries 7 frontloaded skills covering both documentation patterns and all spec operations. Unlike doc-writer, the documenter works directly (no worktree isolation) and owns the spec lifecycle. Never modifies source code logic.
When activated: “Document this module,” “write a README,” “create a spec and document the feature,” specification lifecycle tasks that combine docs and specs.
explorer
Section titled “explorer”Read-only Haiku
A fast codebase navigator for file discovery, pattern matching, and structural analysis. Supports three thoroughness levels — quick (minimal tool calls), medium (balanced search), and very thorough (comprehensive investigation). Uses ast-grep and tree-sitter for syntax-aware structural search alongside standard Glob and Grep.
When activated: “Find all files matching,” “where is X defined,” “how is this project structured,” codebase orientation.
generalist
Section titled “generalist”Full Sonnet
The general-purpose development agent for tasks that don’t fit a specialized role. Has access to all tools and can handle mixed workloads — small features, bug fixes, multi-file investigations, and miscellaneous development tasks. Used when no specialist clearly matches.
When activated: General development tasks, mixed-scope requests, tasks spanning multiple domains.
git-archaeologist
Section titled “git-archaeologist”Read-only Haiku git-forensics
A git history forensics specialist that traces code evolution, finds when bugs were introduced, identifies authorship patterns, and recovers lost work from the reflog. Uses advanced git commands — blame with rename tracking (-C -C -C), pickaxe search (-S), and regex grep (-G). Never modifies git history or the working tree.
When activated: “When was this changed,” “who wrote this code,” “find when this bug was introduced,” git blame, git history questions.
implementer
Section titled “implementer”Full (worktree) Opus refactoring-patterns migration-patterns spec-update
A full-stack implementation agent that handles all code modifications: writing new features, fixing bugs, refactoring existing code, and executing migrations. Runs tests after every edit via a Stop hook to catch regressions immediately. Works in a git worktree so your main branch stays clean. The broadest-scope implementation agent — use the more focused refactorer, migrator, or test-writer when the task is clearly within one domain.
When activated: General implementation tasks, feature building, bug fixes, “implement this,” multi-file changes that span domains.
investigator
Section titled “investigator”Read-only Sonnet debugging git-forensics performance-profiling dependency-management documentation-patterns ast-grep-patterns
A comprehensive read-only research agent that consolidates six analysis domains: codebase exploration, web research, git history forensics, dependency auditing, log analysis, and performance profiling. Carries 6 frontloaded skills — more than any other agent — making it the go-to for complex investigations that cross domain boundaries. Never modifies files.
When activated: Complex multi-domain investigations, “investigate why,” “research and analyze,” tasks that combine codebase analysis with git history or dependency research.
migrator
Section titled “migrator”Full (worktree) Opus migration-patterns
Plans and executes framework upgrades, language version bumps, API changes, and dependency migrations. Works methodically — creating a migration plan, transforming code in controlled steps, and verifying functionality after each change. Uses web research to consult official migration guides. Works in a git worktree so your main branch stays clean.
When activated: “Migrate from X to Y,” “upgrade to version N,” “update the framework,” “modernize the codebase.”
perf-profiler
Section titled “perf-profiler”Read-only Sonnet performance-profiling
A performance engineer that measures application performance, identifies bottlenecks, and recommends targeted optimizations backed by profiling data. Follows a rigorous measure-first approach — collects data before making claims, and every recommendation references specific measurements. Runs in the background. Never modifies code directly.
When activated: “Profile this,” “why is this slow,” “find the bottleneck,” “benchmark this function,” performance questions.
refactorer
Section titled “refactorer”Full (worktree) Opus refactoring-patterns
A disciplined refactoring specialist that performs behavior-preserving code transformations. Identifies code smells (god classes, deep nesting, duplication, long parameter lists), applies established refactoring patterns (extract function, replace conditional with polymorphism, introduce parameter object), and rigorously verifies that tests pass after every single edit via a PostToolUse hook. Works in a git worktree.
When activated: “Refactor this,” “clean up this code,” “reduce complexity,” “extract this function,” “remove duplication.”
researcher
Section titled “researcher”Read-only Sonnet documentation-patterns
A technical research analyst that investigates codebases, searches documentation, and gathers web-based evidence to answer technical questions. Follows a disciplined codebase-first, web-second approach — local evidence is more reliable than generic documentation. Evaluates source recency, authority, and specificity. Produces structured reports with citations.
When activated: “How does X work,” “research this topic,” “compare X vs Y,” technology evaluation, technical deep-dives.
security-auditor
Section titled “security-auditor”Read-only Sonnet security-checklist
A senior application security engineer that audits codebases for vulnerabilities using a structured four-phase methodology: reconnaissance (map the attack surface), OWASP Top 10 scan (check every category systematically), secrets scan (find hardcoded credentials), and configuration review (Docker, environment variables). Rates findings from CRITICAL to INFO with specific remediation guidance. Runs in the background. Never exposes actual secret values in output.
When activated: “Audit this for security,” “check for vulnerabilities,” “scan for secrets,” “OWASP review,” security assessments.
spec-writer
Section titled “spec-writer”Read-only Opus specification-writing
A requirements engineer that creates structured technical specifications using the EARS (Easy Approach to Requirements Syntax) format for requirements and Given/When/Then patterns for acceptance criteria. Grounds every specification in the actual codebase state — reads existing code, tests, and interfaces before writing requirements.
When activated: “Write a spec for,” “define requirements,” “create acceptance criteria,” specification authoring.
statusline-config
Section titled “statusline-config”Full Sonnet
A specialist for configuring the Claude Code terminal statusline. Converts shell PS1 prompts to statusline commands, builds custom status displays, and integrates project-specific information into the status bar. Only modifies Claude Code settings files.
When activated: “Set up my status line,” “customize the status bar,” “show git branch in status line.”
tester
Section titled “tester”Full (worktree) Opus testing spec-update
A test suite creation and verification agent. Analyzes existing code, writes comprehensive tests, and ensures all tests pass before completing via a Stop hook. Supports pytest, Vitest, Jest, Go testing, and Rust test frameworks. Works in a git worktree. Functionally equivalent to test-writer with the addition of the spec-update skill for closing the spec loop after writing tests.
When activated: “Write tests for,” “add test coverage,” “create integration tests,” test creation tasks.
test-writer
Section titled “test-writer”Full (worktree) Opus testing
A senior test engineer that analyzes existing code and writes comprehensive test suites. Detects test frameworks (pytest, Vitest, Jest, Go testing, Rust tests), follows project conventions exactly, and verifies all written tests pass before completing. A Stop hook automatically checks that no tests are failing when the agent finishes. Works in a git worktree. Never modifies source code — if a bug is found, it reports the bug rather than fixing it.
When activated: “Write tests for,” “add tests,” “increase test coverage,” “create unit tests,” test writing requests.
Agent Capabilities Matrix
Section titled “Agent Capabilities Matrix”| Agent | Access | Model | Isolation | Background | Key Skills |
|---|---|---|---|---|---|
| architect | Read-only | Opus | — | — | api-design |
| bash-exec | Full | Sonnet | — | — | — |
| claude-guide | Read-only | Haiku | — | — | claude-code-headless, claude-agent-sdk |
| debug-logs | Read-only | Sonnet | — | — | debugging |
| dependency-analyst | Read-only | Haiku | — | Yes | dependency-management |
| doc-writer | Full | Opus | Worktree | — | documentation-patterns |
| documenter | Full | Opus | — | — | documentation-patterns, specification-writing, spec-new, spec-update, spec-review, spec-refine, spec-check |
| explorer | Read-only | Haiku | — | — | ast-grep-patterns |
| generalist | Full | Inherited | — | — | spec workflow |
| git-archaeologist | Read-only | Haiku | — | — | git-forensics |
| implementer | Full | Opus | Worktree | — | refactoring-patterns, migration-patterns, spec-update |
| investigator | Read-only | Sonnet | — | — | documentation-patterns, git-forensics, performance-profiling, debugging, dependency-management, ast-grep-patterns |
| migrator | Full | Opus | Worktree | — | migration-patterns |
| perf-profiler | Read-only | Sonnet | — | Yes | performance-profiling |
| refactorer | Full | Opus | Worktree | — | refactoring-patterns |
| researcher | Read-only | Sonnet | — | — | documentation-patterns |
| security-auditor | Read-only | Sonnet | — | Yes | security-checklist |
| spec-writer | Read-only | Opus | — | — | specification-writing |
| statusline-config | Full | Sonnet | — | — | — |
| tester | Full | Opus | Worktree | — | testing, spec-update |
| test-writer | Full | Opus | Worktree | — | testing |
Access Levels at a Glance
Section titled “Access Levels at a Glance”| Access Level | Agents |
|---|---|
| Read-only | architect, claude-guide, debug-logs, dependency-analyst, explorer, git-archaeologist, investigator, perf-profiler, researcher, security-auditor, spec-writer |
| Full | bash-exec, doc-writer, documenter, generalist, implementer, migrator, refactorer, statusline-config, tester, test-writer |
Safety Mechanisms
Section titled “Safety Mechanisms”Several agents include built-in safety hooks:
- Read-only bash guard — The architect, explorer, investigator, security auditor, dependency analyst, and git-archaeologist all have a PreToolUse hook that blocks any Bash command that could modify files or state.
- Git-readonly guard — The git-archaeologist has a specialized guard that only permits read-only git subcommands (log, blame, show, diff, reflog, etc.).
- Post-edit test verification — The refactorer runs tests automatically after every single Edit operation. If tests fail, the change is immediately reverted.
- Stop verification — The test-writer and tester have a Stop hook that verifies all written tests pass before the agent completes. The implementer has a similar Stop hook that runs regression checks.
Related
Section titled “Related”- Agent System Plugin — how the agent system works
- Skills — knowledge packs agents can leverage
- Hooks — hook scripts that support agents