DEV Community: DevForge Templates

Why Claude Code Changed How I Freelance as a Developer

DevForge Templates — Tue, 14 Apr 2026 20:54:27 +0000

I've been freelancing for years — React dashboards, Node.js APIs, the usual. In early 2026, I started using Claude Code as my primary development tool. Three months later, my workflow is unrecognizable.

Here's what changed and why it matters for freelance developers.

The Speed Difference

A typical client project — say, a dashboard with auth, CRUD, charts, and deployment — used to take me 2-3 weeks. With Claude Code, I deliver in 3-5 days.

Not because I'm cutting corners. The code quality is higher. Tests are written. Docker deployment is included. The AI handles the boilerplate while I focus on architecture decisions and client-specific logic.

For freelancers, speed = more projects = more revenue. At $45-80/hr, cutting project time by 60% means you can take on 2-3x the work.

What I Actually Use It For

1. Multi-Agent Coordination

I run 7 Claude Code agents across 16 projects. A Boss agent coordinates, worker agents handle specific domains (trading, marketing, research). They communicate via a file-based message bus — no frameworks, no dependencies.

This isn't a demo. The trading agent manages real money on Binance. The marketing agent publishes articles autonomously. The research agent crawls the web for opportunities.

2. Rapid Prototyping for Clients

When a client says "I need an investor dashboard," I don't start from scratch. I tell Claude Code about the requirements and it scaffolds the project in minutes, using patterns it's seen across my 16 projects. Custom Prisma schema, API routes, React components — all type-safe.

3. Code Review and Refactoring

Claude Code's hook system lets me enforce rules mechanically. Before any file edit, a hook checks for security issues, validates against my coding standards, and blocks writes to protected files. It's like having a senior reviewer that never sleeps.

The Stack That Works

After 12+ production projects, I've settled on:

React 19 + TypeScript — frontend
Fastify 5 + Prisma 7 — backend
PostgreSQL — database
Docker — deployment
Zod — validation across the stack
Mantine 8 — UI components

Every project uses the same stack. Claude Code knows it deeply. New projects start at 80% done.

Advice for Freelancers Considering Claude Code

Start with CLAUDE.md. This file tells Claude Code about your project — commands, architecture, rules. Keep it under 60 lines. More than that, and the AI starts ignoring instructions.

Use hooks, not instructions. If something must happen every time (check inbox, validate files, update state), put it in a hook. Hooks are mechanical. Instructions are suggestions.

Specialize. "React developer who uses AI" is commodity. "Claude Code expert who builds multi-agent systems" is a niche. The AI freelance market grew 178% in 2025. Position accordingly.

Async everything. Claude Code works best when you give it a task and let it run. I work async with all clients — no calls, no screen shares. I deliver working code, not explanations.

The Market

AI-assisted development isn't a gimmick. Upwork's AI category grew 60% year-over-year. Claude Code specialists command 40-60% rate premiums over general developers.

The freelancers who will thrive in 2026 aren't the ones who resist AI — they're the ones who make it their competitive advantage.

I build AI-powered fullstack applications with Claude Code. Available for async freelance work — dashboards, AI integrations, multi-agent systems. Portfolio: devforgetemplates.gumroad.com

How I Built a Multi-Agent System Using Only Claude Code (No Frameworks)

DevForge Templates — Tue, 14 Apr 2026 20:52:47 +0000

I run 7 Claude Code agents that coordinate across 16 projects on a single machine. No CrewAI. No AutoGen. No LangGraph. Just files, shell scripts, and Claude Code's built-in hook system.

This isn't a toy demo — it manages a crypto trading bot, marketing pipelines, a multiplayer game server, and home automation. Here's the architecture and how to build it yourself.

Why Not Use a Framework?

Multi-agent frameworks operate at the API level — they orchestrate LLM calls through Python code. But Claude Code agents are terminal sessions with full filesystem access. They read files, run commands, edit code. The coordination layer needs to match that model.

Files are the answer. Every agent can read and write files. No servers, no ports, no auth tokens, no dependencies to install.

The Message Bus: 30 Lines of Bash

The entire inter-agent communication layer is a directory with inbox files:

~/.claude/bus/
├── inbox-boss.md        # Coordinator agent
├── inbox-trading.md     # Crypto trading bot
├── inbox-freelance.md   # Marketing & sales
├── inbox-research.md    # Web research specialist
├── send.sh              # Message delivery
├── broadcast.sh         # Send to all agents
├── audit.log            # Full message history
└── check-inbox.sh       # Read + archive + clear

The send script validates known agents, blocks suspicious content (injection defense), and appends to the recipient's inbox:

#!/bin/bash
# send.sh — FROM TO TYPE "message"
FROM="$1"; TO="$2"; TYPE="${3:-FYI}"; shift 3; MSG="$*"

KNOWN="boss trading freelance research"
echo "$KNOWN" | grep -qw "$FROM" || exit 1
echo "$KNOWN" | grep -qw "$TO"   || exit 1

# Block command injection patterns
echo "$MSG" | grep -qiE 'rm -rf|drop table|curl.*\|.*sh' && exit 1

echo "[${TYPE} $(date +%H:%M)] from:${FROM} | ${MSG}" \
  >> "$HOME/.claude/bus/inbox-${TO}.md"

echo "$(date '+%F %T') | ${FROM} -> ${TO} | ${TYPE} | ${MSG:0:200}" \
  >> "$HOME/.claude/bus/audit.log"

Real messages from my audit log:

freelance -> boss  | STATUS | Published 2 Dev.to articles, 144 views
research  -> boss  | DONE   | Task complete: implementation patterns saved
boss      -> trading | ACK  | Deploy #50 confirmed, monitoring

Hook-Driven Lifecycle

Claude Code hooks fire at specific points in the session — mechanically, every time, regardless of context length. This is more reliable than instructions in CLAUDE.md (which degrade after ~150 lines of rules).

Here's the settings.json that wires it together:

{
  "hooks": {
    "SessionStart": [{
      "type": "command",
      "command": ".claude/hooks/session-start.sh"
    }],
    "UserPromptSubmit": [{
      "type": "command",
      "command": "~/.claude/bus/check-inbox.sh trading"
    }],
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "type": "command",
      "command": ".claude/hooks/protect-files.sh"
    }],
    "PreCompact": [{
      "type": "command",
      "command": "echo 'SAVE STATE: Update SESSION-HANDOFF.md before compacting'"
    }]
  }
}

What each hook does:

SessionStart — loads shared rules, checks inbox, reads the session handoff document. The agent wakes up with full context.
UserPromptSubmit — checks the inbox before every response. Messages are picked up within one interaction, no polling.
PreToolUse — guards sensitive files. My hook blocks .env edits and read-only research docs. The agent physically cannot write credentials.
PreCompact — forces the agent to save state before context compression. No more lost progress.

Shared Memory: Knowledge That Propagates

When any agent discovers a bug or platform limitation, it writes to a shared error database:

# shared/rules/errors.md

## API Limitations
- Gumroad: POST/PUT return 404 — create/edit via browser only
- Dev.to: DELETE articles returns 404 HTML, not JSON

## Claude Code
- CronCreate expires after 3 days — must recreate
- Heredocs in background mode never terminate → zombie shells

Every agent reads this file at session start. When the trading agent discovers that asyncpg returns Decimal types instead of float, it logs the gotcha. Later, when another agent touches database code, it already knows. Knowledge propagates without human intervention.

Try It: Minimal Two-Agent Setup

Create this structure and run two Claude Code sessions:

mkdir -p ~/.claude/bus

# Create inbox files
touch ~/.claude/bus/inbox-dev.md
touch ~/.claude/bus/inbox-reviewer.md

# Create send script
cat > ~/.claude/bus/send.sh << 'SCRIPT'
#!/bin/bash
FROM="$1"; TO="$2"; shift 2; MSG="$*"
echo "[$(date +%H:%M)] from:${FROM} | ${MSG}" >> \
  "$HOME/.claude/bus/inbox-${TO}.md"
SCRIPT
chmod +x ~/.claude/bus/send.sh

In project A's .claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [{
      "type": "command",
      "command": "cat ~/.claude/bus/inbox-dev.md && > ~/.claude/bus/inbox-dev.md"
    }]
  }
}

Now the "reviewer" agent can send feedback that the "dev" agent sees on its next interaction:

~/.claude/bus/send.sh reviewer dev "Auth middleware missing rate limiting — see src/middleware/auth.ts:47"

That's the foundation. The full system adds validation, audit logging, broadcast, and scoped rules — but this is enough to coordinate two agents on a real project.

What Works and What Doesn't

After 3 months of running this in production:

Works well: Low-frequency coordination (status updates, task delegation, error sharing), session continuity via handoff documents, scoped rules that load only when editing relevant files.

Doesn't work: Real-time back-and-forth (file polling has latency), agents editing the same files simultaneously, complex multi-step workflows that need tight coupling (use a single agent instead).

Surprising win: The shared error database. It turns individual debugging sessions into institutional knowledge. Every agent gets smarter from every other agent's mistakes.

The Bigger Pattern

This isn't really about multi-agent systems. It's about treating AI agents as first-class team members with proper tooling: inboxes, shared docs, lifecycle hooks, guarded resources, audit trails. The same patterns that make human teams effective — clear communication, shared context, defined responsibilities — work for AI agents too.

The difference is you can set it up in an afternoon.

I build systems like this for clients — AI integration, multi-agent coordination, and fullstack TypeScript projects. If you're exploring Claude Code for your team, my async consulting details are at DevForge Templates.

The Minimal Docker Setup for Fullstack Development

DevForge Templates — Fri, 03 Apr 2026 09:15:15 +0000

You don't need a Dockerfile for local development. You need docker-compose.yml with three services and a volume mount.

The Setup

# docker-compose.yml
services:
  db:
    image: postgres:17
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  app:
    image: node:22-alpine
    working_dir: /app
    volumes:
      - .:/app
      - node_modules:/app/node_modules
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://dev:dev@db:5432/myapp
      REDIS_URL: redis://redis:6379
    command: sh -c "npm install && npm run dev"
    depends_on:
      - db
      - redis

volumes:
  pgdata:
  node_modules:

That's it. Run docker compose up and you have:

PostgreSQL 17 with persistent data
Redis for caching/sessions
Your app with hot reload (Vite, nodemon, whatever your dev script uses)

Why This Works

No Dockerfile for dev. You don't need one. The node:22-alpine image + volume mount gives you hot reload. Your code changes are reflected instantly because the current directory is mounted as /app.

Named volume for node_modules. This is the key trick. Without node_modules:/app/node_modules, the volume mount from your host would overwrite the container's node_modules. The named volume keeps them separate — container installs its own deps, your host keeps its own.

Persistent database. The pgdata volume survives docker compose down. Your seed data, migrations, test records — all preserved. Only docker compose down -v wipes it.

Adding Prisma Migrations

  migrate:
    image: node:22-alpine
    working_dir: /app
    volumes:
      - .:/app
      - node_modules:/app/node_modules
    environment:
      DATABASE_URL: postgresql://dev:dev@db:5432/myapp
    command: sh -c "npm install && npx prisma migrate dev"
    depends_on:
      db:
        condition: service_started
    profiles:
      - migrate

Run migrations: docker compose --profile migrate run migrate

The profiles key means this service only runs when explicitly called. It won't start with a regular docker compose up.

Production Is Different

For production, you DO need a Dockerfile. Multi-stage build:

# Stage 1: Build
FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2: Run
FROM node:22-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
EXPOSE 3000
CMD ["node", "dist/server.js"]

Dev image: ~900MB (full Node + all deps + source). Production image: ~150MB (only build output + production deps).

Common Mistakes

1. Forgetting the node_modules volume

Without it:

volumes:
  - .:/app  # Host's empty node_modules overwrites container's

With it:

volumes:
  - .:/app
  - node_modules:/app/node_modules  # Container keeps its own

2. Using build: . in development

If you use build: . instead of image: node:22-alpine, Docker rebuilds on every docker compose up. Volume mount + pre-built image is faster.

3. Not setting depends_on

Your app will crash on first start if it tries to connect to PostgreSQL before the database is ready. depends_on ensures startup order (though for production, use healthchecks).

The .env.example

Always ship one:

# .env.example
DATABASE_URL=postgresql://dev:dev@localhost:5432/myapp
REDIS_URL=redis://localhost:6379
JWT_SECRET=dev-secret-change-in-production
PORT=3000

Note: localhost for running outside Docker, db/redis for inside Docker. Use the Docker service names in docker-compose.yml and localhost in .env for when you run the app natively.

This setup runs across 12 production templates. Clone, docker compose up, start coding. No 45-minute setup guides.

5 Claude Code Hooks That Automate My Entire Workflow

DevForge Templates — Thu, 02 Apr 2026 06:21:45 +0000

Claude Code hooks are shell commands that fire at specific lifecycle events. They're configured in .claude/settings.json and run automatically — no manual intervention.

I use 5 hooks across all my projects. Here's each one with the exact config.

1. Auto-Format After Every File Write

Every time Claude writes or edits a file, Prettier runs on it automatically.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true"
      }]
    }]
  }
}

Why: Claude's code formatting is inconsistent. Sometimes it uses 2 spaces, sometimes 4. Prettier fixes it instantly. The || true ensures the hook never blocks Claude if Prettier fails.

2. Inbox Check on Every Message

Every time I send a message, Claude checks its message bus inbox for tasks from other agents.

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "~/.claude/bus/check-inbox.sh my-agent"
      }]
    }]
  }
}

The script checks if ~/.claude/bus/inbox-my-agent.md has content. If yes, it prints the messages. Claude sees them and acts on them before responding to my message.

Why: This is how my 6 agents communicate. No polling interval — messages are delivered the moment I interact with any agent.

3. Session Context on Start

When a new session starts, automatically load the last session's state.

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "cat docs/SESSION-HANDOFF.md 2>/dev/null && echo '---' && cat .claude/rules/known-issues.md 2>/dev/null || true"
      }]
    }]
  }
}

Why: Claude reads the handoff file and known issues automatically. No need to say "read the handoff file" at the start of every session. It just knows what happened last time.

4. Reminder Before Session Ends

When Claude stops (session end, context limit, or user stops), remind it to save state.

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "echo '{\"systemMessage\": \"REMINDER: Update docs/SESSION-HANDOFF.md with what was done, what failed, and what is next.\"}'"
      }]
    }]
  }
}

Why: Without this, Claude often stops mid-task without saving context. The reminder fires every time, so the handoff file stays current.

5. Protect Critical Files

Before any edit to protected files, block the write.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path // \"\"' | grep -qE '(\\.env|credentials|secrets)' && echo '{\"decision\": \"block\", \"reason\": \"Cannot edit sensitive files\"}' || true"
      }]
    }]
  }
}

Why: Claude occasionally tries to write API keys or modify .env files. This hook blocks any edit to files matching sensitive patterns. It's a safety net you set once and forget.

The Hook Lifecycle

Here's when each hook type fires:

Event	When	Use case
`SessionStart`	New session begins	Load context
`UserPromptSubmit`	You send a message	Check inbox
`PreToolUse`	Before a tool runs	Block dangerous actions
`PostToolUse`	After a tool succeeds	Format code, run tests
`Stop`	Session ends	Save state
`PreCompact`	Before context compression	Preserve critical info

Setting It Up

All hooks go in .claude/settings.json (project-level) or ~/.claude/settings.json (global).

# Create project settings
mkdir -p .claude
cat > .claude/settings.json << 'EOF'
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "echo 'file written'"
      }]
    }]
  }
}
EOF

Start simple. Add one hook. Verify it fires. Then add more.

Common Mistakes

1. Missing || true — If your hook command fails, it can block Claude entirely. Always add || true unless you intentionally want to block on failure.

2. Hooks that are too slow — Hooks run synchronously by default. A hook that takes 10 seconds runs on every single tool call. Keep them fast.

3. Forgetting the JSON output format — Stop hooks need to output JSON with systemMessage field. Plain text won't show up.

These 5 hooks run across 16 projects. Once set up, they work silently in the background. The best automation is the kind you forget exists.

The One File That Makes Claude Code Sessions Actually Persistent

DevForge Templates — Wed, 01 Apr 2026 09:46:35 +0000

Every Claude Code session ends the same way: context window fills up, session compresses, and your AI forgets what it was doing.

I fixed this with one file.

The Problem

Claude Code has no persistent memory between sessions. When you start a new terminal, it reads your CLAUDE.md and starts fresh. Any decisions made, approaches tried, or context built up — gone.

For a single quick task, this is fine. For multi-day projects with complex state, it's a disaster.

The Fix: SESSION-HANDOFF.md

Every project gets a docs/SESSION-HANDOFF.md with this structure:

# Session Handoff

## Last Updated
2026-03-31 (Session 30)

## Current State
[What's working, what's deployed, what's in progress]

## What Was Done This Session
[Bullet points of completed work]

## What Failed
[Approaches that didn't work and why — so the next session doesn't repeat them]

## What's Next
[Prioritized list of next steps]

## Key Decisions
[Architectural choices made and the reasoning]

The Rule

The rule is simple and non-negotiable: CLAUDE.md mandates updating SESSION-HANDOFF.md before every session end or context compaction.

In my CLAUDE.md:

## Session Protocol (MANDATORY)
1. Start: MUST read docs/SESSION-HANDOFF.md
2. During: note decisions in SESSION-HANDOFF.md
3. Before end/compaction: MUST update SESSION-HANDOFF.md

Claude Code follows this because it's in CLAUDE.md — loaded on every session start.

Why This Works Better Than Memory

Claude Code has a built-in memory system (~/.claude/ memory files). It's useful for user preferences and project-level facts. But it's bad for session state because:

Memory is unstructured. SESSION-HANDOFF.md has a fixed format — Claude knows exactly where to look.
Memory is append-only. Session state changes completely each session. You need a full rewrite, not appended notes.
Memory survives too long. A "what I was doing" note from 5 sessions ago is noise. SESSION-HANDOFF.md is always current.

Making It Bulletproof

Hook: Reminder Before End

Add a Stop hook in .claude/settings.json that reminds Claude to update the handoff:

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "echo '{\"systemMessage\": \"REMINDER: Update SESSION-HANDOFF.md before ending!\"}'"
      }]
    }]
  }
}

Hook: Auto-Read on Start

Add a SessionStart hook that reads the handoff file:

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "cat docs/SESSION-HANDOFF.md 2>/dev/null || echo 'No handoff file found'"
      }]
    }]
  }
}

Now Claude reads the last session's state automatically on every start.

Real Example

Here's a compressed version of my trading bot project's handoff:

## Last Updated: Session 47

## Current State
- Bot running on VPS, 145 trades executed
- Dashboard: 18 pages, all functional
- OBV strategy v12 in production

## What Failed This Session
- Volume filter caused false negatives — rolled back in Deploy#47
- html2canvas timeout on complex dashboard pages

## What's Next
1. [P0] Fix trailing stop calibration for volatile coins
2. [P1] Add correlation matrix page to dashboard
3. [P2] Backtest new momentum strategy

Next session reads this and immediately knows: don't re-add the volume filter, focus on trailing stops.

Scaling to Multiple Agents

When you run multiple Claude Code instances (I run 6), each has its own SESSION-HANDOFF.md. A Boss agent can read all of them:

for f in ~/projects/*/docs/SESSION-HANDOFF.md; do
  echo "=== $(dirname $(dirname $f)) ==="
  head -20 "$f"
done

This gives the coordinator a snapshot of all projects in seconds.

The Pattern in 30 Seconds

Add docs/SESSION-HANDOFF.md to your project
Add "MUST read/update SESSION-HANDOFF.md" to your CLAUDE.md
Add SessionStart hook to auto-read it
Add Stop hook to remind about updates

Total setup: 5 minutes. Saves hours of re-explaining context.

Running this pattern across 16 projects. Context persists. Sessions don't.

How I Run a 3-Agent Content Marketing Team with Claude Code

DevForge Templates — Mon, 30 Mar 2026 09:28:43 +0000

I got tired of manually publishing to Dev.to, Hashnode, and Bluesky every time I wrote an article. So I built a 3-agent system that does it for me.

The Setup

Three Claude Code instances, each in its own terminal:

Agent	Role	What it owns
Boss	Strategist	Content calendar, task delegation, analytics
Writer	Article creator	Research, outline, draft, save to `drafts/`
Social	Publisher	Dev.to API, Hashnode GraphQL, Bluesky AT Protocol

They communicate through a file-based message bus. Boss sends a topic to Writer. Writer researches, drafts, and notifies Social. Social publishes everywhere.

The Message Bus

Four lines of bash:

#!/bin/bash
FROM=$1 TO=$2 TYPE=$3; shift 3; MSG="$*"
echo "[$TYPE $(date +%H:%M)] from:$FROM | $MSG" \
  >> ~/.claude/bus/inbox-$TO.md

Each agent checks its inbox on every user message (via a UserPromptSubmit hook in .claude/settings.json). When a message arrives, the agent reads it, executes, replies, and clears.

No Redis. No RabbitMQ. No WebSockets. Just files.

How a Publishing Cycle Works

Step 1: I tell Boss what to write.

Write an article about Zod validation patterns.
Target: intermediate React developers.
Angle: the patterns nobody talks about.

Step 2: Boss delegates to Writer.

~/.claude/bus/send.sh boss writer TASK \
  "topic: Zod validation, angle: hidden patterns, target: intermediate React devs"

Step 3: Writer researches (WebSearch), outlines, drafts 800-1200 words with working code examples, and saves to drafts/2026-03-30-zod-patterns.md.

Step 4: Writer notifies the team.

~/.claude/bus/send.sh writer boss DONE "draft ready: drafts/2026-03-30-zod-patterns.md"
~/.claude/bus/send.sh writer social TASK "new draft ready for publish"

Step 5: Boss reviews, approves. Social publishes to all 3 platforms.

The Publishing Scripts

Dev.to — one curl call:

curl -X POST https://dev.to/api/articles \
  -H "api-key: $DEVTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @article.json

Hashnode — GraphQL mutation with canonical URL (no SEO penalty for cross-posting):

node tools/hashnode-publish.mjs drafts/article.md

Bluesky — AT Protocol with auto-facets for link cards:

node tools/bluesky-post.mjs "Hook text + article link"

All three are autonomous. No browser needed.

Results So Far

14 articles across Dev.to and Hashnode
439 views in 10 days (from zero followers)
Top article: 145 views (crypto trading bot)
Publishing time per article: ~2 minutes across 3 platforms

What I'd Do Differently

Start with 2 agents, not 3. Boss + Writer is enough initially. Add Social when you have enough drafts queued up.

Mandate session handoff. Each agent must update SESSION-HANDOFF.md before session end. Without this, you lose context on restart.

Don't over-engineer the bus. I tried adding message types (TASK, QUESTION, ACK, DONE) — most of the time TASK and DONE are all you need.

The Key Insight

The value isn't in the infrastructure. The bus is trivial. The publishing scripts took an afternoon.

The value is in the CLAUDE.md files — the instructions that make each agent actually good at its job. Getting a Writer agent to produce articles that don't sound like AI slop takes weeks of tuning. Getting a Boss agent to delegate with the right context takes real iteration.

You're buying architecture decisions, not code.

Building AI agent systems in public. 14 articles, 6 agents, 0 frameworks.

Multi-Agent Claude System: How 6 AIs Work Together on My Projects

DevForge Templates — Sun, 29 Mar 2026 06:26:20 +0000

Tonight I held a conference call with 6 AIs. They each reported status, shared insights, and proposed ideas for each other's projects. This isn't science fiction — it's my actual development setup.

The Architecture

I run 6 specialized Claude Code CLI instances, each owning a different project:

Agent	Project	Role
Boss	Coordinator	Delegates tasks, reviews output, makes cross-project decisions
Binance	Trading bot	Crypto strategy development, backtesting, live trading
Freelance	Template factory	Gumroad products, marketing, Upwork proposals
Home Assistant	Smart home	IoT automations, sensor dashboards
Xojo	Desktop apps	Insurance industry desktop applications
Web Research	Research	Market analysis, competitive intelligence

Each agent runs in its own terminal with its own context, its own memory, and its own CLAUDE.md rules.

Communication: The Bus

The agents talk through a dead-simple file-based message bus:

~/.claude/bus/
├── inbox-boss.md
├── inbox-binance.md
├── inbox-freelance.md
├── inbox-home-assistant.md
├── inbox-xojo.md
├── inbox-web-research.md
├── send.sh
└── broadcast.sh

send.sh writes a timestamped message to the target's inbox file. That's it. No Redis, no RabbitMQ, no WebSockets. Just files.

#!/bin/bash
# send.sh — one agent writes to another's inbox
FROM=$1 TO=$2 TYPE=$3 MSG=$4
echo "[$TYPE $(date +%H:%M)] from:$FROM | $MSG" >> ~/.claude/bus/inbox-$TO.md

Each agent has a cron job (Claude Code's CronCreate) polling its inbox every 3 minutes:

*/3 * * * * → "cat ~/.claude/bus/inbox-freelance.md — if content, execute, reply, clear"

When an agent finds a message, it reads it, executes the task, sends a reply to the sender's inbox, and clears its own.

The Conference

Here's what tonight's conference actually looked like. Boss sent a broadcast:

CONFERENCE — КОЖЕН надсилає:
1. Who you are (1 line)
2. Status (3-5 lines)
3. Your #1 TOP INSIGHT
4. Your #1 TOP BLOCKER
5. Idea for another agent
6. What you need from the user

Within 10 minutes, all agents responded. Real excerpts:

Binance agent's insight:

"OBV Accumulation strategy confirmed: R:R 2.33 across 83 days. Futures executor doubles signal coverage — 80% of best signals are SHORT in bear markets."

Freelance agent's insight:

"Upwork proposals are the shortest path to first $. 18 ready, 0 submitted. Everything else (tweets, articles, Reddit) is a long game."

The cross-pollination moment:
Freelance agent suggested packaging the trading bot as a Gumroad product. Binance agent sent its full feature list. Within 30 minutes, we had a product listing, a Dev.to article draft, and an Upwork proposal template — all generated from real data that one agent shared with another.

Why This Works Better Than One Big Agent

1. Context isolation

Each agent's context window is dedicated to its project. The trading bot agent knows every test, every strategy parameter, every backtest result. It doesn't waste tokens on marketing copy or smart home configs.

2. Parallel execution

While Freelance writes a Gumroad listing, Binance runs backtests, and Web Research scrapes job boards. They don't block each other.

3. Specialized memory

Each agent has its own memory/ directory with project-specific knowledge. The Binance agent remembers which strategies failed and why. The Freelance agent remembers which Reddit subs need karma before posting. They don't pollute each other's context.

4. Boss as orchestrator

The Boss agent doesn't code. It reads status from all agents, identifies bottlenecks, and delegates. Tonight it noticed that the trading bot's feature list could become a marketing asset — something neither the Binance nor Freelance agent would have seen independently.

What Doesn't Work

Latency. File-based polling at 3-minute intervals means conversations take 6+ minutes for a round-trip. If you need real-time coordination, this isn't it.

Context loss. Each agent session eventually hits context limits and compresses. The SESSION-HANDOFF.md pattern (mandatory update before session end) mitigates this, but knowledge still degrades over long sessions.

Single point of failure. If Boss goes down, nobody delegates. The agents can still work independently, but coordination stops.

User bottleneck. Some actions still need human intervention — submitting Upwork proposals, uploading to Gumroad, posting on Reddit. The agents prepare everything, but the last mile is manual.

The Stack

Claude Code CLI — each instance in its own terminal
Message bus — bash scripts + markdown files in ~/.claude/bus/
Cron polling — CronCreate (Claude Code built-in, session-scoped)
State persistence — SESSION-HANDOFF.md + memory/ per project
Broadcast — broadcast.sh writes to all inboxes simultaneously
Shared rules — _coordination/shared/rules/ read by all agents

Total infrastructure cost: $0. It's just files and Claude Code subscriptions.

How to Build Your Own

Create the bus directory with an inbox file per agent
Write send.sh — 4 lines of bash (shown above)
Add inbox polling to each agent's CLAUDE.md or use CronCreate
Mandate SESSION-HANDOFF.md — agents must document state before session end
Start with 2 agents — a Boss and one Worker. Add more as needed.

The key insight: you don't need a framework. The simplest possible communication mechanism (files) works because Claude is smart enough to parse unstructured messages and act on them.

The hard part isn't the infrastructure. It's designing the right agent boundaries — what each agent owns, what it doesn't, and when it should ask Boss for help vs. acting independently.

Running this system across 16 projects. Building in public — follow for more real architecture, no hype.

I Built a Crypto Bot That Actually Makes Money — Here's What I Learned

DevForge Templates — Thu, 26 Mar 2026 07:49:22 +0000

Everyone builds a crypto bot at some point. Most lose money. Mine didn't — but not for the reasons I expected.

After 101 trades and 83 days of backtesting, here's what actually mattered.

The Strategy That Worked: OBV Accumulation

I tried three different strategies before finding one that held up. Moving average crossovers? Too many false signals. RSI divergence? Works in textbooks, not in crypto's 24/7 volatility.

What worked: On-Balance Volume (OBV) Accumulation.

The idea is simple — track volume flow before price moves. When OBV is accumulating (smart money buying) while price is flat or dipping, that's your signal.

def calculate_obv_accumulation(candles, lookback=20):
    obv = [0]
    for i in range(1, len(candles)):
        if candles[i].close > candles[i-1].close:
            obv.append(obv[-1] + candles[i].volume)
        elif candles[i].close < candles[i-1].close:
            obv.append(obv[-1] - candles[i].volume)
        else:
            obv.append(obv[-1])

    # Accumulation = OBV rising while price is flat
    obv_slope = linear_regression_slope(obv[-lookback:])
    price_slope = linear_regression_slope(
        [c.close for c in candles[-lookback:]]
    )

    return obv_slope > 0 and abs(price_slope) < threshold  # e.g., 0.02

This catches the "smart money" accumulation phase — institutional buying that precedes price moves.

The Numbers (Real, Not Cherry-Picked)

101 backtested trades across Jan–Mar 2026
37.6% win rate — yes, fewer than half my trades win
Risk-to-Reward: 2.33 — but winners are 2.3x bigger than losers
Max drawdown: $0.31 per trade

That win rate looks bad until you do the math:

Expected value = (0.376 × 2.33) - (0.624 × 1.0) = 0.876 - 0.624 = +0.252

Every dollar risked returns $0.25 on average. That's the R:R discovery that changed everything for me — you don't need to be right most of the time, you need your wins to be bigger than your losses.

What I Got Wrong First

Mistake 1: No momentum exhaustion check

My first version would buy at the top of a pump because OBV was "accumulating." Added a momentum exhaustion gate:

def is_momentum_exhausted(candles, period=14):
    recent_gains = sum(
        c.close - c.open for c in candles[-period:]
        if c.close > c.open
    )
    recent_losses = abs(sum(
        c.close - c.open for c in candles[-period:]
        if c.close < c.open
    ))

    if recent_losses == 0:
        return True  # All gains, no pullback = exhausted

    ratio = recent_gains / recent_losses
    return ratio > 3.0  # Overbought threshold

This single check eliminated my worst trades.

Mistake 2: Same position size for everything

BNB and BTC don't move the same way. Volatility-adjusted sizing was the fix — smaller positions on volatile coins, bigger on stable ones. Sounds obvious in hindsight.

Mistake 3: No cooldown between trades

Without a per-symbol cooldown, the bot would enter and exit the same coin 3 times in an hour on noise. Added a 30-minute cooldown per symbol. Trade frequency dropped, profitability went up.

The Testing Obsession

The bot has 1,143 automated tests. That sounds excessive for a side project. It's not.

Crypto trades with real money. A bug isn't "the page looks weird" — it's "I just lost $500 at 3am while sleeping." Every safety mechanism has tests:

Stop-loss caps per coin
Anti-hedge protection (no conflicting long + short)
Position recovery on restart
Score velocity detection (blocks stale signals)

def test_anti_hedge_protection():
    """Bot must never hold LONG and SHORT on same symbol"""
    bot.open_position("BTCUSDT", "LONG")

    with pytest.raises(AntiHedgeError):
        bot.open_position("BTCUSDT", "SHORT")

If you're building anything that touches money, test like your sleep depends on it — because it does.

The Stack

Python 3.12 with asyncio (crypto = lots of concurrent WebSocket streams)
PostgreSQL with asyncpg (connection pooling for high-frequency inserts)
FastAPI dashboard for monitoring
Docker for deployment (one command on any VPS)
Telegram bot for trade alerts on my phone

Total infra cost: ~$5/month on a Hetzner ARM VPS.

What I'd Do Differently

Start with backtesting, not live trading. I wasted 2 weeks on live trades with an unproven strategy. Build the backtester first.
Track MFE (Maximum Favorable Excursion). This tells you how far winning trades go before reversing — critical for setting trailing stops from real data, not gut feeling.
Futures from day one. 80% of my best signals are SHORT opportunities in bear markets. Spot-only means you're blind to half the market.
Don't trust indicators in isolation. OBV alone isn't enough. The scoring system combines multiple signals, and the accumulation pattern is just the strongest weight.

Is It Worth Building Your Own?

If you want to learn: absolutely. I learned more about markets from building this bot than from any course or book.

If you want passive income: maybe. The bot works, but crypto is crypto — strategies degrade, markets change, exchanges update APIs. It's not "set and forget."

If you want guaranteed returns: no. And anyone promising that is lying.

The real value is the framework — once you have a tested backtesting engine, a solid executor, and proper safety mechanisms, you can swap strategies as markets evolve.

Building in public. Follow along for more real numbers, no hype.

I Built 12 Production React Templates with AI - Here Is What I Learned

DevForge Templates — Tue, 24 Mar 2026 14:47:18 +0000

Over the past 3 months, I built 12 production-ready fullstack templates — each with AI features, Docker deployment, and a real database. Not boilerplates with TODO comments. Actual apps with auth, payments, dashboards, and seed data.

Here's what I learned, what worked, and what surprised me.

The Stack (One Stack, Every Template)

Every template runs the same stack:

React 19 + Vite 7 + Mantine 8 (frontend)
Fastify 5 + Prisma 7 + PostgreSQL (backend)
Zustand + TanStack Query (state management)
Zod (shared validation — one schema, zero type drift)
Docker + Traefik (deployment with auto-SSL)

Why the same stack everywhere? Because consistency compounds. Every template shares the same patterns, the same folder structure, the same auth flow. If you learn one, you can navigate all twelve.

The 12 Templates

Full-Stack Starter Kit — Auth, dashboard, AI chat, Stripe. The base everything else builds on.
AgentForge — AI agent management dashboard. Agent registry, task queue, execution logs, CRON scheduling.
CRM — Contact management, pipeline stages, activity tracking.
E-Commerce Dashboard — Product management, orders, inventory, analytics.
SaaS MVP — Multi-tenant, subscription billing, usage tracking.
Booking System — Calendar, appointments, availability management.
HR Platform — Employee directory, leave management, onboarding.
Client Portal — Project tracking, file sharing, invoicing.
Healthcare Dashboard — Patient records, appointments, clinical data.
Restaurant Management — Menu, orders, table management, kitchen display.
Real Estate — Property listings, virtual tours, lead management.
AI Document Processor — Upload, extract, summarize documents with AI.

What Every Template Includes

JWT auth with refresh token rotation + Google OAuth
AI chat widget (Claude/OpenAI API, mock mode included)
Role-based access (admin, user, custom roles)
Docker deployment — one docker compose up for production
Seed data — realistic test data, not empty tables
Mock mode — everything works without API keys

That last point matters more than you'd think. If someone clones your template and has to configure 4 API keys before seeing anything work, most will give up. Mock mode means: clone, install, run. It just works.

Building with AI: What Actually Helped

I used Claude Code for about 70% of the development. Here's what worked:

Great for:

Generating CRUD routes that follow established patterns
Writing Prisma schemas and seed data
Creating React components that match existing UI patterns
Test scaffolding
Docker configuration

Not great for:

Novel architectural decisions (still needs human thinking)
Complex business logic with edge cases
UI design choices (it follows patterns, doesn't create them)

The key was CLAUDE.md — a file that defines project conventions, stack choices, and patterns. With good context, Claude generates code that fits. Without it, you get generic code that needs heavy editing.

Deployment: Docker + Traefik

Every template deploys the same way:

docker compose -f docker-compose.prod.yml up -d

Traefik handles SSL certificates automatically via Let's Encrypt. No nginx config files, no certbot cron jobs. Add a new template? Add Traefik labels. Done.

Currently running 12 live demos on a single VPS, each with its own subdomain and auto-renewing SSL.

The Numbers

12 templates, all passing pnpm build
~50,000 lines of TypeScript across all templates
12 live demos running on Docker
Same VPS, same Traefik instance
Average template: 3,000-5,000 lines of code
Time to deploy a new template: under 30 minutes

What Surprised Me

Mock mode was the highest-impact feature. It took an extra day per template but made the difference between "interesting" and "I can actually use this."
Seed data sells templates. An empty dashboard looks like a skeleton. A dashboard with realistic data looks like a product. Every template ships with 50-200 seed records.
One stack > variety. I initially considered mixing Next.js, Remix, and Vite across templates. Staying with one stack made everything faster and more maintainable.
AI features are table stakes now. In 2024, "has AI chatbot" was a differentiator. In 2026, templates without AI features feel incomplete.
Docker deployment is a selling point. Many developers are tired of Vercel lock-in for dashboards that don't need edge functions. "Self-hosted with Docker" resonates.

What's Next

All templates are live on Gumroad with a 30% launch discount (code: LAUNCH30). Each comes with full TypeScript source, Docker config, seed data, and MIT license.

Live demos and details: devforgetemplates.gumroad.com

I'm also offering custom builds — if you need a template adapted for your specific use case, that's my fastest turnaround since the foundation is already built.

Full disclosure: I built these templates and sell them. This article is my launch announcement, but I tried to make the technical content genuinely useful regardless. Happy to answer questions about the stack, architecture, or deployment setup in the comments.

7 Claudes Working Together: How I Built a Multi-Agent Coordination System

DevForge Templates — Tue, 24 Mar 2026 14:33:05 +0000

What happens when you stop thinking of Claude as a chatbot and start treating it as infrastructure?

I run 7 Claude instances simultaneously — each with a specialized role, shared rules, and a message bus for inter-agent communication. Here's how the system works.

The Problem

I manage 16+ projects across different domains: web templates, marketing automation, infrastructure, research. Context-switching between projects meant losing state constantly. Each conversation with Claude started from scratch.

The Architecture: Boss + Workers

The system has two layers:

Boss Claude — coordinates everything. Reads project states, makes architectural decisions, delegates tasks, monitors progress.

Worker Claudes — specialized agents:

Freelance Claude: marketing, Gumroad products, Upwork proposals
Web Research Claude: market scans, competitor analysis
Infrastructure Claude: Docker deployments, VPS management
And 4 more for specific project domains

Each worker has its own CLAUDE.md with scoped rules, its own .claude/rules/ directory, and its own session handoff files.

Communication: The Message Bus

Agents communicate through a file-based message bus:

~/.claude/bus/
├── inbox-boss.md
├── inbox-freelance.md
├── inbox-web-research.md
├── broadcast.md
└── send.sh

To send a message:

~/.claude/bus/send.sh freelance boss QUESTION "What's the VPS IP for the new project?"

Boss reads the message, responds, and writes the reply to the sender's inbox. Each agent checks its inbox via a CronCreate job.

Shared Rules

All agents follow core rules stored in a shared location:

_coordination/shared/rules/
├── core.md        # 7 universal rules
├── errors.md      # Shared error log
└── user-feedback.md  # User corrections

Rules include: think deeper before acting, never silently guess, communicate progress (DOING/FOUND/NEXT), learn from mistakes, and context budget management.

When one agent discovers a bug or limitation, it records it in errors.md. Every other agent reads this at session start — so a mistake happens once across the entire system, not once per agent.

State Management

Each agent maintains its own state:

_coordination/agents/freelance/
├── state.md    # Current status, what I'm working on
├── history.md  # Append-only decision log
└── charter.md  # Agent's role and responsibilities

Before session end, every agent updates its state. The next session (or another agent checking in) gets full context without re-explaining anything.

Hooks > CLAUDE.md

The most important lesson: use hooks for hard rules, not CLAUDE.md instructions.

CLAUDE.md instructions can be forgotten in long sessions as context grows. Hooks fire mechanically every time:

{
  "hooks": {
    "UserPromptSubmit": [{
      "command": "cat ~/.claude/bus/inbox-freelance.md"
    }]
  }
}

This hook checks the inbox on every user message — impossible to forget.

CronCreate for Background Tasks

Each agent sets up recurring tasks:

CronCreate: */15 * * * * — Check inbox
CronCreate: 17 * * * * — Check Gumroad sales

The Boss broadcasts to all agents when shared rules change or when cross-project decisions are made.

What Actually Works

Specialization beats generalization. A Claude with 60 lines of focused CLAUDE.md outperforms one with 500 lines of "know everything" context.
File-based communication is surprisingly robust. No databases, no APIs, no infrastructure to maintain. Just markdown files and shell scripts.
Session handoff files are essential. Without them, every new session starts cold. With them, agents resume exactly where they left off.
Shared error logs prevent repeated mistakes. One agent hits a platform limitation, all agents learn about it immediately.

What Doesn't Work

Real-time coordination is slow. File-based messaging has inherent latency (cron interval). If you need sub-second agent coordination, this isn't the architecture.
Context budget is real. ETH Zurich research confirmed: verbose CLAUDE.md files actually reduce performance. Keep each agent's context lean.
Debugging cross-agent issues is hard. When Boss delegates to Freelance, which delegates research to Web Research — tracing a failure through 3 agents requires reading 3 separate logs.

The Numbers

7 active Claude instances
16 projects managed
~50 messages/day across the bus
State files updated 20+ times/day
Shared rules: 7 core rules, 15+ error entries
Total coordination overhead: ~5% of each session

Would I Recommend This?

For a single project? No — overkill. Use one Claude with a good CLAUDE.md.

For managing multiple projects with different contexts? Absolutely. The specialization alone is worth it. And the shared learning (errors.md, user-feedback.md) means the entire system gets smarter every day.

The key insight: Claude works best when it has focused context and clear boundaries. Seven specialized Claudes > one Claude trying to know everything.

How I Built a Crypto Trading Bot with Claude Code in 3 Weeks

DevForge Templates — Tue, 24 Mar 2026 14:33:03 +0000

Building a crypto trading bot sounds glamorous until you're debugging why your scoring algorithm triggered a buy at 3 AM on a coin that dropped 40% by morning.

Here's what I learned building a production crypto trading system with Claude Code as my primary development tool.

The Architecture

The bot has 22 scoring components that analyze different market signals: volume spikes, price momentum, RSI divergence, order book depth, social sentiment, and more. Each component returns a weighted score between -1 and 1. The aggregate score determines buy/sell/hold.

The backend runs on Fastify 5 with TypeScript. PostgreSQL stores historical scores and trades. A React dashboard shows real-time portfolio status, active signals, and historical performance.

Why Claude Code Changed Everything

Before Claude Code, I was context-switching between docs, Stack Overflow, and my editor constantly. With Claude Code, the workflow became:

Describe the scoring component I need
Claude reads the existing codebase (CLAUDE.md + shared types)
It generates the component following the established pattern
I review, test, iterate

The key was the CLAUDE.md file. I defined the project structure, naming conventions, and the scoring component interface once. Every new component followed the same pattern automatically.

22 Scoring Components in Detail

Each component is a standalone module with the same interface:

interface ScoringComponent {
  name: string;
  weight: number;
  analyze(data: MarketData): Promise<Score>;
}

interface Score {
  value: number; // -1 to 1
  confidence: number; // 0 to 1
  reasoning: string;
}

The reasoning field was critical for debugging. When a trade goes wrong, you can trace back through each component's reasoning to understand what the aggregate model "thought."

Some components that worked well:

Volume-Price Divergence: When volume spikes but price stays flat, something is about to move
Multi-Timeframe RSI: RSI on 5m, 15m, 1h, 4h — agreement across timeframes = strong signal
Order Book Imbalance: >3:1 bid/ask ratio at key levels often precedes moves

Components that looked good in backtests but failed live:

Social Sentiment: Too noisy, too slow. By the time sentiment shifts measurably, the move already happened
Correlation Clustering: BTC correlation breaks down exactly when you need it most — during crashes

Testing: 1000+ Tests

Every scoring component has unit tests with historical data. But the real value came from integration tests that replay entire market days and verify the aggregate score matches expected behavior.

pnpm test
# 1,047 tests passing
# Coverage: 89% statements, 94% branches on scoring

Claude Code generated most of the test scaffolding. I described the edge cases, it wrote the tests. Saved days of tedious work.

15 Deploys Per Day

With Docker + Traefik on a VPS, deploying is one command:

rsync -az . vps:~/crypto-bot/ && ssh vps 'cd crypto-bot && docker compose up -d --build'

During active development, I was deploying 10-15 times per day. Hot-fixing a scoring weight, deploying, watching the next few signals, adjusting. The tight feedback loop was essential.

Lessons Learned

Backtesting lies. Every backtest has survivorship bias. Your bot will encounter market conditions that don't exist in your test data.
Start with paper trading. Run your bot with zero real money for at least 2 weeks. Track what it would have done.
Position sizing matters more than signal quality. A mediocre signal with good risk management beats a great signal with poor position sizing.
Claude Code excels at repetitive patterns. 22 components that all follow the same interface? Perfect for AI-assisted development. Novel algorithm design? Still needs human thinking.
CLAUDE.md is your best investment. 30 minutes writing a good CLAUDE.md saves hours of correcting AI-generated code that doesn't match your patterns.

The Stack

Backend: Fastify 5 + TypeScript + Prisma 7 + PostgreSQL
Frontend: React 19 + Vite + Mantine (dashboard)
Infra: Docker + Traefik + VPS
AI Dev: Claude Code with custom CLAUDE.md
Testing: Vitest, 1000+ tests

Would I Do It Again?

Yes, but I'd skip the social sentiment component entirely and invest that time in better position sizing logic. The scoring is 30% of the system. Risk management is 70%.

And I'd use Claude Code from day one instead of starting manually and migrating halfway through. The CLAUDE.md-driven workflow is genuinely faster for structured, pattern-heavy codebases.

One Schema, Zero Drift: How Zod Keeps My Frontend and Backend in Sync

DevForge Templates — Mon, 23 Mar 2026 16:18:59 +0000

TypeScript catches a lot of bugs. But it has a blind spot: the network boundary. Your server returns { createdAt: string } instead of { created_at: string }, and TypeScript won't say a word. You'll find out at runtime, when the UI renders "undefined" where a date should be.

This happens because TypeScript types are erased at compile time. They describe what your code expects, not what actually arrives over the wire. Your frontend type says User, but the API could return anything -- a different shape, extra fields, missing fields, wrong types. TypeScript just trusts you.

Zod fixes this by making validation and types the same thing. You define a schema once, in a shared folder, and both sides of the app use it. The server validates incoming requests against it. The client validates forms against it. TypeScript infers types from it. One source of truth, enforced at runtime and compile time.

The Shared Schema

Start with a /shared folder at the project root. Both server and client import from here:

/shared/schemas/user.ts
/server/routes/users.ts      ← imports from shared
/client/features/users/       ← imports from shared

Here's a user creation schema:

// shared/schemas/user.ts
import { z } from "zod";

export const CreateUserSchema = z.object({
  email: z.string().email("Invalid email address"),
  name: z.string().min(2, "Name must be at least 2 characters"),
  role: z.enum(["admin", "member", "viewer"]),
  avatarUrl: z.string().url().optional(),
});

export type CreateUser = z.infer<typeof CreateUserSchema>;
// → { email: string; name: string; role: "admin" | "member" | "viewer"; avatarUrl?: string }

z.infer extracts the TypeScript type from the schema. You never write the type by hand. If you add a field to the schema, the type updates automatically, and every file that imports CreateUser gets type-checked against the new shape.

Server: Fastify Request Validation

On the backend, use the schema to validate incoming request bodies. Invalid data gets rejected before your route handler ever runs:

// server/routes/users.ts
import { CreateUserSchema } from "../../shared/schemas/user.js";

fastify.post("/api/users", async (request, reply) => {
  const parsed = CreateUserSchema.safeParse(request.body);

  if (!parsed.success) {
    return reply.status(400).send({
      error: "Validation failed",
      issues: parsed.error.issues,
    });
  }

  // parsed.data is fully typed as CreateUser
  const user = await prisma.user.create({
    data: {
      email: parsed.data.email,
      name: parsed.data.name,
      role: parsed.data.role,
      avatarUrl: parsed.data.avatarUrl,
    },
  });

  return reply.status(201).send(user);
});

safeParse returns either { success: true, data: CreateUser } or { success: false, error: ZodError }. No try/catch needed. The data inside parsed.data is guaranteed to match the schema -- not just typed, actually validated.

Client: React Hook Form + Mantine

The same schema drives form validation on the frontend. With @hookform/resolvers/zod, you connect the Zod schema directly to React Hook Form:

// client/features/users/CreateUserForm.tsx
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { TextInput, Select, Button } from "@mantine/core";
import { CreateUserSchema, type CreateUser } from "../../../shared/schemas/user.js";

export function CreateUserForm() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<CreateUser>({
    resolver: zodResolver(CreateUserSchema),
  });

  const onSubmit = async (data: CreateUser) => {
    // data is validated and typed -- matches exactly what the server expects
    await fetch("/api/users", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    });
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <TextInput
        label="Email"
        {...register("email")}
        error={errors.email?.message}
      />
      <TextInput
        label="Name"
        {...register("name")}
        error={errors.name?.message}
      />
      <Select
        label="Role"
        data={["admin", "member", "viewer"]}
        {...register("role")}
        error={errors.role?.message}
      />
      <Button type="submit">Create User</Button>
    </form>
  );
}

The error messages you defined in the schema ("Invalid email address", "Name must be at least 2 characters") show up directly in the form. No duplication. If you change a validation rule in the schema, both the server rejection message and the client form error update at the same time.

What Happens When You Change a Field

Say you rename role to accessLevel in the schema:

export const CreateUserSchema = z.object({
  email: z.string().email("Invalid email address"),
  name: z.string().min(2, "Name must be at least 2 characters"),
  accessLevel: z.enum(["admin", "member", "viewer"]),  // renamed
  avatarUrl: z.string().url().optional(),
});

Run tsc and you'll immediately see errors in every file that references role -- the server route, the form component, any tests. Nothing slips through. This is the whole point: the schema is the contract, and TypeScript enforces it at compile time across both sides.

Advanced Patterns

.transform(): Reshape Data at Parse Time

Normalize data as it enters the system. The schema describes both the input and the output:

export const CreateUserSchema = z.object({
  email: z.string().email().transform((e) => e.toLowerCase().trim()),
  name: z.string().min(2),
  role: z.enum(["admin", "member", "viewer"]),
});

Now parsed.data.email is always lowercase and trimmed, regardless of what the client sends. The transform runs during safeParse, so your route handler never deals with messy input.

.refine(): Custom Validation Logic

For rules that go beyond basic type checks:

export const DateRangeSchema = z
  .object({
    startDate: z.coerce.date(),
    endDate: z.coerce.date(),
  })
  .refine((data) => data.endDate > data.startDate, {
    message: "End date must be after start date",
    path: ["endDate"],
  });

The path option tells React Hook Form which field to attach the error to. The form shows the message under the end date input without any extra wiring.

Discriminated Unions for API Responses

Type-safe API responses where the structure depends on a status field:

export const ApiResponse = z.discriminatedUnion("status", [
  z.object({ status: z.literal("success"), data: UserSchema }),
  z.object({ status: z.literal("error"), message: z.string(), code: z.number() }),
]);

type ApiResponse = z.infer<typeof ApiResponse>;
// TypeScript knows: if status === "success", then .data exists
// if status === "error", then .message and .code exist

This pattern eliminates if (response.data) guessing. You check status, and TypeScript narrows the type automatically.

Error Handling: Zod Errors to User-Friendly Messages

Zod's error structure is designed for programmatic consumption. Each issue includes a path (which field), a code (what went wrong), and a message (human-readable). You can map these to form fields directly:

function formatErrors(error: z.ZodError): Record<string, string> {
  const formatted: Record<string, string> = {};
  for (const issue of error.issues) {
    const field = issue.path.join(".");
    if (!formatted[field]) {
      formatted[field] = issue.message;
    }
  }
  return formatted;
}

// Server returns: { issues: [{ path: ["email"], message: "Invalid email address", code: "invalid_string" }] }
// formatErrors turns it into: { email: "Invalid email address" }

This means your server's 400 response can be displayed directly in the form -- the same error format, whether validation runs client-side or server-side.

Project Structure

Here's how the shared schemas fit into a fullstack monorepo:

shared/
  schemas/
    user.ts         # CreateUserSchema, UpdateUserSchema, UserSchema
    project.ts      # CreateProjectSchema, ProjectFilters, etc.
    auth.ts         # LoginSchema, RegisterSchema
    common.ts       # PaginationSchema, SortSchema, IdParam
  index.ts          # Re-exports everything

server/
  routes/
    users.ts        # imports CreateUserSchema for validation
    projects.ts

client/
  features/
    users/
      CreateUserForm.tsx   # imports CreateUserSchema for form validation
      UserList.tsx
    projects/

shared/schemas/common.ts is where you put reusable pieces:

// shared/schemas/common.ts
export const PaginationSchema = z.object({
  page: z.coerce.number().int().positive().default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20),
});

export const IdParamSchema = z.object({
  id: z.string().cuid(),
});

Every route that accepts pagination params uses the same schema. Every form that includes an ID validates it the same way. One change propagates everywhere.

What This Eliminates

The pattern removes an entire class of bugs that TypeScript alone can't catch:

Field renames that break one side but not the other
Type mismatches between what the API sends and what the UI expects
Duplicated validation with rules that drift out of sync
Runtime surprises from unvalidated external data

The cost is one extra dependency and a shared/ folder. The return is that your frontend and backend are provably talking about the same data shapes -- checked by the compiler, enforced at runtime, defined in one place.