{"repo": "cexll/mini-claude-code-go", "files": {"README.md": {"0c319eb57bfbe240c09c88970985878eb23bc5c3": {"t": 1785674075.377341, "n": 9351, "h": "dbc25f38558d9abe", "c": "# Mini Claude Code Agent (Go)\n\nA minimal AI coding agent in Go that provides file operations and shell execution through OpenAI-compatible chat APIs.\n\n## Features\n\n- 🤖 **Agentic Loop**: Automatically executes multiple tool calls to complete complex tasks\n- 📁 **File Operations**: Read, write, and edit files with safety constraints\n- 🔧 **Shell Execution**: Run bash commands with timeout and dangerous command blocking\n- 🔒 **Path Sandbox**: All file operations are restricted to the workspace directory\n- 🎯 **OpenAI Compatible**: Works with OpenAI API and compatible services (Moonshot, etc.)\n- 📊 **Debug Mode**: Optional detailed logging of API requests/responses\n- ⚡ **Single Binary**: No dependencies, easy deployment\n\n## Quick Start\n\n### Prerequisites\n\n- Go 1.21 or higher\n- OpenAI API key (or compatible service API key)\n\n### Build\n\n```bash\ncd mini-claude-code-go\ngo build agent.go\n```\n\nThis creates a single executable binary `agent` (~8MB).\n\n### Run\n\n```bash\n# Set your API key\nexport OPENAI_API_KEY=\"sk-...\"\n\n# Run the agent\n./agent\n```\n\n## Configuration\n\nThe agent is configured entirely through environment variables:\n\n### Required\n\n| Variable | Description |\n|----------|-------------|\n| `OPENAI_API_KEY` | Your OpenAI API key (or use `ANTHROPIC_API_KEY`) |\n\n### Optional\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `OPENAI_BASE_URL` | `https://api.openai.com` | API endpoint (or use `ANTHROPIC_BASE_URL`) |\n| `OPENAI_MODEL` | `gpt-4` | Model to use (or use `ANTHROPIC_MODEL`) |\n| `DEBUG` | `false` | Enable debug logging (`true` or `false`) |\n\n### Examples\n\n**Using OpenAI:**\n```bash\nexport OPENAI_API_KEY=\"sk-...\"\nexport OPENAI_MODEL=\"gpt-4-turbo\"\n./agent\n```\n\n**Using Moonshot (OpenAI-compatible):**\n```bash\nexport OPENAI_API_KEY=\"sk-...\"\nexport OPENAI_BASE_URL=\"https://api.moonshot.cn/v1\"\nexport OPENAI_MODEL=\"moonshot-v1-8k\"\n./agent\n```\n\n**Enable debug logging:**\n```bash\nDEBUG=true ./agent\n```\n\n## Usage\n\nOnce started, you'll see a REPL prompt:\n\n```\nTiny CC Agent (Go) -- cwd: /path/to/workspace\nType \"exit\" or \"quit\" to leave.\n\nUser:\n```\n\nType natural language commands and the agent will use tools to accomplish tasks.\n\n### Example Session\n\n```\nUser: create a hello.txt file with \"Hello World\" content\n[tool] write_file(map[content:Hello World path:hello.txt])\n  -> wrote 11 bytes to hello.txt\nDone! Created hello.txt with the requested content.\n\nUser: read the file\n[tool] read_file(map[path:hello.txt])\n  -> Hello World\nThe file contains: \"Hello World\"\n\nUser: append a new line \"Goodbye\"\n[tool] read_file(map[path:hello.txt])\n  -> Hello World\n[tool] write_file(map[content:Hello World\nGoodbye mode:append path:hello.txt])\n  -> wrote 19 bytes to hello.txt\nDone! Appended \"Goodbye\" to hello.txt\n\nUser: exit\n```\n\n### Exit Commands\n\nType any of these to exit:\n- `exit`\n- `quit`\n- `q`\n- Press `Ctrl+D` (EOF)\n\n## Available Tools\n\nThe agent has access to 4 tools:\n\n### 1. bash\n\nExecute shell commands in the workspace directory.\n\n**Features:**\n- Default 30s timeout (configurable up to 120s via `timeout_ms`)\n- Blocks dangerous commands: `rm -rf /`, `shutdown`, `reboot`, `sudo`, `halt`\n- Captures both stdout and stderr\n\n**Example:**\n```\nUser: run ls -la\n```\n\n### 2. read_file\n\nRead UTF-8 text files with optional line range and character limit.\n\n**Parameters:**\n- `path` (required): File path (relative to workspace)\n- `start_line` (optional): Starting line number (1-based)\n- `end_line` (optional): Ending line number (-1 for end of file)\n- `max_chars` (optional): Maximum characters to return\n\n**Example:**\n```\nUser: read the first 10 lines of README.md\n```\n\n### 3. write_file\n\nCreate or modify files with overwrite or append mode.\n\n**Parameters:**\n- `path` (required): File path (relative to workspace)\n- `content` (required): Content to write\n- `mode` (optional): `overwrite` (default) or `append`\n\n**Features:**\n- Automatically creates parent directories\n- Returns bytes written and relative path\n\n**Example:**\n```\nUser: create a config.json file with default settings\n```\n\n### 4. edit_text\n\nMake precise edits to existing files.\n\n**Actions:**\n- `replace`: Find and replace text\n  - Parameters: `find`, `replace`\n- `insert`: Insert text after a specific line\n  - Parameters: `insert_after` (line number, -1 for beginning), `new_text`\n- `delete_range`: Delete a range of lines\n  - Parameters: `range` [start, end) (exclusive end)\n\n**Example:**\n```\nUser: replace \"old_function\" with \"new_function\" in main.go\n```\n\n## Security\n\n### Path Sandbox\n\nAll file operations are restricted to the workspace directory:\n\n- Absolute paths are checked to ensure they're within the workspace\n- Relative paths are resolved against the workspace\n- Symbolic links are resolved and validated\n- Path traversal attempts (e.g., `../../../etc/passwd`) are blocked\n\n### Command Blocking\n\nThe following dangerous command patterns are blocked:\n- `rm -rf /`\n- `shutdown`\n- `reboot`\n- `sudo `\n- `halt`\n\n### Output Limits\n\nTool outputs are clamped to 100,000 characters to prevent memory issues.\n\n## Development\n\n### Project Structure\n\n```\nmini-claude-code-go/\n├── agent.go                 # Single-file implementation (~800 lines)\n├── go.mod                   # Go module definition\n├── go.sum                   # Dependency checksums\n└── README.md                # This file\n```\n\n### Code Organization\n\nThe code follows a clear structure:\n1. Imports and constants\n2. Type definitions (Config, Message, ToolCall, etc.)\n3. Spinner (UX component)\n4. Main function (REPL loop)\n5. Config loading\n6. Query function (agentic loop)\n7. API client (callOpenAI)\n8. Tool dispatcher\n9. Tool implementations (bash, read, write, edit)\n10. Safety layer (safePath, isDangerousCommand)\n11. Utility functions\n12. System prompt and tool definitions\n\n### Testing\n\nBuild and test:\n```bash\n# Build\ngo build agent.go\n\n# Run tests (if any)\ngo test ./...\n\n# Vet code\ngo vet agent.go\n\n# Format code\ngo fmt agent.go\n```\n\n### Debug Mode\n\nEnable detailed API logging:\n\n```bash\nDEBUG=true ./agent\n```\n\nThis will log to stderr:\n- Request URL\n- Request payload (pretty-printed JSON)\n- Response status\n- Response body (pretty-printed JSON)\n\nNormal output to stdout is unaffected.\n\n## Architecture\n\n### Agentic Loop\n\nThe agent operates in a loop (max 20 iterations):\n\n```\n1. Send messages + tool definitions to API\n2. Receive response\n   - If text content: print it\n   - If tool calls: execute all tools\n3. Append results to conversation history\n4. If finish_reason == \"tool_calls\": goto 1\n5. Otherwise: done\n```\n\n### API Format\n\nUses OpenAI Chat Completions format:\n- Endpoint: `/v1/chat/completions`\n- Authentication: `Authorization: Bearer {key}`\n- System prompt as first message with `role: \"system\"`\n- Tool results as messages with `role: \"tool\"`\n\n### Message Flow\n\n```\nUser Input\n  ↓\n[{role: \"system\", content: \"You are a coding agent...\"},\n {role: \"user\", content: \"create a file\"}]\n  ↓\nAPI Call\n  ↓\n{role: \"assistant\", tool_calls: [{function: {name: \"write_file\", ...}}]}\n  ↓\nExecute Tools\n  ↓\n{role: \"tool\", tool_call_id: \"...\", content: \"wrote 10 bytes\"}\n  ↓\nAPI Call (continues until finish_reason != \"tool_calls\")\n```\n\n## Comparison with Python Version\n\nThis Go implementation is functionally equivalent to the [Python version](https://github.com/shareAI-lab/mini_claude_code/blob/main/v1_basic_agent.py):\n\n| Feature | Python | Go |\n|---------|--------|-----|\n| Single file | ✅ | ✅ |\n| File operations | ✅ | ✅ |\n| Shell execution | ✅ | ✅ |\n| Path sandbox | ✅ | ✅ |\n| Dangerous command blocking | ✅ | ✅ |\n| Agentic loop | ✅ | ✅ |\n| Spinner | ✅ | ✅ |\n| **API format** | Anthropic | **OpenAI** |\n| **Binary size** | N/A (requires Python) | **8MB** |\n| **Startup time** | ~1-2s | **<100ms** |\n| **Memory usage** | ~50-80MB | **~20-30MB** |\n| **Deployment** | Requires Python env | **Single binary** |\n\n### Key Differences\n\n1. **API Format**: Go version uses OpenAI format (`/v1/chat/completions`) instead of Anthropic format (`/v1/messages`)\n2. **Performance**: Go version has faster startup and lower memory usage\n3. **Deployment**: Go version compiles to a single binary with no runtime dependencies\n4. **Compatibility**: Go version works with any OpenAI-compatible API\n\n## Troubleshooting\n\n### \"OPENAI_API_KEY or ANTHROPIC_API_KEY required\"\n\nSet one of these environment variables:\n```bash\nexport OPENAI_API_KEY=\"sk-...\"\n```\n\n### \"api error: status 404\"\n\nCheck your `OPENAI_BASE_URL`. Common values:\n- OpenAI: `https://api.openai.com` (default)\n- Moonshot: `https://api.moonshot.cn/v1`\n\nThe URL should NOT include `/chat/completions` (it's added automatically).\n\n### \"path escapes workspace\"\n\nAll file operations must be within the current working directory. Absolute paths or `..` that escape the workspace are blocked for security.\n\n### \"blocked dangerous command\"\n\nCommands containing dangerous patterns are blocked. Use safer alternatives or break down the task.\n\n## License\n\nMIT License - see the original Python version for details.\n\n## Credits\n\n- Original Python version: [shareAI-lab/mini_claude_code](https://github.com/shareAI-lab/mini_claude_code)\n- Go port: Adapted to use OpenAI-compatible APIs\n\n## Contributing\n\nThis is a minimal reference implementation. For enhancements:\n1. Fork the repository\n2. Make your changes\n3. Test thoroughly\n4. Submit a pull request\n\nKeep it simple - the goal is to stay under 1000 lines in a single file.\n"}}}}