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.

Building from Local Dockerfile

For development or customization, you can build CodeMate from a local Dockerfile:

# Build from default Dockerfile in current directory
codemate --build --branch feature/xyz

# Build from custom Dockerfile path
codemate --build -f ./path/to/Dockerfile --branch feature/xyz

# Build with custom image tag
codemate --build --tag my-codemate:dev --branch feature/xyz

# Combine all options
codemate --build -f ./custom/Dockerfile --tag my-codemate:v1 --branch feature/xyz

Options:

• --build - Build Docker image from local Dockerfile before running
• -f, --dockerfile PATH - Path to Dockerfile (default: docker/Dockerfile)
• --tag TAG - Image tag for local build (default: codemate:local)
  • Note: Only works with --build. To use a pre-built image, use --image instead

When --build is used:

1. The script builds the Docker image from the specified Dockerfile
2. The default image tag is codemate:local (unless --tag is specified)
3. The locally built image is used instead of pulling from the registry
4. The --image option is ignored when --build is used

Adding Custom Toolchains:

To add additional toolchains or tools to the container, create a custom Dockerfile that extends the base image:

# Custom Dockerfile with additional toolchains
FROM ghcr.io/boringhappy/codemate:latest

# Add Java
RUN apt-get update && apt-get install -y openjdk-17-jdk maven

# Add PHP
RUN apt-get install -y php php-cli php-mbstring composer

# Add Ruby
RUN apt-get install -y ruby-full
RUN gem install bundler

# Add any other tools you need
RUN apt-get install -y postgresql-client redis-tools

# Clean up
RUN apt-get clean && rm -rf /var/lib/apt/lists/*

Then build and run with your custom Dockerfile:

codemate --build -f ./Dockerfile.custom --tag codemate:custom --branch feature/xyz

Environment Variables

Note: When using codemate, these variables are handled automatically through the setup process. This reference is primarily for advanced Docker usage or troubleshooting.

Variable	Required	Description
GIT_REPO_URL	No	Repository URL (defaults to current repo's remote)
UPSTREAM_REPO_URL	No	Upstream repository URL (for fork-based workflows)
BRANCH_NAME	No	Branch to work on
PR_NUMBER	No	Existing PR number to work on
PR_TITLE	No	PR title for newly created PRs
ISSUE_NUMBER	No	GitHub issue number (creates branch issue-NUMBER and uses /issue:read-issue skill)
NO_PR	No	Set to true to skip PR creation and branch push for new branches
CODEMATE_GITHUB_TOKEN	Auto	GitHub personal access token (defaults to gh auth token if not provided)
GIT_USER_NAME	Auto	Git commit author name (defaults to git config user.name if not provided)
GIT_USER_EMAIL	Auto	Git commit author email (defaults to git config user.email if not provided)
CODEMATE_IMAGE	No	Custom image (default: ghcr.io/boringhappy/codemate:latest)
SLACK_WEBHOOK	No	Slack Incoming Webhook URL for notifications when Claude stops (only sent if new commits exist)
LARK_WEBHOOK	No	Lark Incoming Webhook URL for notifications when Claude stops (only sent if new commits exist)
ANTHROPIC_AUTH_TOKEN	No	Anthropic API token (for custom API endpoints)
ANTHROPIC_BASE_URL	No	Anthropic API base URL (for custom API endpoints)
QUERY	No	Initial query to send to Claude after startup
DEFAULT_MARKETPLACES	No	Comma-separated default plugin marketplaces (default: vercel-labs/agent-browser,BoringHappy/CodeMate)
DEFAULT_PLUGINS	No	Comma-separated default plugins (default: agent-browser@agent-browser,git@codemate,pr@codemate,dev@codemate,issue@codemate,workspace@codemate,pm@codemate)
CUSTOM_MARKETPLACES	No	Comma-separated list of custom plugin marketplace repositories (e.g., username/repo1,org/repo2)
CUSTOM_PLUGINS	No	Comma-separated list of custom plugins to install (e.g., plugin1@marketplace1,plugin2@marketplace2)

How It Works

CodeMate uses a separate base image (codemate-base) that is rebuilt weekly to keep system packages and development tools up-to-date.

On startup, the container:

1. Configures git user from environment variables
2. Authenticates GitHub CLI with token
3. Installs/updates plugins from configured marketplaces
4. Clones/updates repository to /home/agent/<repo-name>
5. Checks out specified branch or PR
6. Creates a draft PR if working on a new branch (unless --no-pr or fork workflow)
7. Starts Claude Code in a tmux session with --dangerously-skip-permissions flag
8. Sends initial query to Claude if --query is provided
9. Runs a cron job every minute to monitor the PR for new comments, CI failures, and review-ready state

Skills

CodeMate comes with pre-installed skills from the agent-browser. These skills are automatically available when you start the container and provide workflow automation for Git, PR management, and browser interactions.

Available Plugins

Git Plugin (git@codemate):

Command	Description
/git:commit	Stage all changes, create a commit with a meaningful message, and push to remote

PR Plugin (pr@codemate):

Command	Description
/pr:get-details	Fetch PR information including title, description, file changes, and review comments
/pr:create	Create a pull request from the current branch; supports standard and fork workflows
/pr:fix-comments	Read PR review comments, fix the issues, commit changes, and reply to comments
/pr:update	Update PR title and/or summary. Use --summary-only to update only the summary
/pr:ack-comments	Acknowledge PR issue comments by adding 👀 reaction

Issue Plugin (issue@codemate):

Command	Description
/issue:read-issue	Read GitHub issue details including title, description, labels, and comments
/issue:refine-issue	Rewrite issue body to match template (plan-then-execute, requires approval)
/issue:triage-issue	Apply priority and category labels based on content analysis
/issue:classify-issue	Post clarifying questions for ambiguous issues and add needs-more-info label

PM Plugin (pm@codemate):

Command	Description
/pm:spec-list	List all spec GitHub Issues with their status and task counts
/pm:spec-init <name>	Start a guided brainstorming session to create a new spec as a GitHub Issue
/pm:spec-plan <issue-number> [--granularity micro|pr|macro]	Post a technical implementation plan as a comment on the spec issue; user must 👍 the comment to approve before decomposing
/pm:spec-decompose <issue-number> [--granularity micro|pr|macro]	Create task sub-issues from the approved plan comment; requires 👍 reaction on the plan comment
/pm:spec-status <issue-number>	Show live progress summary from GitHub Issues
/pm:spec-next <issue-number>	Find the next actionable task based on dependencies
/pm:spec-done <issue-number>	Summarize changes, post a done comment, close the spec issue, and add done label
/pm:spec-abandon <issue-number>	Close the spec issue and optionally its linked task issues

The --granularity flag controls task sizing:

• micro — 0.5–1 day tasks (fine-grained, commit-level)
• pr — 1–3 day tasks, ~200–400 LOC per PR (default)
• macro — 3–7 day milestones / epics

Workspace Plugin (workspace@codemate):

Command	Description
/workspace:best-practice	Bootstrap a repo with spec issue templates, labels, and PR template

The workspace plugin also installs session lifecycle hooks:

• SessionStart — records session start time and current commit
• UserPromptSubmit — records each prompt submission timestamp
• Stop — checks for new commits, sends Slack/Lark notifications if SLACK_WEBHOOK or LARK_WEBHOOK is set

Browser Plugin (agent-browser):

Command	Description
/agent-browser	Automate browser interactions for web testing, form filling, screenshots, and data extraction

Custom Plugins

You can extend CodeMate with your own custom plugins by adding them to your .env file:

# Override default marketplaces (optional)
DEFAULT_MARKETPLACES=vercel-labs/agent-browser,BoringHappy/CodeMate

# Override default plugins (optional)
DEFAULT_PLUGINS=agent-browser@agent-browser,git@codemate,pr@codemate,dev@codemate,issue@codemate,workspace@codemate,pm@codemate

# Set to empty to disable all defaults (optional)
DEFAULT_MARKETPLACES=
DEFAULT_PLUGINS=

# Add custom plugin marketplaces (comma-separated GitHub repo paths)
CUSTOM_MARKETPLACES=username/my-marketplace,org/another-marketplace

# Add custom plugins to install (comma-separated plugin names)
CUSTOM_PLUGINS=my-plugin@my-marketplace,another-plugin@my-marketplace

How it works:

1. By default, CodeMate installs marketplaces from DEFAULT_MARKETPLACES and plugins from DEFAULT_PLUGINS
2. You can override these defaults by setting the environment variables to different values
3. You can disable all defaults by setting them to empty strings
4. Custom marketplaces and plugins are added after defaults during container startup
5. All plugins become available as skills (e.g., /my-plugin:command)
6. The setup is idempotent - already installed plugins are skipped

Example:

If you have a custom plugin marketplace at github.com/myorg/my-plugins with a plugin called deploy, you would configure:

CUSTOM_MARKETPLACES=myorg/my-plugins
CUSTOM_PLUGINS=deploy@my-plugins

Then use it in Claude Code:

/deploy:production

Issue-Based Workflow

CodeMate supports starting work directly from a GitHub issue using the --issue flag. This workflow automatically:

1. Creates a branch named issue-{NUMBER} (or uses existing branch if it already exists)
2. Sends an initial query to Claude to read and address the issue using /issue:read-issue skill
3. Claude analyzes the issue details (title, description, labels, comments)
4. Claude implements the requested changes
5. Creates a PR when you're ready to commit

Example:

# Start working on issue #456
codemate --issue 456

This is equivalent to:

codemate --branch issue-456 --query "Please use /issue:read-issue skill to read and address issue #456"

When to use:

• Starting new work from a GitHub issue
• Implementing feature requests tracked as issues
• Fixing bugs documented in issues

PR Comment Monitoring

CodeMate automatically monitors PR comments and notifies Claude when new feedback arrives. A cron job runs every minute to check for new comments. The monitor only acts when Claude's session is idle (stopped).

What Gets Monitored

Each cron run checks the following in priority order (only one action is taken per run):

1. CI failures — if a CI check fails on the current branch, Claude is sent the failure logs and asked to fix them
2. PR ready for review — when a draft PR is marked ready for review, Claude is asked to update the PR title and description via /pr:update and add a pr-updated label
3. Issue comments — new general PR comments (Conversation tab) without a 👀 reaction are forwarded to Claude
4. Review comments — unresolved inline code comments (Files changed tab) trigger /pr:fix-comments

Comment Types

GitHub PRs have two types of comments that CodeMate monitors:

Type	Location	API Endpoint	Use Case
Review Comments	Files changed tab (inline)	/pulls/{pr}/comments	Code-specific feedback on particular lines
Issue Comments	Conversation tab	/issues/{pr}/comments	General discussion, questions, requests

Review Comments Workflow

When someone leaves a review comment (inline code comment):

1. Monitor detects unresolved review comments
2. Sends message to Claude: "Please use /fix-comments skill to address comments"
3. Claude uses /pr:fix-comments skill to:
   • Read the feedback
   • Make code changes
   • Commit and push
   • Reply with "Claude Replied: ..." to mark as resolved

Issue Comments Workflow

When someone leaves an issue comment (general PR comment):

1. Monitor detects new issue comments without 👀 reaction
2. Sends the actual comment content to Claude
3. Claude processes the request
4. Claude uses /pr:ack-comments skill to add 👀 reaction
5. Future runs skip comments with 👀 reaction

Filtering Logic

Comments are filtered out if they:

• Are posted by bots (login ending in [bot])
• Start with "Claude Replied:" (already handled)
• Have 👀 reaction (already acknowledged)

Best Practices

Add a Pull Request Template

Create .github/PULL_REQUEST_TEMPLATE.md in your target repository to standardize PR descriptions:

## Summary
<!-- Brief description of changes -->

## Test Plan
<!-- How to verify the changes -->

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated

Security Recommendations

• Run CodeMate only on trusted repositories
• Use short-lived GitHub tokens with minimal scopes
• Avoid mounting sensitive host directories
• Review changes before merging PRs created by Claude

License

MIT