An exploration of AI agent system design and architecture, built from scratch in TypeScript. This project serves as a hands-on study of how modern coding assistants work under the hood—from agentic loops and tool orchestration to streaming interfaces and context management.

Tech Stack: TypeScript, Bun, React (Ink), Anthropic Claude API

Areas Explored:

• Agentic Architecture — ReAct (Reasoning + Acting) loop with multi-turn conversation, automatic summarization, and token management
• Tool Orchestration — Extensible registry pattern for file operations, code search, and sandboxed shell execution
• Terminal UI — Real-time streaming interface using React/Ink with concurrent state management
• Context Management — Session persistence, context windowing, and conversation export
• Observability — Debug logging infrastructure with UI panel, log levels, and performance timing

• Interactive Chat - Multi-turn conversations with context
• Streaming Responses - See text as it's generated in real-time
• Extended Thinking - Enable Claude's extended thinking for complex problems
• File Operations - Read, write, and edit files with diff display
• Code Search - Find files by pattern and search contents with regex
• Shell Integration - Execute bash commands with progress indicators
• Session Persistence - Save and resume conversations across sessions
• Token Tracking - Monitor token usage and estimated costs
• Rich UI - Color themes, syntax highlighting, tree views, and markdown rendering
• Auto-Summarization - Automatically condense long conversations

See FEATURES.md for the full feature roadmap. Planned features include:

• Task Tool - Spawn sub-agents for complex, multi-step tasks
• TodoWrite - Built-in task tracking and progress display
• Hooks System - Pre/post tool execution hooks
• Skills & Plugins - Extensibility via plugins with commands, agents, and MCP servers
• Multi-Provider - AWS Bedrock, Google Vertex AI, Azure OpenAI support

bun install

# Interactive mode
bun run start

# Development mode with watch
bun run dev

# With initial prompt
bun run src/index.tsx "explain this codebase"

Use these commands during an interactive session:

Set your API key:

export ANTHROPIC_API_KEY=your_key_here

Optional environment variables:

Enable debug mode to troubleshoot issues or understand agent behavior:

# Enable debug logging to stderr
bun run start --debug

# Also write logs to file
bun run start --debug --log-file

# Or via environment variable
DEBUG=1 bun run start

When debug mode is enabled:

• Press ` (backtick) to toggle the debug panel
• Use /debug command to toggle the panel
• Filter logs by level: d (debug), i (info), w (warn), e (error)
• Press c to clear the log buffer
• Logs are written to stderr and optionally to ~/.codepal/debug.log

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run tests
bun test

# Type check
bun run typecheck

1. Research - Check reference/ for implementation patterns
2. Design - Consider how it integrates with existing features
3. Implement - Follow existing code patterns in src/
4. Test - Add tests with bun test
5. Document - Update FEATURES.md and ARCHITECTURE.md if needed

The reference/ directory contains analysis of Claude Code v2.1.6:

• DEPENDENCIES.md - Full dependency list with versions
• TOOL_EXECUTION.md - Tool execution architecture
• data/plugins/ - Plugin system examples
• data.json - Configuration structure

PLAN.md is a project-specific instructions file that gets automatically loaded into the system prompt when working in this directory. It defines:

• Coding conventions and patterns
• Testing requirements and commands
• Project-specific rules
• Important files and architecture decisions
• Development phases and priorities

• Bun runtime
• Anthropic API key