dev

CodeMate

English | 简体中文

Docker-based Claude Code environment with automated Git/PR setup.

⚠️ Security Notice: This container runs with --dangerously-skip-permissions by default, allowing Claude to execute commands without confirmation. Use only in isolated environments with trusted repositories.

Why CodeMate?

Tired of approving every single command when pair programming with AI? Yet hesitant to grant full bypass permissions on your local machine? Every GitHub interaction requiring manual confirmation breaks your flow.

CodeMate solves this by running Claude Code in an isolated Docker container where it can operate freely without compromising your system. True pair programming starts here—let Claude focus on coding while you focus on the bigger picture.

Features

• Automated repository cloning and PR management
• Pre-installed: Go, Node.js, Python, Rust, uv
• zsh with Oh My Zsh
• Persistent Claude configuration
• Built-in Claude Code skills for PR workflow automation
• Slack and Lark notifications when Claude stops (via SLACK_WEBHOOK / LARK_WEBHOOK)
• tmux session management with PR comment monitoring

Quick Start

Prerequisites

• Docker
• GitHub CLI (gh) authenticated
• Anthropic API key

Run codemate --setup to create the required configuration files (global config in ~/.codemate/ and project .env).

Note: git is also required as a prerequisite — the script checks for it at startup.

Mac Users

On macOS, you need a Docker runtime since Docker doesn't run natively. Choose one:

• Docker Desktop - Official Docker GUI application
• Colima - Lightweight Docker runtime (recommended for CLI users)

Installation

Global Installation (Recommended)

Install codemate globally to use it from anywhere:

# Install directly to /usr/local/bin (requires sudo)
sudo curl -fsSL https://raw.githubusercontent.com/BoringHappy/CodeMate/main/codemate -o /usr/local/bin/codemate && sudo chmod +x /usr/local/bin/codemate

# Or install to ~/.local/bin without sudo (ensure ~/.local/bin is in your PATH)
curl -fsSL https://raw.githubusercontent.com/BoringHappy/CodeMate/main/codemate -o ~/.local/bin/codemate && chmod +x ~/.local/bin/codemate

# One-time global setup
codemate --setup

# Update to latest version
codemate --update

Usage

Basic Commands

# First time setup - creates global config and project .env
codemate --setup

# Run with explicit repo URL
codemate --repo https://github.com/your-org/your-repo.git --branch feature/xyz

# Run with branch name (auto-detects repo from: --repo > .env > current directory's git remote)
codemate --branch feature/your-branch

# Run with a custom PR title
codemate --branch feature/your-branch --pr-title "My feature title"

# Run with existing PR
codemate --pr 123

# Run with GitHub issue (creates branch issue-NUMBER)
codemate --issue 456

# Fork-based workflow (for open-source contributions)
codemate --repo https://github.com/yourname/project.git --upstream https://github.com/maintainer/project.git --branch fix-bug
codemate --repo https://github.com/yourname/project.git --upstream https://github.com/maintainer/project.git --issue 789

# Skip PR creation on new branches (useful for forks or draft work)
codemate --branch feature/xyz --no-pr

# Run with custom volume mounts (optional)
codemate --branch feature/xyz --mount ~/data:/data

# Run with initial query to Claude
codemate --branch feature/xyz --query "Please review the code and fix any issues"

# Build and run from local Dockerfile
codemate --build --branch feature/xyz

# Build with custom Dockerfile path and tag
codemate --build -f ./custom/Dockerfile --tag my-codemate:v1 --branch feature/xyz

# For Chinese users: Use DaoCloud mirror for faster image pulls
codemate --branch feature/xyz --image ghcr.m.daocloud.io/boringhappy/codemate:latest

The setup command will:

1. Create global configuration in ~/.codemate/ (Claude config and settings)
2. Create project-specific .env file in your current directory
3. Prompt you for Anthropic API token and other settings

Configuration Structure:

• Global config: ~/.codemate/ - Claude configuration and settings (shared across all projects)
• Project config: .env in each project directory - Project-specific secrets and settings

Repository URL Resolution: The script determines the repository URL in this priority order:

1. --repo command-line argument (highest priority)
2. GIT_REPO_URL environment variable or .env file
3. Current directory's git remote origin URL (auto-detected)
4. If none are available, an error is raised

Custom Volume Mounts

Use --mount <host-path>:<container-path> to mount additional directories or files. Useful for sharing data, configurations, or credentials with the container. Multiple --mount options can be specified.