Don - AI Coding Agent

Overview

Don is an intelligent coding agent powered by Claude (Anthropic) that enables developers to interact with their codebase through natural language. Don can read, write, edit, and manage files seamlessly, making it an invaluable assistant for code generation, refactoring, and project management tasks.

The src directory contains the core implementation of Don's conversational intelligence and file system integration capabilities.

Files

1. index.ts - Main Agent Entry Point

The core agent implementation that manages the conversation loop and tool execution.

Key Features:

• Interactive CLI interface for chatting with the AI agent (named "Don")
• Conversation management and message history tracking
• Integration with Anthropic Claude API (using claude-haiku-4-5 model)
• Tool execution workflow: detects tool calls from Claude and executes them
• Graceful exit handling

Main Classes:

• Agent: Handles the conversation loop, user input, and API interactions

Key Methods:

• run(): Main conversation loop that reads user input and manages responses
• getMessage(): Reads user input from stdin
• runInference(): Sends conversation messages to Claude API with available tools

---

2. definitions.ts - Tool Definitions and Execution

Defines all available tools that Claude can use, with validation and execution logic.

Key Features:

• Zod schema-based tool definition and validation
• Converts Zod schemas to JSON schema for Claude API compatibility
• Tool registry for dynamic lookup and execution
• Error handling for tool execution

Exported Items:

• toolsDefinitions: Array of tool definitions for Claude API
• executeTool(): Function to execute tools by name with input validation

Available Tools:

1. read_file

   • Description: Read the contents of a file
   • Input: path (string) - relative file path
   • Output: File contents as string

2. list_files

   • Description: List files and directories at a given path
   • Input: path (string, optional) - directory path (defaults to current directory)
   • Output: Newline-separated list of file paths

3. edit_file

   • Description: Edit or create files by replacing text
   • Input:
     • path (string) - file path
     • old_str (string, optional) - text to find and replace
     • new_str (string) - replacement text
   • Output: Success/error message

Tool Type Definition:

type Tool<T extends z.ZodObject<any>> = {
    definition: Anthropic.Tool;
    schema: T;
    handler: (input: z.infer<T>) => Promise<string>;
};

---

3. tools.ts - File System Operations

Low-level file system utilities and command execution.

Key Features:

• Promise-based file operations
• Directory traversal (excluding node_modules)
• Command execution via shell
• Smart file creation with directory creation
• Text replacement with validation

Tools Class Methods:

• readFile(path): Read file contents
• writeNewFile(filePath, content): Write/create a file
• editFile(path, old_str, new_str): Edit existing files or create new ones
• listFiles(raw): List all files and directories recursively
• runCommand(command): Execute shell commands

Helper Functions:

• walkDir(dir): Recursively traverse directory structure, returning both files and directories

---

Architecture

┌─────────────────────────────────────────┐
│         index.ts (Agent Class)          │
│  - User input handling                  │
│  - Conversation management              │
│  - Claude API integration               │
└────────────────┬────────────────────────┘
                 │
                 ↓
┌─────────────────────────────────────────┐
│    definitions.ts (Tool Execution Layer)     │
│  - Tool validation (Zod schemas)        │
│  - Tool registry & execution            │
│  - Schema conversion (Zod → JSON)       │
└────────────────┬────────────────────────┘
                 │
                 ↓
┌─────────────────────────────────────────┐
│  tools.ts (File System)     │
│  - Low-level file operations            │
│  - Directory traversal                  │
│  - Command execution                    │
└─────────────────────────────────────────┘

Usage

Running the Agent

npm run dev

This starts an interactive chat session. You can:

• Ask questions and have conversations
• Request file operations (read, write, edit, list)
• Type "exit" to quit the program

Example Interactions

You: List all files in the src directory
Don ✨: <executes list_files tool>
Don: Here are the files in the src directory...

You: Read the content of index.ts
Don ✨: <executes read_file tool>
Don: The index.ts file contains the following...

You: Create a new function that validates email addresses
Don ✨: <executes edit_file tool>
Don: I've created a new validation utility with email verification...

You: Refactor this code for better performance
Don ✨: <reads file, analyzes, and applies optimizations>
Don: I've refactored your code to improve performance by...

Dependencies

• @anthropic-ai/sdk: Claude API client
• chalk: Terminal color output
• dotenv: Environment variable loading
• zod: Schema validation
• zod-to-json-schema: Convert Zod schemas to JSON schemas
• Node.js built-in modules: readline, fs/promises, child_process, path

Environment Variables

Required for API access:

• ANTHROPIC_API_KEY: Your Anthropic API key

Technical Details

Tool Validation Flow

1. User input → Claude processes with tool definitions
2. Claude returns tool use request
3. executeTool() looks up tool in registry
4. Zod schema validates input data
5. Tool handler executes file system operation
6. Result returned to Claude for next inference

Error Handling

• Invalid tool names: Returns error result
• Validation failures: Zod catches schema mismatches
• File operation errors: Caught and returned as error responses
• User input EOF: Gracefully closes program

Notes

• Uses claude-haiku-4-5 model for fast, efficient responses
• Maximum tokens set to 8024
• Conversation history is maintained throughout the session
• File operations are synchronous within async handlers
• Excludes node_modules from directory listings

Use Cases

Don is perfect for:

• Code Generation: Generate boilerplate, utilities, and scaffolding
• Code Review: Ask Don to review and suggest improvements
• Refactoring: Improve code structure and performance through natural language requests
• Documentation: Generate or update project documentation
• Bug Fixes: Describe issues and let Don help locate and fix them
• Project Navigation: Quickly understand your codebase structure

Features

✨ Natural Language Interaction - Communicate with your codebase using plain English 📁 File Management - Read, create, edit, and browse files seamlessly 🤖 AI-Powered - Leverages Claude's advanced coding knowledge ⚡ Fast & Efficient - Quick responses optimized for productivity 💾 Context Aware - Maintains conversation history for coherent interactions