|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file provides guidance to AI agents working with code in this repository. |
| 4 | + |
| 5 | +## Build Commands |
| 6 | + |
| 7 | +- `make build` - Build the binary to `out/agentapi` (includes chat UI build) |
| 8 | +- `make embed` - Build the chat UI and embed it into Go |
| 9 | +- `go build -o out/agentapi main.go` - Direct Go build without chat UI |
| 10 | +- `go generate ./...` - Generate OpenAPI schema and version info |
| 11 | + |
| 12 | +## Testing |
| 13 | + |
| 14 | +- `go test ./...` - Run all Go tests |
| 15 | +- Tests are located alongside source files (e.g., `lib/httpapi/server_test.go`) |
| 16 | + |
| 17 | +## Development Commands |
| 18 | + |
| 19 | +- `agentapi server -- claude` - Start server with Claude Code agent |
| 20 | +- `agentapi server -- aider --model sonnet` - Start server with Aider agent |
| 21 | +- `agentapi server -- goose` - Start server with Goose agent |
| 22 | +- `agentapi server --type=codex -- codex` - Start server with Codex (requires explicit type) |
| 23 | +- `agentapi server --type=gemini -- gemini` - Start server with Gemini (requires explicit type) |
| 24 | +- `agentapi attach --url localhost:3284` - Attach to running agent terminal |
| 25 | +- Server runs on port 3284 by default |
| 26 | +- Chat UI available at http://localhost:3284/chat |
| 27 | +- API documentation at http://localhost:3284/docs |
| 28 | + |
| 29 | +## Architecture |
| 30 | + |
| 31 | +This is a Go HTTP API server that controls coding agents (Claude Code, Aider, Goose, etc.) through terminal emulation. |
| 32 | + |
| 33 | +**Core Components:** |
| 34 | +- `main.go` - Entry point using cobra CLI framework |
| 35 | +- `cmd/` - CLI command definitions (server, attach) |
| 36 | +- `lib/httpapi/` - HTTP server, routes, and OpenAPI schema |
| 37 | +- `lib/screentracker/` - Terminal output parsing and message splitting |
| 38 | +- `lib/termexec/` - Terminal process execution and management |
| 39 | +- `lib/msgfmt/` - Message formatting for different agent types (claude, goose, aider, codex, gemini, amp, cursor-agent, cursor, auggie, custom) |
| 40 | +- `chat/` - Next.js web UI (embedded into Go binary) |
| 41 | + |
| 42 | +**Key Architecture:** |
| 43 | +- Runs agents in an in-memory terminal emulator |
| 44 | +- Translates API calls to terminal keystrokes |
| 45 | +- Parses terminal output into structured messages |
| 46 | +- Supports multiple agent types with different message formats |
| 47 | +- Embeds Next.js chat UI as static assets in Go binary |
| 48 | + |
| 49 | +**Message Flow:** |
| 50 | +1. User sends message via HTTP API |
| 51 | +2. Server takes terminal snapshot |
| 52 | +3. Message sent to agent as terminal input |
| 53 | +4. Terminal output changes tracked and parsed |
| 54 | +5. New content becomes agent response message |
| 55 | +6. SSE events stream updates to clients |
| 56 | + |
| 57 | +## API Endpoints |
| 58 | + |
| 59 | +- GET `/messages` - Get all messages in conversation |
| 60 | +- POST `/message` - Send message to agent (content, type fields) |
| 61 | +- GET `/status` - Get agent status ("stable" or "running") |
| 62 | +- GET `/events` - SSE stream of agent events |
| 63 | +- GET `/openapi.json` - OpenAPI schema |
| 64 | +- GET `/docs` - API documentation UI |
| 65 | +- GET `/chat` - Web chat interface |
| 66 | + |
| 67 | +## Supported Agents |
| 68 | + |
| 69 | +Agents with explicit type requirement (use `--type=<agent>`): |
| 70 | +- `codex` - OpenAI Codex |
| 71 | +- `gemini` - Google Gemini CLI |
| 72 | +- `amp` - Sourcegraph Amp CLI |
| 73 | +- `cursor` - Cursor CLI |
| 74 | + |
| 75 | +Agents with auto-detection: |
| 76 | +- `claude` - Claude Code (default) |
| 77 | +- `goose` - Goose |
| 78 | +- `aider` - Aider |
| 79 | + |
| 80 | +## Project Structure |
| 81 | + |
| 82 | +- Go module with standard layout |
| 83 | +- Chat UI in `chat/` directory (Next.js + TypeScript) |
| 84 | +- OpenAPI schema auto-generated to `openapi.json` |
| 85 | +- Version managed via `version.sh` script |
0 commit comments