DEV Community

Alex Rogov
Alex Rogov

Posted on • Originally published at alexrogov.hashnode.dev

Building an AI Coding Agent from Scratch with Claude Agent SDK

#ai #javascript #typescript #tutorial

Building an AI Coding Agent from Scratch with Claude Agent SDK

You've been using Claude as a chatbot — paste code, get a reply, paste again. That works. But there's a different mode entirely: give Claude a set of tools and a goal, and let it figure out the steps itself.

That's what an agent is. Not a smarter autocomplete — a loop that reads files, runs checks, makes decisions, and calls your code until the job is done.

In this article, I'll walk through building a TypeScript code review agent using Anthropic's SDK. It will autonomously scan your project, find issues, and output a structured report — without you prompting it at each step.

What Makes Something an "Agent"

A regular API call is stateless: you send a prompt, you get a response. An agent is different in three ways:

  1. Tools — it can call functions you define (read a file, run a command, query an API)
  2. A loop — after using a tool, it sees the result and decides what to do next
  3. A goal — it keeps going until it reaches a terminal state, not until the context window fills up

The Anthropic SDK exposes this through tool_use content blocks. Claude returns a tool call, you execute it, you append the result, and Claude continues. You own the loop.

What We're Building

A CLI agent that takes a TypeScript project path and produces a code review report:

$ npx ts-node agent.ts ./src

🔍 Reading project structure...
📂 Found 12 TypeScript files
🔎 Checking src/services/UserService.ts...
⚠️  Found 3 issues in src/services/UserService.ts
✅ No issues in src/repositories/UserRepo.ts
...
📋 Report saved to review-report.md
Enter fullscreen mode Exit fullscreen mode

The agent decides which files to read, in what order, and how deep to go — we just give it the tools and the goal.

Project Setup 

mkdir ts-review-agent && cd ts-review-agent
npm init -y
npm install @anthropic-ai/sdk
npm install -D typescript ts-node @types/node
npx tsc --init --strict --module commonjs --target es2020
Enter fullscreen mode Exit fullscreen mode

Create agent.ts:

import Anthropic from '@anthropic-ai/sdk';
import * as fs from 'fs';
import * as path from 'path';

const client = new Anthropic(); // reads ANTHROPIC_API_KEY from env
Enter fullscreen mode Exit fullscreen mode

Defining the Tools

The agent needs three capabilities: list files, read a file, and write the final report.

const tools: Anthropic.Tool[] = [
  {
    name: 'list_files',
    description: 'List all TypeScript files in a directory recursively',
    input_schema: {
      type: 'object',
      properties: {
        directory: { type: 'string', description: 'Absolute or relative path to directory' }
      },
      required: ['directory']
    }
  },
  {
    name: 'read_file',
    description: 'Read the contents of a TypeScript file',
    input_schema: {
      type: 'object',
      properties: {
        file_path: { type: 'string', description: 'Path to the file to read' }
      },
      required: ['file_path']
    }
  },
  {
    name: 'write_report',
    description: 'Write the final code review report to a markdown file',
    input_schema: {
      type: 'object',
      properties: {
        content: { type: 'string', description: 'Markdown content of the report' },
        output_path: { type: 'string', description: 'Where to save the report' }
      },
      required: ['content', 'output_path']
    }
  }
];
Enter fullscreen mode Exit fullscreen mode

Tool definitions are just JSON Schema — Claude reads the description to understand when and how to use each one. The descriptions matter more than you'd think.

Implementing the Tool Executor 

type ToolInput = Record<string, string>;

function executeTool(name: string, input: ToolInput): string {
  switch (name) {
    case 'list_files': {
      const dir = input.directory;
      const files: string[] = [];
      function walk(current: string) {
        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
          const full = path.join(current, entry.name);
          if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
            walk(full);
          } else if (entry.isFile() && entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
            files.push(full);
          }
        }
      }
      walk(dir);
      return JSON.stringify(files);
    }

    case 'read_file': {
      try {
        return fs.readFileSync(input.file_path, 'utf-8');
      } catch {
        return `Error: could not read ${input.file_path}`;
      }
    }

    case 'write_report': {
      fs.writeFileSync(input.output_path, input.content, 'utf-8');
      return `Report written to ${input.output_path}`;
    }

    default:
      return `Unknown tool: ${name}`;
  }
}
Enter fullscreen mode Exit fullscreen mode

This is intentionally simple. In production you'd add path sanitization, size limits, and timeouts — but the pattern is the same.

The Agent Loop

This is the core. Everything else is setup; this is where the agent runs.

async function runAgent(projectPath: string): Promise<void> {
  const messages: Anthropic.MessageParam[] = [
    {
      role: 'user',
      content: `You are a TypeScript code reviewer. Review the project at "${projectPath}".

Steps:
1. List all TypeScript files in the project
2. Read and review each file for: type safety issues, unused variables, any-typed params, missing error handling, and obvious logic bugs
3. Write a structured markdown report with findings, severity (error/warning/info), and suggested fixes

Be thorough but focus on real issues, not style preferences.`
    }
  ];

  console.log('🤖 Agent starting...
');

  while (true) {
    const response = await client.messages.create({
      model: 'claude-opus-4-7',
      max_tokens: 4096,
      tools,
      messages
    });

    // Add assistant response to history
    messages.push({ role: 'assistant', content: response.content });

    // Check if we're done
    if (response.stop_reason === 'end_turn') {
      console.log('
✅ Agent finished.');
      break;
    }

    // Process tool calls
    if (response.stop_reason === 'tool_use') {
      const toolResults: Anthropic.ToolResultBlockParam[] = [];

      for (const block of response.content) {
        if (block.type === 'tool_use') {
          console.log(`🔧 ${block.name}(${JSON.stringify(block.input).slice(0, 60)}...)`);
          const result = executeTool(block.name, block.input as ToolInput);
          toolResults.push({
            type: 'tool_result',
            tool_use_id: block.id,
            content: result
          });
        } else if (block.type === 'text' && block.text) {
          console.log(`💭 ${block.text.slice(0, 80)}...`);
        }
      }

      // Append tool results and continue
      messages.push({ role: 'user', content: toolResults });
    }
  }
}

// Entry point
const targetPath = process.argv[2] || '.';
runAgent(path.resolve(targetPath)).catch(console.error);
Enter fullscreen mode Exit fullscreen mode

The loop is simple: send messages → get response → if tool calls, execute them and append results → repeat until end_turn.

Running It 

export ANTHROPIC_API_KEY=your_key_here
npx ts-node agent.ts ./src
Enter fullscreen mode Exit fullscreen mode

Output (truncated):

🤖 Agent starting...

🔧 list_files({"directory":"/Users/alex/project/src"}...)
🔧 read_file({"file_path":"/Users/alex/project/src/services/AuthService.ts"}...)
💭 Reviewing AuthService.ts — found potential issues with token expiry...
🔧 read_file({"file_path":"/Users/alex/project/src/middleware/auth.ts"}...)
🔧 write_report({"content":"# Code Review Report

## Summary...","output_p}...)

✅ Agent finished.
Enter fullscreen mode Exit fullscreen mode

The agent reads files in an order it decides, cross-references related files, and writes a cohesive report — without you prompting each step.

Patterns That Matter in Production

1. Token budget awareness. Each iteration appends to messages. For large codebases, you'll hit limits fast. Either batch files (give the agent 5 files per run) or summarize intermediate results.

// Rough token estimate before each request
const estimatedTokens = JSON.stringify(messages).length / 4;
if (estimatedTokens > 150_000) {
  // Summarize or paginate
}
Enter fullscreen mode Exit fullscreen mode

2. Max iterations guard. Agents can loop unexpectedly. Add a hard limit:

let iterations = 0;
while (iterations++ < 20) { ... }
Enter fullscreen mode Exit fullscreen mode

3. Structured tool results. Return JSON from tools, not prose. Claude parses structured data more reliably than free text.

4. System prompt for persona. Move the role description out of the user message into a system parameter — it's more robust and doesn't count against your conversation history structure.

Key Takeaways

  • An agent is just a loop: model → tool calls → results → model, until stop_reason === 'end_turn'
  • Tool descriptions are part of your prompt — write them like documentation
  • You own the loop, which means you control retries, limits, and error handling
  • The Anthropic SDK exposes everything you need — no framework required for basic agents
  • Start with 2-3 well-defined tools and expand; generic "execute_code" tools cause unpredictable behavior

The full code for this agent is ~120 lines of TypeScript. The complexity in real agents comes from state management, error recovery, and tool design — not from the loop itself.

Follow me on Twitter @Alex_Rogov_js for more AI + Architecture content. If you found this useful, check out my other articles on AI-friendly TypeScript project structure and what I put in every CLAUDE.md.

Originally published on my Hashnode blog. Follow me for more AI + Architecture content.

Top comments (0)