A Go-based REST API service that provides HTTP endpoints to interact with Claude Code CLI. Built with Fiber framework for high performance.
Sign in to like and favorite skills
A Go-based REST API service that provides HTTP endpoints to interact with Claude Code CLI. Built with Fiber framework for high performance.
. ├── cmd/ │ └── api/ │ └── main.go # Application entry point ├── internal/ │ ├── config/ │ │ ├── config.go # Configuration management │ │ └── config_test.go # Config tests │ ├── handler/ │ │ ├── claude.go # HTTP handlers │ │ └── claude_test.go # Handler tests │ └── service/ │ ├── claude.go # Business logic for Claude CLI │ └── claude_test.go # Service tests ├── .env.example # Example environment configuration ├── Makefile # Build and run commands ├── go.mod # Go module definition ├── run-local.sh # Quick start script └── README.md
# Install Go brew install go # Verify Go installation go version
# Install Go (check https://go.dev/dl/ for latest version) wget https://go.dev/dl/go1.23.4.linux-amd64.tar.gz sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.23.4.linux-amd64.tar.gz export PATH=$PATH:/usr/local/go/bin # Verify Go installation go version
Download and run the installer from https://go.dev/dl/
Install Claude Code CLI following the official documentation at https://docs.anthropic.com/en/docs/claude-code.
After installation, authenticate:
claude auth
Verify the installation:
claude --version
# Clone the repository git clone <your-repo-url> cd claude-api-service # Run the quick start script ./run-local.sh
The script will:
.envhttp://localhost:8080# Clone and setup git clone <your-repo-url> cd claude-api-service # Setup project (creates .env, downloads dependencies) make setup # Run the application make run
# Clone the repository git clone <your-repo-url> cd claude-api-service # Copy environment configuration cp .env.example .env # Download dependencies go mod download # Set Claude path and run export CLAUDE_PATH=$(which claude) go run ./cmd/api/main.go
The API will start on
http://localhost:8080Configure the service using environment variables or a
.env| Variable | Description | Default |
|---|---|---|
| Server listen address (host:port) | |
| Path to Claude CLI executable | |
| CORS allowed origins (comma-separated or | |
.env# Server Configuration SERVER_ADDRESS=:8080 # Claude CLI Configuration CLAUDE_PATH=/usr/local/bin/claude # CORS Configuration ALLOWED_ORIGINS=http://localhost:3000,http://example.com
GET /health
Response:
{ "status": "healthy", "service": "claude-api-service" }
POST /api/v1/claude/prompt Content-Type: application/json { "prompt": "Write a hello world program in Python", "timeout": 300, "mode": "fast" }
Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| string | Yes | The prompt to send to Claude |
| int | No | Timeout in seconds (default: 300) |
| string | No | |
Response:
{ "response": "Here's a hello world program in Python:\n\nprint('Hello, World!')", "duration": "2.5s", "timestamp": "2025-12-18T10:30:00Z" }
POST /api/v1/claude/chat Content-Type: application/json { "message": "How do I sort a list in Python?", "history": [ "Previous message 1", "Previous message 2" ], "timeout": 300, "mode": "fast" }
Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| string | Yes | The current message to send |
| string[] | No | Previous messages for context |
| int | No | Timeout in seconds (default: 300) |
| string | No | |
Response:
{ "response": "You can sort a list in Python using the sorted() function...", "duration": "1.8s", "timestamp": "2025-12-18T10:31:00Z" }
GET /api/v1/claude/version
Response:
{ "version": "claude-code v1.0.0" }
# Health check curl http://localhost:8080/health # Send a prompt (fast mode - uses haiku) curl -X POST http://localhost:8080/api/v1/claude/prompt \ -H "Content-Type: application/json" \ -d '{ "prompt": "Explain what is dependency injection", "timeout": 300, "mode": "fast" }' # Send a prompt (deep mode - uses opus) curl -X POST http://localhost:8080/api/v1/claude/prompt \ -H "Content-Type: application/json" \ -d '{ "prompt": "Analyze the architectural patterns in microservices", "timeout": 300, "mode": "deep" }' # Chat with context curl -X POST http://localhost:8080/api/v1/claude/chat \ -H "Content-Type: application/json" \ -d '{ "message": "Can you give me an example?", "history": ["Explain what is dependency injection"], "timeout": 300 }' # Get version curl http://localhost:8080/api/v1/claude/version
# Send a prompt http POST localhost:8080/api/v1/claude/prompt \ prompt="Write a fibonacci function in Go" \ timeout:=300 \ mode="fast" # Chat http POST localhost:8080/api/v1/claude/chat \ message="What about recursion?" \ history:='["Write a fibonacci function in Go"]' \ timeout:=300
Install Air for hot reload during development:
go install github.com/cosmtrek/air@latest
Run with hot reload:
make dev
# Run all tests make test # Run tests with verbose output go test -v ./... # Run tests with coverage make test-coverage # Run tests with race detection go test -race ./...
Current test coverage:
internal/configinternal/handlerinternal/serviceInstall golangci-lint:
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
Run linter:
make lint
make fmt
make help # Show all available commands make setup # Setup project and install dependencies make run # Run the application make build # Build the binary make test # Run tests make test-coverage # Run tests with coverage make clean # Clean build artifacts make lint # Run linter make fmt # Format code make dev # Run with hot reload make build-and-run # Build and run make full-pipeline # Run complete CI pipeline (clean, format, lint, test, build) # API Testing (requires running server) make test-health # Test health endpoint make test-version # Test version endpoint make test-prompt PROMPT="your question" MODE=fast # Test prompt endpoint make test-chat MESSAGE="your message" MODE=deep # Test chat endpoint
The project follows clean architecture principles:
Ensure Claude CLI is installed and in your PATH:
which claude
If not found, install Claude Code from the official documentation.
Ensure the Claude CLI is executable:
chmod +x $(which claude)
If requests are timing out:
timeoutclaude --versionclaude authEnsure the server is running:
# Check if server is listening lsof -i :8080 # Or use netstat netstat -an | grep 8080
If you're getting CORS errors from a frontend application, update the
ALLOWED_ORIGINS.envALLOWED_ORIGINS=http://localhost:3000,http://your-frontend-domain.com
To run integration tests with the real Claude CLI:
CLAUDE_INTEGRATION_TEST=1 go test -v ./internal/service/...
Note: This requires Claude CLI to be installed and authenticated.
MIT
Contributions are welcome. Please:
git checkout -b feature/amazing-featuregit commit -m 'Add amazing feature'git push origin feature/amazing-feature