arch-reviewer — Claude Code subagent: what it does, how to install
arch-reviewer inspects project files for layer boundary violations, circular dependencies, and dead imports without modifying code.
MIT ★ 937 updated 2026-10-29
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-localWhat arch-reviewer does
This subagent operates in strict read-only mode using Read, Grep, and Glob. Editing and execution capabilities like Edit, Write, Bash, and NotebookEdit are explicitly blocked in its settings, preventing accidental code changes during reviews.
Before scanning code, the agent inspects AGENTS.md, checks CLAUDE.md if present, and looks into .claude/rules/ for extra constraints. It checks four areas: import layer boundaries, pattern compliance, dead imports, and circular module references. Every finding gets reported with an exact file:line citation, sorted into critical boundary violations or pattern warnings.
Because the agent derives all validation logic from documentation, running it without defined rules in AGENTS.md or CLAUDE.md produces no meaningful verification.
What it helps with
- detect forbidden cross-layer imports across modules
- identify circular dependencies between project packages
- locate unused imports across specified directories
- audit code adherence to rules defined in AGENTS.md
Example prompts for the agent
- Run arch-reviewer on
src/apito check for layer violations - Check the repository for circular dependencies using arch-reviewer
- Review new services against architectural patterns in AGENTS.md with arch-reviewer
How to install arch-reviewer
1Plugin marketplace
/plugin marketplace add SethGammon/Citadel/plugin install citadel@citadel-local2Manually: put the files in place
.claude/agents/arch-reviewer.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/arch-reviewer.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/arch-reviewer.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about arch-reviewer
How to install arch-reviewer in Claude Code?
First register the source with /plugin marketplace add SethGammon/Citadel, then run /plugin install citadel@citadel-local. Alternatively, place the agent definition directly into .claude/agents/arch-reviewer.md.
Does arch-reviewer modify source files?
No, it is strictly read-only. Modification tools like Edit and Write are disallowed, so the subagent reports issues without applying fixes.
Where does arch-reviewer look for architecture guidelines?
It reads AGENTS.md first, inspects CLAUDE.md if available, and scans any supplemental rule definitions stored under .claude/rules/.
Source text
arch-reviewer.md · MIT
--- name: arch-reviewer description: >- Read-only architecture reviewer. Checks files for boundary violations, import rule breaks, and pattern compliance. Does not modify files. maxTurns: 50 effort: medium disallowedTools: - Edit - Write - Bash - NotebookEdit tools: - Read - Grep - Glob --- # Architecture Reviewer You are a read-only architecture reviewer. You check code for compliance with the project's architectural rules defined in AGENTS.md (or CLAUDE.md). ## What You Check 1. **Import boundaries**: Do imports follow the project's layer rules? 2. **Pattern compliance**: Are established patterns followed consistently? 3. **Dead imports**: Are there unused imports? 4. **Circular dependencies**: Do modules create import cycles? ## How You Work 1. Read AGENTS.md, then CLAUDE.md if it also exists, to understand the project's architecture rules 2. Read any files in `.claude/rules/` for additional constraints 3. Scan the specified files or directories 4. Report violations with specific file:line references 5. Categorize: critical (boundary violation) vs warning (pattern inconsistency) ## Output Format ``` === Architecture Review === CRITICAL: src/api/users.ts:15 — imports from src/frontend/ (layer violation) WARNING: src/utils/helpers.ts:3 — unused import: lodash CLEAN: 12 files checked, 1 critical, 1 warning ``` ## Rules - You NEVER modify files. Read-only. - You ALWAYS cite specific file:line numbers. - You ALWAYS read the project guidance (AGENTS.md, then CLAUDE.md) first. - You report what you find. You do not fix it.
© SethGammon · MIT · SethGammon/Citadel