Claude API Service

A Go-based REST API service that provides HTTP endpoints to interact with Claude Code CLI. Built with Fiber framework for high performance.

Features

• RESTful API for Claude CLI integration
• Built with Go Fiber for high performance
• Graceful shutdown handling
• CORS support
• Request timeout management
• Health check endpoint
• Structured logging
• Error handling middleware
• Model selection (haiku for fast responses, opus for deep analysis)

Project Structure

.
├── 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

Prerequisites

• Go 1.23 or higher - Download Go
• Claude Code CLI - Must be installed and authenticated

Installing Prerequisites

macOS

# Install Go
brew install go

# Verify Go installation
go version

Linux (Ubuntu/Debian)

# 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

Windows

Download and run the installer from https://go.dev/dl/

Installing Claude Code CLI

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

Quick Start

Option 1: Using the Quick Start Script (Recommended)

# Clone the repository
git clone <your-repo-url>
cd claude-api-service

# Run the quick start script
./run-local.sh

The script will:

1. Check if Go is installed
2. Check if Claude CLI is installed
3. Create .env file if it doesn't exist
4. Start the server on http://localhost:8080

Option 2: Using Make

# 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

Option 3: Manual Setup

# 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:8080.

Configuration

Configure the service using environment variables or a .env file:

Variable	Description	Default
SERVER_ADDRESS	Server listen address (host:port)	:8080
CLAUDE_PATH	Path to Claude CLI executable	claude
ALLOWED_ORIGINS	CORS allowed origins (comma-separated or * for all)	*

Example .env file

# Server Configuration
SERVER_ADDRESS=:8080

# Claude CLI Configuration
CLAUDE_PATH=/usr/local/bin/claude

# CORS Configuration
ALLOWED_ORIGINS=http://localhost:3000,http://example.com

API Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy",
  "service": "claude-api-service"
}

Send Prompt to Claude

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
prompt	string	Yes	The prompt to send to Claude
timeout	int	No	Timeout in seconds (default: 300)
mode	string	No	"fast" (haiku) or "deep" (opus), default: haiku

Response:

{
  "response": "Here's a hello world program in Python:\n\nprint('Hello, World!')",
  "duration": "2.5s",
  "timestamp": "2025-12-18T10:30:00Z"
}

Chat with Claude

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
message	string	Yes	The current message to send
history	string[]	No	Previous messages for context
timeout	int	No	Timeout in seconds (default: 300)
mode	string	No	"fast" (haiku) or "deep" (opus), default: haiku

Response:

{
  "response": "You can sort a list in Python using the sorted() function...",
  "duration": "1.8s",
  "timestamp": "2025-12-18T10:31:00Z"
}

Get Claude Version

GET /api/v1/claude/version

Response:

{
  "version": "claude-code v1.0.0"
}

Example Usage

Using cURL

# 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

Using HTTPie

# 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

Development

Run with Hot Reload

Install Air for hot reload during development:

go install github.com/cosmtrek/air@latest

Run with hot reload:

make dev

Run Tests

# 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 ./...

Test Coverage

Current test coverage:

• internal/config: 100%
• internal/handler: 100%
• internal/service: ~94%

Linting

Install golangci-lint:

go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Run linter:

make lint

Format Code

make fmt

Make Commands

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

Architecture

Clean Architecture

The project follows clean architecture principles:

• cmd/api: Application entry point and server setup
• internal/config: Configuration management from environment variables
• internal/handler: HTTP request handlers (controllers)
• internal/service: Business logic and Claude CLI interaction

Key Design Patterns

• Dependency Injection: Services are injected into handlers
• Context Propagation: Proper context usage for timeouts and cancellation
• Middleware Chain: Recovery, logging, and CORS middleware
• Graceful Shutdown: Handles OS signals for clean shutdown

Troubleshooting

Claude CLI not found

Ensure Claude CLI is installed and in your PATH:

which claude

If not found, install Claude Code from the official documentation.

Permission denied errors

Ensure the Claude CLI is executable:

chmod +x $(which claude)

Timeout errors

If requests are timing out:

1. Increase the timeout value in your requests
2. Check Claude CLI is responding correctly: claude --version
3. Verify you're authenticated: claude auth

Connection refused

Ensure the server is running:

# Check if server is listening
lsof -i :8080

# Or use netstat
netstat -an | grep 8080

CORS errors

If you're getting CORS errors from a frontend application, update the ALLOWED_ORIGINS in your .env file:

ALLOWED_ORIGINS=http://localhost:3000,http://your-frontend-domain.com

Integration Testing

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.

License

MIT

Contributing

Contributions are welcome. Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request