DEV Community

Cover image for How I Built oh-my-zsh for Claude Code: 11 Agents, 36 Commands, and 6-Layer Security
정상록
정상록

Posted on • Originally published at github.com

How I Built oh-my-zsh for Claude Code: 11 Agents, 36 Commands, and 6-Layer Security

#claudecode #opensource #ai #programming

How I Built oh-my-zsh for Claude Code: 11 Agents, 36 Commands, and 6-Layer Security

If you use Claude Code for real development work, you know the pain: it's powerful, but getting it to work consistently well requires a lot of manual setup. Custom agents, security hooks, workflow rules, slash commands -- you end up rebuilding the same infrastructure for every project.

After months of iterating on my Claude Code setup across 30+ client projects at my AI automation consultancy, I decided to package everything into an open-source framework called Claude Forge.

The pitch is simple: oh-my-zsh for Claude Code. Just like oh-my-zsh transforms a bare terminal into a fully-featured shell environment, Claude Forge transforms Claude Code from a capable CLI into a complete development environment.

GitHub: sangrokjung/claude-forge

Why I Built This

The Repetition Problem

Every new project meant the same ritual:

  1. Create agent definitions for planner, reviewer, security checker
  2. Write hook scripts for secret filtering and SQL protection
  3. Define coding rules and git conventions
  4. Set up MCP server configurations
  5. Wire everything together

After the 10th time doing this, I realized two things: (a) this should be automated, and (b) the Claude Code community could benefit from a shared, curated set of these components.

The Gap in the Ecosystem

Claude Code has an incredibly elegant extension system -- agents are markdown files, commands are markdown files, hooks are shell scripts. Everything is just files in ~/.claude/. But there was no framework to manage, distribute, and update these files as a cohesive unit.

Claude Forge fills that gap.

Architecture: Symlinks All the Way Down

The architecture is intentionally simple. No package manager, no build step, no runtime dependency.

claude-forge/ (git repo)
  ├── agents/        (11 agent definitions)
  ├── commands/      (36 slash commands)
  ├── skills/        (15 skill workflows)
  ├── hooks/         (14 automation hooks)
  ├── rules/         (8 rule files)
  ├── scripts/       (utility scripts)
  ├── settings.json  (Claude Code settings)
  └── install.sh     (symlink installer)
Enter fullscreen mode Exit fullscreen mode

The installer (install.sh) creates symlinks from the repo to ~/.claude/. This gives us three key properties:

  1. Instant updates -- git pull updates everything. No reinstall.
  2. Clean separation -- your personal config goes in settings.local.json, which isn't tracked.
  3. Easy customization -- fork the repo, modify what you need, push to your own remote. 
# Installation (macOS/Linux)
git clone --recurse-submodules https://github.com/sangrokjung/claude-forge.git
cd claude-forge
./install.sh
Enter fullscreen mode Exit fullscreen mode

The entire install takes about 5 minutes, including optional MCP server setup.

Deep Dive: The 6 Core Components

1. Agents (11)

Claude Forge ships with 11 specialized agents, split into two tiers based on the task complexity they handle:

Opus-tier agents (6) -- for deep analysis and planning:

Agent Purpose
planner Creates implementation plans for complex features. Identifies dependencies, risks, and breaking points before any code is written.
architect System design, scalability decisions, and technical architecture. Thinks about trade-offs you haven't considered.
code-reviewer Quality, security, and maintainability review. Has specific checklists for common patterns.
security-reviewer OWASP Top 10 vulnerability detection, secrets scanning, SSRF and injection analysis.
tdd-guide Enforces RED-GREEN-IMPROVE test-driven development. Won't let you skip the "write tests first" step.
database-reviewer PostgreSQL and Supabase optimization: schema design, query performance, indexing strategies.

Sonnet-tier agents (5) -- for fast execution:

Agent Purpose
build-error-resolver Fixes build and TypeScript errors with minimal code changes.
e2e-runner Generates and runs Playwright end-to-end tests.
refactor-cleaner Dead code cleanup using knip, depcheck, and ts-prune.
doc-updater Keeps documentation and codemaps in sync with code changes.
verify-agent Fresh-context build, lint, and test verification.

Each agent is a markdown file with a tailored system prompt. This means they're version-controllable, shareable, and easy to customize.

2. Commands (36)

Slash commands are the primary interface for Claude Forge workflows. Here are the most commonly used ones:

Core workflow:

/plan          -- AI creates implementation plan, waits for your OK
/tdd           -- Write tests first, then implement
/code-review   -- Security + quality check
/handoff-verify-- Auto-verify build/test/lint
/commit-push-pr-- Commit, push, create PR, optionally merge
/auto          -- Full autopilot: plan to PR in one command
Enter fullscreen mode Exit fullscreen mode

Exploration:

/explore       -- Navigate and understand codebase structure
/build-fix     -- Incrementally fix TypeScript/build errors
/next-task     -- AI recommends what to work on next
Enter fullscreen mode Exit fullscreen mode

Security:

/security-review          -- CWE Top 25 + STRIDE threat modeling
/stride-analysis-patterns -- Systematic STRIDE methodology
/security-compliance      -- SOC2, ISO27001, GDPR, HIPAA checks
Enter fullscreen mode Exit fullscreen mode

Testing:

/e2e           -- Generate and run Playwright E2E tests
/test-coverage -- Analyze coverage gaps, generate missing tests
/verify-loop   -- Auto-retry build/lint/test up to 3x with auto-fix
Enter fullscreen mode Exit fullscreen mode

The /auto command deserves special mention. You type /auto login page and Claude Forge handles the entire pipeline: planning the implementation, writing tests, implementing the feature, reviewing the code, verifying the build, and creating a PR. It's opinionated and sometimes you want more control, but for straightforward features it's remarkably effective.

3. Skills (15)

Skills are multi-step workflows that combine agents, commands, and tool calls into reusable patterns. Think of them as "recipes" for common development tasks.

Key skills include:

  • build-system -- Auto-detects and runs the project's build system (npm, yarn, pnpm, make, etc.)
  • security-pipeline -- Runs CWE Top 25 scan + STRIDE threat modeling in an automated sequence
  • eval-harness -- Formal evaluation framework for eval-driven development
  • team-orchestrator -- Manages Agent Teams: composition, task distribution, dependency resolution, hub-and-spoke coordination
  • session-wrap -- End-of-session cleanup with 4 parallel sub-agents detecting documentation needs, patterns, learnings, and follow-ups
  • verification-engine -- Fresh-context sub-agent verification loop ensuring nothing passes without evidence

4. Hooks (14)

Hooks are the hidden power of Claude Code, and Claude Forge makes full use of them. They intercept tool calls at different lifecycle points:

Security hooks (6-layer defense):

Layer 1: output-secret-filter.sh    -- Catches leaked secrets in output
Layer 2: remote-command-guard.sh    -- Blocks unsafe remote commands
Layer 3: db-guard.sh                -- Prevents destructive SQL
Layer 4: security-auto-trigger.sh   -- Scans code changes for vulns
Layer 5: rate-limiter.sh            -- Prevents MCP abuse
Layer 6: mcp-usage-tracker.sh       -- Monitors external tool usage
Enter fullscreen mode Exit fullscreen mode

Utility hooks:

code-quality-reminder.sh     -- Nudges about immutability, file size
context-sync-suggest.sh      -- Suggests doc sync at session start
session-wrap-suggest.sh      -- Suggests cleanup before ending
work-tracker-*.sh            -- Analytics and usage tracking
task-completed.sh            -- Sub-agent task completion alerts
Enter fullscreen mode Exit fullscreen mode

These run automatically. The security hooks in particular have saved me from embarrassing mistakes multiple times -- accidentally leaking an API key in output, running a destructive SQL query, or piping a remote script directly into bash.

5. Rules (8)

Rules are always-on instructions that shape Claude's behavior within your project. Claude Forge includes 8 rule files covering:

  • Coding style -- immutability, small files/functions, boundary validation
  • Security -- mandatory security checks before every commit
  • Git workflow -- conventional commits, PR workflow, feature branches
  • Golden principles -- TDD, evidence-based completion, design-before-code
  • Agent orchestration -- when to use which agent, parallel vs sequential
  • Interaction -- response format, analogy-first explanations, conclusion-first
  • Verification -- no completion claims without fresh verification evidence
  • Date calculation -- always use system tools for date math (LLMs are bad at it)

6. MCP Servers (6)

Pre-configured MCP server integrations:

Server Purpose API Key Required?
context7 Library documentation lookup No
memory Persistent memory across sessions No
fetch Web page fetching No
jina-reader Web-to-markdown conversion No
exa AI-powered web search OAuth
github GitHub API access PAT

Real-World Workflows

Feature Development Pipeline

This is the workflow I use most. It enforces a plan-first, test-first approach:

/plan --> /tdd --> /code-review --> /handoff-verify --> /commit-push-pr
Enter fullscreen mode Exit fullscreen mode
  1. /plan -- The planner agent analyzes your request, identifies risks, and creates a step-by-step implementation plan. It waits for your approval before any code is written.
  2. /tdd -- The TDD guide agent enforces RED-GREEN-IMPROVE: write a failing test, implement the minimum code to pass it, then refactor.
  3. /code-review -- The code reviewer agent checks for quality issues, security vulnerabilities, and maintainability concerns.
  4. /handoff-verify -- A fresh-context verify agent runs build, lint, and tests to ensure everything passes.
  5. /commit-push-pr -- Commits, pushes, creates a PR with a structured description, and optionally merges.

Bug Fix (Fast Path)

For quick bug fixes where you don't need the full planning overhead:

/explore --> /tdd --> /verify-loop --> /quick-commit
Enter fullscreen mode Exit fullscreen mode

The /verify-loop command is particularly useful here -- it runs build/lint/test and if anything fails, it automatically attempts to fix the issue and re-runs, up to 3 times.

Team Collaboration

For large features that benefit from parallel execution:

/orchestrate --> Agent Teams (parallel work) --> /commit-push-pr
Enter fullscreen mode Exit fullscreen mode

The team orchestrator skill creates an Agent Team with file-ownership separation (so agents don't conflict) and hub-and-spoke coordination (a lead agent manages task distribution and dependency resolution).

Installation Guide

Prerequisites

Dependency Version Check
Node.js v22+ node -v
Git any git --version
jq any jq --version
Claude Code CLI >= 1.0 claude --version

macOS / Linux 

git clone --recurse-submodules https://github.com/sangrokjung/claude-forge.git
cd claude-forge
./install.sh
Enter fullscreen mode Exit fullscreen mode

The installer:

  1. Checks dependencies
  2. Backs up existing ~/.claude/ config
  3. Creates symlinks for 7 directories + settings
  4. Optionally installs MCP servers
  5. Adds shell aliases (cc -> claude, ccr -> claude --resume)

Windows 

# Run PowerShell as Administrator
.\install.ps1
Enter fullscreen mode Exit fullscreen mode

Windows uses file copies instead of symlinks. Re-run after git pull.

First Steps After Install 

# Launch Claude Code
claude

# Run the interactive guide
/guide

# Try full autopilot on a simple feature
/auto add dark mode toggle
Enter fullscreen mode Exit fullscreen mode

Lessons Learned Building This

Building Claude Forge across 30+ real client projects taught me a few things I didn't expect:

Hooks Are the Killer Feature Nobody Talks About

Claude Code's hook system lets you intercept tool calls before and after execution. This is incredibly powerful for safety. The output-secret-filter hook alone has saved me from accidentally leaking API keys in terminal output more times than I'd like to admit. The db-guard hook once caught a DROP TABLE in a migration script that would have nuked a production database. These aren't theoretical protections -- they're battle-tested.

Agents as Markdown Files Is Brilliant

Anthropic's decision to define agents as markdown files means the entire agent system is:

  • Version-controllable -- every agent change is a git commit
  • Shareable -- copy a markdown file to share an agent
  • Reviewable -- PRs for agent changes are just markdown diffs
  • Composable -- reference one agent from another

This design choice made Claude Forge possible. If agents were compiled plugins or binary extensions, none of this would work.

Symlinks Solve the Distribution Problem

I considered npm packages, Homebrew formulas, and custom installers. Symlinks won because:

  • No package manager dependency
  • No build step
  • No version conflicts
  • git pull updates everything
  • Easy to fork and modify

The entire "distribution" is: clone, symlink, done. It's the same pattern oh-my-zsh uses, and it works because the extension format is just files.

The /auto Command Changed How I Think About Development

When I first built the /auto command (plan-to-PR automation), I expected it to be a demo feature. Instead, it became my most-used command for straightforward features. Type /auto add user settings page and Claude Forge handles planning, TDD, code review, verification, and PR creation. It's not perfect for complex features (you want more control there), but for standard CRUD operations and UI components, it's remarkably effective.

Security Can't Be an Afterthought

The original version of Claude Forge had no security hooks. After the first time an API key appeared in Claude's output during a client demo, I built the 6-layer security system. The lesson: if you're using an AI coding assistant with access to your codebase, you need automated guardrails. Human vigilance isn't enough when you're moving fast.

Who Is This For?

Claude Forge is designed for developers who:

  • Use Claude Code daily and want a more structured workflow
  • Work across multiple projects and are tired of re-creating the same setup
  • Care about security and want automated guardrails
  • Follow TDD and code review practices and want them enforced
  • Lead teams and want consistent development practices across team members

It's probably not for you if:

  • You prefer a minimal, no-framework approach
  • You only use Claude Code occasionally
  • You have a heavily customized setup that you're happy with

Customization

Claude Forge is designed to be forked and customized:

Add your own agent:
Create a markdown file in agents/ with the agent's system prompt.

Add a slash command:
Create a markdown file in commands/ with the command's instructions.

Override settings:
Copy setup/settings.local.template.json to ~/.claude/settings.local.json and modify. This file isn't tracked by git, so your customizations survive git pull.

Add a hook:
Create a shell script in hooks/ and register it in settings.json.

What's on the Roadmap

  • More workflow recipes and real-world examples
  • Community-contributed agent and command packs
  • Plugin system for optional extensions
  • Better Windows support
  • Integration with more MCP servers
  • Performance benchmarking tools

Try It Out 

git clone --recurse-submodules https://github.com/sangrokjung/claude-forge.git
cd claude-forge
./install.sh
Enter fullscreen mode Exit fullscreen mode

GitHub: sangrokjung/claude-forge

If you find it useful, a star on GitHub helps others discover it. And if you build something cool with it -- an agent, a command, a workflow -- I'd love to see a PR.

Claude Forge is MIT licensed. Use it, fork it, build on it.

Top comments (0)