Claude Code + Agents: Advanced Configuration and Autonomous Workflows

Beyond the Basics

If you've used Claude Code for a while, you know the basics: open a project, describe a task, Claude does it. That's useful, but it's still mostly reactive — you prompt, Claude responds.

The real power is in making Claude operate autonomously: running on schedules, maintaining context across sessions without losing state, spawning subagents to parallelize work, and wiring into your existing tools via MCP servers.

This guide covers the full configuration stack.

---

The CLAUDE.md Architecture

CLAUDE.md is the most underused feature in Claude Code. It's a markdown file you place in your project (or home directory) that Claude reads at the start of every session. Think of it as a persistent system prompt that loads automatically.

Where to put it

Claude reads CLAUDE.md files in a hierarchy:

1. ~/.claude/CLAUDE.md — global, applies to every project
2. /your/project/CLAUDE.md — project-specific, checked into the repo
3. /your/project/subdir/CLAUDE.md — directory-specific overrides

All three are loaded and merged. More specific files take precedence.

What to put in it

The more specific and opinionated, the better. Generic instructions produce generic behavior.

Global ~/.claude/CLAUDE.md — role and authority:

# My AI CTO

You are my technical cofounder. You have full authority to:
- Choose tech stack and architecture
- Write, edit, and delete code
- Run shell commands and tests
- Deploy to staging

You do NOT have authority to:
- Spend money on paid services without flagging it
- Push to production without my confirmation

## Communication style
- Be concise — max 3 sentences per update
- Lead with the action taken, not the reasoning
- Surface blockers immediately, don't work around them silently

## Tech preferences
- TypeScript over JavaScript
- Bun over Node.js
- Drizzle ORM over Prisma
- Tailwind over CSS modules

Project CLAUDE.md — codebase context:

# Project: AI Bazaar

Next.js 15 app with App Router. Content in /content/guides/*.mdx (gray-matter frontmatter).
Database: SQLite via Drizzle ORM (drizzle.config.ts). Deployed on Vercel.

## Key paths
- /src/app/ — Next.js routes
- /src/lib/ — Shared utilities
- /content/ — MDX content files
- /src/components/ — React components (Tailwind styling)

## Commands
- `bun dev` — start dev server (port 3000)
- `bun test` — run tests
- `bun run db:push` — push schema changes

## Rules
- Never commit .env files
- Always run `bun test` before marking a task done
- Use the existing component library — don't invent new patterns

CLAUDE.md for non-coding projects

CLAUDE.md works for any workflow, not just code:

# Research Assistant

You are a crypto market researcher. When I give you a topic:
1. Search for 5+ recent sources (< 30 days)
2. Summarize key points in bullets
3. Flag contrarian views separately
4. Score conviction level 1-10 with reasoning
5. Suggest 3 follow-up questions

Output format: always use the Research Report template in /templates/research.md

---

Subagents and Parallelization

Claude Code can spawn subagents — parallel Claude instances that work on independent tasks simultaneously. This is how you take a 4-hour sequential task and turn it into a 45-minute parallel one.

How subagents work

When Claude Code encounters multiple independent tasks, it can delegate them to parallel subagents:

• Each subagent gets its own context and tools
• Results are passed back to the orchestrating Claude
• The orchestrator synthesizes and continues

Triggering parallel work

Be explicit in your prompts:

Run these tasks in parallel:
1. Write the API endpoint for /api/users (in src/app/api/users/route.ts)
2. Write the React component for the user dashboard (in src/components/dashboard.tsx)
3. Write tests for both (in src/__tests__/)

Report back when all three are done.

Claude Code will launch three parallel workstreams. For large projects with many independent files, this can 3-5x your throughput.

Subagent scope control

Limit what each subagent can touch to prevent conflicts:

Agent 1: Work ONLY in src/app/api/ — do not touch any other directories
Agent 2: Work ONLY in src/components/ — do not touch any other directories
Agent 3: Work ONLY in src/__tests__/ — read access to both above directories

---

MCP Servers: Extending Claude's Capabilities

MCP (Model Context Protocol) is Anthropic's standard for giving Claude access to external tools and data sources. Each MCP server gives Claude new capabilities — browser control, database access, Slack, GitHub, and more.

Installing MCP servers

MCP servers are defined in your Claude Code config (~/.claude/mcp.json or via claude mcp add):

# Add a filesystem server (gives Claude access to specific directories)
claude mcp add filesystem npx @modelcontextprotocol/server-filesystem ~/projects

# Add a GitHub server
claude mcp add github npx @modelcontextprotocol/server-github

# Add a Postgres database
claude mcp add postgres npx @modelcontextprotocol/server-postgres postgresql://localhost/mydb

# Add Playwright for browser automation
claude mcp add playwright npx @modelcontextprotocol/server-playwright

High-value MCP servers

| Server | What it gives Claude | Use case | |---|---|---| | @modelcontextprotocol/server-filesystem | Read/write files in specified paths | Cross-project file access | | @modelcontextprotocol/server-github | GitHub API (PRs, issues, files) | Code review, issue management | | @modelcontextprotocol/server-postgres | Direct DB queries | Debugging, migrations | | @modelcontextprotocol/server-playwright | Browser control | Testing, scraping, automation | | @modelcontextprotocol/server-slack | Post/read Slack messages | Workflow notifications | | Context7 (mcp-context7) | Live library documentation | Always up-to-date API references |

MCP configuration file

Full config at ~/.claude/mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-playwright"],
      "env": {
        "PLAYWRIGHT_BROWSERS_PATH": "/Users/you/.playwright-mcp/browsers"
      }
    }
  }
}

---

Hooks: Running Code Around Claude's Actions

Hooks are shell commands that Claude Code runs automatically at specific lifecycle events. They're the bridge between Claude's actions and your existing tooling.

Hook types

| Hook | When it fires | |---|---| | PreToolUse | Before Claude calls any tool | | PostToolUse | After Claude calls any tool | | Notification | When Claude has a notification for you | | UserPromptSubmit | When you submit a prompt | | Stop | When Claude finishes a task |

Hook configuration (~/.claude/settings.json)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "cd $(git rev-parse --show-toplevel) && bun run typecheck 2>&1 | tail -5"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/scripts/telegram-notify.sh --done \"Claude finished a task\""
          }
        ]
      }
    ]
  }
}

Practical hook recipes

Auto-typecheck after every file write:

# Run TypeScript typecheck after any Write tool call
bun run tsc --noEmit 2>&1 | head -20

Log every shell command Claude runs:

# Append to audit log
echo "$(date): $CLAUDE_TOOL_INPUT" >> ~/.claude/audit.log

Notify via Telegram when Claude is done:

~/.claude/scripts/telegram-notify.sh --done "Task complete in $(pwd)"

Block writes to production config files:

# Exit code 2 blocks the tool call and sends the message to Claude
if echo "$CLAUDE_TOOL_INPUT" | grep -q "production"; then
  echo "Blocked: cannot write to production config" >&2
  exit 2
fi

---

Autonomous Workflows (Claude Without You)

The --dangerously-skip-permissions pattern

For fully autonomous Claude sessions where you don't want approval prompts:

claude --dangerously-skip-permissions

Combine this with a goal in CLAUDE.md and Claude will run until the task is done.

Pattern: scheduled nightly jobs

# Run as a cron job or launchd agent
#!/bin/bash
cd ~/projects/ai-bazaar
claude --dangerously-skip-permissions \
  --print \
  "Check for any failing tests, fix them, and commit the fixes with message 'fix: automated test repair'"

The two-way Telegram loop

For longer autonomous runs, wire Claude to Telegram so it can ask questions mid-task and receive answers:

# Claude sends a question
~/.claude/scripts/telegram-notify.sh --question "Which approach: A (REST) or B (GraphQL)?"

# Claude waits for your reply
reply=$(~/.claude/scripts/telegram-wait.sh 600)

# Continue based on reply
if echo "$reply" | grep -qi "GraphQL\|B"; then
  # take path B
fi

This gives you an async human-in-the-loop without blocking the session.

Context management for long sessions

Claude Code sessions degrade as context fills. Strategies to keep them healthy:

1. Save milestones to memory: After each major task, write a summary to ~/.claude/projects/memory/MEMORY.md
2. Use /gsd:pause-work to snapshot state before a session gets too long
3. Delegate research to subagents: Research burns context fast. Have a subagent do research, then pass only the summary to your main agent
4. Pipe large outputs: If a command returns 1000 lines, pipe to a file and tell Claude to read the file — don't let it load into context

---

Permission Tiers

Configure Claude's permission level in ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(bun:*)",
      "Bash(git:*)",
      "Bash(curl:*)",
      "Write(**/*.ts)",
      "Write(**/*.tsx)",
      "Write(**/*.mdx)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(~/.env)",
      "Read(**/*private*key*)",
      "Read(**/*secret*)"
    ]
  }
}

This gives Claude broad write access to TypeScript and MDX files, full git and bun access, but blocks destructive commands and secret file reads.

---

Production Checklist

Before treating Claude Code as a production automation tool:

• [ ] CLAUDE.md defines clear authority boundaries (what Claude can and can't do)
• [ ] Deny rules block access to .env, private keys, and production configs
• [ ] Hooks run typecheck/test after writes
• [ ] A Telegram or email notification fires when autonomous sessions complete or fail
• [ ] Long sessions use pause/resume to prevent context degradation
• [ ] All autonomous runs have audit logs

---

Want help designing your Claude automation pipeline or CLAUDE.md architecture? Book a 30-minute call and we'll map it out.