CodeAgent is a Go-based AI-powered automated code generation and collaboration system that seamlessly integrates with GitHub. It receives AI instructions through GitHub webhooks and automatically handles code generation, modification, and review tasks for Issues and Pull Requests.
- 🤖 Multiple AI Providers: Support for Anthropic Claude and Google Gemini
- 🔄 GitHub Integration: Automatic processing of Issues and Pull Requests
- 🐳 Flexible Deployment: Docker containers or local CLI execution
- 📁 Smart Workspace Management: Git worktree-based isolated environments
- 🔐 Security First: Webhook signature verification and secure token handling
- ⚡ Real-time Processing: Instant response to GitHub events
- Architecture Overview
- Getting Started
- Configuration
- Usage
- Development
- Troubleshooting
- Contributing
- License
CodeAgent uses a webhook-driven architecture for seamless GitHub integration:
GitHub Events → Webhook → CodeAgent → Workspace Creation → AI Processing → Code Generation → PR Updates
- Agent (
internal/agent/): Orchestrates the entire workflow - Webhook Handler (
internal/webhook/): Processes GitHub webhooks (Issues and PRs) - Workspace Manager (
internal/workspace/): Manages temporary Git worktrees - AI Providers (
internal/code/): Claude and Gemini integration (Docker/CLI modes) - GitHub Client (
internal/github/): Handles GitHub API interactions
Required:
- Go 1.21 or higher
- Git
- GitHub Personal Access Token
- AI Provider API Key (Claude or Gemini)
# Clone the repository
git clone https://github.com/qiniu/codeagent.git
cd codeagent
# Download dependencies
go mod download# Set environment variables
export GITHUB_TOKEN="your-github-token"
export CLAUDE_API_KEY="your-claude-api-key"
export WEBHOOK_SECRET="your-webhook-secret"
# Run the server
go run ./cmd/server --port 8888Health Check
curl http://localhost:8888/health| Variable | Description | Required | Example |
|---|---|---|---|
GITHUB_TOKEN |
GitHub Personal Access Token | Yes | ghp_xxxxxxxxxxxx |
WEBHOOK_SECRET |
GitHub Webhook Secret | Yes | your-strong-secret |
CODE_PROVIDER |
AI provider (claude/gemini) | No | claude |
USE_DOCKER |
Use Docker containers | No | true |
PORT |
Server port | No | 8888 |
LOG_LEVEL |
Logging level | No | debug |
Create config.yaml in the project root:
# Server configuration
server:
port: 8888
# GitHub integration
github:
webhook_url: "http://localhost:8888/hook"
# Workspace settings
workspace:
base_dir: "./workspace" # Supports relative paths
cleanup_after: "24h"
# AI provider selection
code_provider: claude # Options: claude, gemini
use_docker: false # true = Docker, false = CLI
# Claude configuration
claude:
container_image: "goplusorg/codeagent:v0.4"
timeout: "30m"
# Gemini configuration
gemini:
container_image: "goplusorg/codeagent:v0.4"
timeout: "30m"
1. Configure GitHub Webhook
Go to your repository settings → Webhooks → Add webhook:
- URL:
https://your-domain.com/hook - Content type:
application/json - Secret: Same as your
WEBHOOK_SECRET - Events: Select
Issue comments,Pull request reviews,Pull requests
2. Webhook Security
CodeAgent supports GitHub webhook signature verification:
- SHA-256 verification (recommended)
- SHA-1 backward compatibility
- Constant-time comparison to prevent timing attacks
- Development mode: verification skipped if secret not configured
Use these commands in GitHub Issue comments or PR discussions:
| Command | Description | Example |
|---|---|---|
/code [description] |
Generate code for an Issue | /code Implement user authentication with JWT or /code |
/continue <instruction> |
Continue development in PR | /continue Add unit tests for the login function |
1. Create New Feature
# In a GitHub Issue comment:
/code Implement user login functionality including username/password validation and JWT token generation
2. Enhance Existing Code
# In a PR comment:
/continue Add comprehensive error handling and input validation
codeagent/
├── cmd/
│ └── server/ # Application entry point
├── internal/
│ ├── agent/ # Core orchestration logic
│ ├── code/ # AI provider implementations
│ ├── config/ # Configuration management
│ ├── context/ # Context collection and formatting
│ ├── events/ # Event parsing
│ ├── github/ # GitHub API client
│ ├── interaction/ # User interaction handling
│ ├── mcp/ # MCP (Model Context Protocol) support
│ ├── modes/ # Processing mode handlers
│ ├── webhook/ # GitHub webhook handling
│ └── workspace/ # Git workspace management
├── pkg/
│ ├── models/ # Shared data structures
│ └── signature/ # Webhook signature verification
├── test/
│ └── integration/ # Integration tests
├── docs/ # Documentation
├── config.example.yaml # Example configuration
└── README.md # This file
# Build for current platform
make build
# Or manually
go build -o bin/codeagent ./cmd/server
# Cross-compilation
GOOS=linux GOARCH=amd64 go build -o bin/codeagent-linux ./cmd/server# Run all tests
make test
# Integration testing
go run ./cmd/server --config test-config.yaml
# Test webhook endpoint
curl -X POST http://localhost:8888/hook \
-H "Content-Type: application/json" \
-H "X-GitHub-Event: issue_comment" \
-d @test-data/issue-comment.jsonCommon Issues
| Issue | Symptom | Solution |
|---|---|---|
| Webhook not received | No response to GitHub commands | Check webhook URL and secret configuration |
| AI provider timeout | Long delays or timeouts | Increase timeout in config, check API key |
| Docker issues | Container startup failures | Ensure Docker daemon is running |
| CLI not found | Command not found errors | Install Claude/Gemini CLI tools |
| Permission denied | Git operations fail | Check GitHub token permissions |
| Workspace cleanup | Disk space issues | Monitor workspace directory, adjust cleanup_after |
Debug Commands
# Check server status
curl http://localhost:8888/health
# View server logs
export LOG_LEVEL=debug
./scripts/start.sh
# Test webhook manually
curl -X POST http://localhost:8888/hook \
-H "Content-Type: application/json" \
-H "X-GitHub-Event: ping" \
-d '{"zen":"GitHub zen message"}'We welcome contributions! Here's how you can help:
Ways to Contribute
Please read our Contributing Guide for detailed information about the development process.
This project is licensed under the MIT License.
Thank you to all developers and users who have contributed to making CodeAgent better!
Need help? Check our documentation or open an issue.
