claude-agent-starter

Production-ready starter for building AI agents with the Claude Agent SDK. Includes subagents, hooks, session management, and real-world examples.

What is the Claude Agent SDK?

The Claude Agent SDK gives Claude a computer — not just a prompt. It's the same agent loop that powers Claude Code, now available as a library. Your agents can read files, run commands, search the web, and edit code autonomously.

This starter provides patterns and examples so you don't start from scratch.

Features

• Ready-to-run agent examples (code reviewer, research assistant, refactoring agent)
• Subagent orchestration — parallel specialized agents
• Session persistence — multi-phase workflows with context
• Hook system — logging, auditing, approval gates
• TypeScript with strict mode
• Structured as reusable modules

Quick Start

# Clone and install
git clone https://github.com/autosergach/claude-agent-starter.git
cd claude-agent-starter
npm install

# Set your API key
export ANTHROPIC_API_KEY=your-key-here

# Run an example
npx ts-node examples/code-reviewer.ts ./path/to/project
npx ts-node examples/research-agent.ts "How do MCP servers work?"
npx ts-node examples/refactor-agent.ts ./src/legacy-module.ts

Project Structure

src/
├── agents/
│   ├── code-reviewer.ts      # Read-only code analysis agent
│   ├── research-agent.ts     # Web research with subagents
│   └── refactor-agent.ts     # Code refactoring with safety checks
├── hooks/
│   ├── audit-logger.ts       # Log all tool calls to file
│   └── edit-guard.ts         # Require approval for destructive edits
├── utils/
│   ├── runner.ts             # Agent execution wrapper
│   └── session.ts            # Session management helpers
examples/
├── code-reviewer.ts          # Run code review on a directory
├── research-agent.ts         # Research a topic
└── refactor-agent.ts         # Refactor a file safely

Examples

1. Code Reviewer (Read-Only)

Safe agent that analyzes code without modifying anything:

import { query } from '@anthropic-ai/claude-agent-sdk';

for await (const message of query({
  prompt: `Review the code in ./src for:
    - Security vulnerabilities
    - Performance issues
    - Architecture violations
    Write a summary with severity ratings.`,
  options: {
    allowedTools: ['Read', 'Glob', 'Grep'],
    permissionMode: 'default',
    maxTurns: 20,
  },
})) {
  if (message.type === 'assistant') {
    for (const block of message.message.content) {
      if ('text' in block) process.stdout.write(block.text);
    }
  }
}

2. Research Agent with Subagents

Parallel research with specialized sub-agents:

import { query } from '@anthropic-ai/claude-agent-sdk';

const agents = {
  'web-researcher': {
    description: 'Searches the web for information',
    prompt: 'You are a research specialist. Search for comprehensive, current information.',
    tools: ['WebSearch', 'WebFetch'],
  },
  'code-analyst': {
    description: 'Analyzes code repositories and documentation',
    prompt: 'You are a code analysis specialist. Read and summarize code patterns.',
    tools: ['Read', 'Glob', 'Grep'],
  },
};

for await (const message of query({
  prompt: 'Research how major companies implement MCP servers. Find patterns and best practices.',
  options: {
    allowedTools: ['Read', 'WebSearch', 'WebFetch', 'Agent'],
    agents,
    maxTurns: 30,
  },
})) {
  // Claude orchestrates subagents automatically
}

3. Refactoring Agent with Hooks

Safe code refactoring with audit trail:

import { query } from '@anthropic-ai/claude-agent-sdk';

const hooks = {
  PostToolUse: [
    {
      matcher: 'Edit|Write',
      hooks: [
        async (input: any) => {
          const file = input.tool_input?.file_path ?? 'unknown';
          console.log(`[AUDIT] Modified: ${file} at ${new Date().toISOString()}`);
          return {};
        },
      ],
    },
  ],
};

for await (const message of query({
  prompt: 'Refactor ./src/legacy-module.ts to use async/await instead of callbacks. Run tests after.',
  options: {
    allowedTools: ['Read', 'Edit', 'Glob', 'Grep', 'Bash'],
    permissionMode: 'acceptEdits',
    hooks,
  },
})) {
  // Agent refactors with full audit logging
}

Session Management

Multi-phase workflows with context preservation:

import { query } from '@anthropic-ai/claude-agent-sdk';

let sessionId: string | undefined;

// Phase 1: Analysis (read-only, safe)
for await (const message of query({
  prompt: 'Analyze the authentication module. Identify all security issues.',
  options: {
    allowedTools: ['Read', 'Glob', 'Grep'],
    permissionMode: 'default',
  },
})) {
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id;
  }
}

// Phase 2: Fix (has full context from phase 1)
for await (const message of query({
  prompt: 'Now fix the critical security issues you found.',
  options: {
    allowedTools: ['Read', 'Edit', 'Bash'],
    permissionMode: 'acceptEdits',
    resume: sessionId,
  },
})) {
  // Agent remembers everything from phase 1
}

Permission Modes

Mode	Behavior	Use case
default	Ask for approval on writes	Interactive development
acceptEdits	Auto-approve file edits, ask for Bash	Trusted refactoring
dontAsk	Skip approval prompts entirely	CI/CD pipelines
bypassPermissions	No restrictions	Testing only

Configuration

const options = {
  // Tool access
  allowedTools: ['Read', 'Edit', 'Glob', 'Grep', 'Bash'],

  // Permission level
  permissionMode: 'acceptEdits',

  // Custom system prompt
  systemPrompt: 'You are a senior TypeScript engineer...',

  // Working directory
  cwd: '/path/to/project',

  // Limits
  maxTurns: 50,

  // Subagent definitions
  agents: { /* ... */ },

  // Lifecycle hooks
  hooks: { /* ... */ },

  // Resume from previous session
  resume: 'session-id',
};

Related

• Claude Agent SDK Docs
• Claude Agent SDK Demos
• Building Effective Agents

Author

Alex Rogov — Full-Stack JS Architect, Amsterdam

• Twitter: @Alex_Rogov_js
• LinkedIn: rogov-alex
• GitHub: autosergach

License

MIT