|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Development Commands |
| 6 | + |
| 7 | +```bash |
| 8 | +# Run in development mode with file watching |
| 9 | +deno task dev |
| 10 | + |
| 11 | +# Build executable for local use |
| 12 | +deno task buildLocal |
| 13 | + |
| 14 | +# Build for distribution |
| 15 | +deno task build |
| 16 | + |
| 17 | +# Run directly from source |
| 18 | +deno run -A src/main.ts --mode=editor "your prompt" |
| 19 | +deno run -A src/main.ts --mode=bash "your command" |
| 20 | +deno run -A src/main.ts "your request" # Default hybrid mode |
| 21 | +``` |
| 22 | + |
| 23 | +## Core Architecture |
| 24 | + |
| 25 | +ComputerUseAgent is a Deno-based AI CLI tool that uses Claude 3 API to execute user requests through a planning-based approach. The architecture centers around three key components: |
| 26 | + |
| 27 | +### Session Management |
| 28 | +- **HybridSession** (`src/modules/hybrid/hybrid_session.ts`): Primary execution engine that orchestrates the entire process |
| 29 | +- **PlannerModule** (`src/modules/planner/planner.ts`): Generates execution plans by breaking down user requests into actionable steps |
| 30 | +- **BaseSession** (`src/utils/session.ts`): Provides common session functionality including message history and token tracking |
| 31 | + |
| 32 | +### Tool System |
| 33 | +- **ToolHandler** (`src/utils/tool_handler.ts`): Central registry that manages all available tools and routes tool calls |
| 34 | +- **DynamicToolHandler** (`src/utils/dynamic_tool_handler.ts`): Handles user-configurable tools defined in tool config files |
| 35 | +- Built-in tools include bash execution, text editing, memory management, clipboard operations, and Jina API integration |
| 36 | + |
| 37 | +### Configuration Management |
| 38 | +- Tool configurations are loaded from JSON files and validated before use |
| 39 | +- User settings are managed through `src/config/settings.ts` |
| 40 | +- System constants and API configuration in `src/config/constants.ts` |
| 41 | + |
| 42 | +## Execution Flow |
| 43 | + |
| 44 | +1. User request enters through `main.ts` command parser |
| 45 | +2. HybridSession creates execution plan using PlannerModule |
| 46 | +3. Each plan step is executed sequentially through Claude API |
| 47 | +4. Tool calls are processed by ToolHandler and routed to appropriate handlers |
| 48 | +5. Results are logged to database and session history is maintained |
| 49 | + |
| 50 | +## Command Structure |
| 51 | + |
| 52 | +When adding new commands: |
| 53 | +1. Create handler in `src/commands/` following existing patterns |
| 54 | +2. Define command flags and help text |
| 55 | +3. Register in `main.ts` command routing section |
| 56 | +4. Follow the pattern: validate flags → handle help → execute logic |
| 57 | + |
| 58 | +## Tool Development |
| 59 | + |
| 60 | +Custom tools are defined in JSON configuration files with this structure: |
| 61 | +```typescript |
| 62 | +interface ToolConfig { |
| 63 | + toolName: string; |
| 64 | + command: string; |
| 65 | + output: string; |
| 66 | + inputs: ToolInputConfig[]; |
| 67 | + description: string; |
| 68 | + enabled: boolean; |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +## Key Files to Understand |
| 73 | + |
| 74 | +- `src/main.ts`: Entry point and command routing |
| 75 | +- `src/modules/hybrid/hybrid_session.ts`: Core execution logic |
| 76 | +- `src/utils/tool_handler.ts`: Tool registration and execution |
| 77 | +- `src/config/constants.ts`: System prompts and API configuration |
| 78 | +- `CONVENTIONS.md`: Detailed development patterns and anti-patterns |
| 79 | + |
| 80 | +## Important Notes |
| 81 | + |
| 82 | +- Legacy EditorSession and BashSession are deprecated; focus on HybridSession |
| 83 | +- All operations go through planning phase first |
| 84 | +- Tool errors are captured and logged, not thrown |
| 85 | +- Follow Anthropic tool calling conventions in `prompts/tool_calling_anthropic.md` |
| 86 | +- Token usage must be tracked for all API calls |
| 87 | +- Session boundaries must be maintained clearly |
0 commit comments