🤖Claude Code Automation

This repository is configured to work with Claude Code automation for issue resolution. When you assign an issue to Claude Code, it will automatically create a branch, implement the solution, and create a pull request.

How It Works

1. Creating an Issue for Claude Code

Use the "Claude Code Task" issue template or manually:

1. Create a new issue

2. Add the claude-code label

3. Assign to claude-code-bot (or ensure the label is present)

4. Provide clear requirements and acceptance criteria

2. Automatic Process

When an issue is assigned to Claude Code, the automation will:

1. Create Branch: Generate a new branch named claude/issue-{number}-{title}

2. Comment: Add a comment to the issue indicating work has started

3. Implement: Analyze requirements and implement the solution

4. Quality Checks: Run tests, formatting, and type checking

5. Commit: Create meaningful commits with the changes

6. Pull Request: Create a PR linking back to the issue

3. Review Process

After Claude Code completes the work:

1. Review the generated pull request

2. Check that all requirements are met

3. Run additional tests if needed

4. Merge when satisfied or request changes

Configuration Requirements

Repository Secrets

The following secrets must be configured in your repository:

• ANTHROPIC_API_KEY: Your Anthropic API key for Claude Code

• GITHUB_TOKEN: Automatically provided by GitHub Actions

Permissions

The workflow requires the following permissions:

• contents: write - To create branches and commits

• issues: write - To comment on issues

• pull-requests: write - To create pull requests

• id-token: write - For authentication

Environment Requirements

• Python Version: The workflow uses Python 3.10+ (required for MCP SDK compatibility)

• Package Manager: Uses uv for fast dependency installation

• Development Tools: Includes pytest, ruff, and mypy for quality checks

Workflow Configuration

The automation is configured in .github/workflows/claude-issue-assignment.yml with:

assignee_trigger: "basher83,claude-code-bot"  # Users who can trigger automation
allowed_tools: "bash,read,write,edit,glob,grep"  # Tools Claude Code can use
timeout_minutes: "120"  # Maximum execution time

Issue Template Guidelines

When creating issues for Claude Code, include:

Clear Task Description

## Task Description
Add support for VM snapshot management in the Proxmox MCP server.

Specific Requirements

## Requirements
- [ ] Add `create_vm_snapshot` tool
- [ ] Add `delete_vm_snapshot` tool
- [ ] Add `restore_vm_snapshot` tool
- [ ] Include proper error handling

Acceptance Criteria

## Acceptance Criteria
- [ ] All tools follow existing patterns in tools/ directory
- [ ] Proper Pydantic models for validation
- [ ] Rich formatted output
- [ ] Tests included

Technical Details

## Technical Details
- Use the existing ProxmoxManager pattern
- Follow the formatting standards in formatting/ module
- Add to tools/vm.py or create tools/snapshot.py

Best Practices

For Issue Creation

• Be specific about requirements

• Provide examples of expected behavior

• Include error cases to handle

• Reference existing code patterns when applicable

For Review

• Check that the solution follows project conventions

• Verify tests are comprehensive

• Ensure documentation is updated if needed

• Test the implementation manually if possible

Troubleshooting

Common Issues

Workflow doesn't trigger:

• Ensure the issue has the claude-code label

• Check that the assignee is in the assignee_trigger list (basher83 or claude-code-bot)

• Verify repository secrets are configured

• Confirm the workflow file is on the main branch

Python dependency errors:

• The workflow requires Python 3.10+ for MCP SDK compatibility

• Check that pyproject.toml specifies requires-python = ">=3.10"

• Verify MCP dependencies are compatible with the Python version

Implementation fails:

• Check the workflow logs for detailed error messages

• Ensure the task description is clear and actionable

• Verify the requirements don't conflict with existing code

• Check that the ANTHROPIC_API_KEY secret is properly configured

Quality checks fail:

• The workflow runs: pytest && ruff format . && mypy . && ruff check .

• Claude Code will attempt to fix issues automatically

• Manual intervention may be needed for complex conflicts

• Check individual tool logs for specific failures

Missing ASSIGNEE_TRIGGER error:

• Ensure assignee_trigger parameter is set in the workflow

• Add your GitHub username to the trigger list

• Verify the workflow configuration matches the action requirements

Debugging Steps

1. Check workflow run logs: Go to Actions tab → failed run → view logs

2. Verify issue setup: Confirm labels, assignee, and issue description

3. Test locally: Run uv pip install -e ".[dev]" to check dependencies

4. Check secrets: Ensure ANTHROPIC_API_KEY is configured in repository settings

Getting Help

If you encounter issues with the automation:

1. Check the GitHub Actions logs for detailed error information

2. Review the issue description for clarity and completeness

3. Ensure all required repository secrets are configured

4. Verify Python and dependency compatibility

5. Create a support issue if problems persist

Workflow Execution Details

Step-by-Step Process

When an issue is assigned to trigger the automation, the following steps occur:

1. Branch Creation

   # Creates branch name from issue number and title
   BRANCH_NAME="claude/issue-${ISSUE_NUMBER}-${CLEAN_TITLE}"
   git checkout -b "$BRANCH_NAME"
   git push origin "$BRANCH_NAME"

2. Environment Setup

   # Set up Python 3.10 environment
   uv venv
   source .venv/bin/activate
   uv pip install -e ".[dev]"

3. Claude Code Implementation

   • Analyzes issue requirements and codebase

   • Implements solution following project patterns

   • Runs quality checks: pytest && ruff format . && mypy . && ruff check .

   • Creates meaningful commits with proper messages

4. Pull Request Creation

   • Automatic PR with descriptive title

   • Links back to the original issue

   • Includes summary of changes made

   • Ready for review and testing

Quality Assurance

The workflow automatically runs these checks:

• pytest: All test suites must pass

• ruff: Code formatting and linting compliance

• mypy: Type checking validation

• Project patterns: Follows existing code conventions

Example Workflow

1. Create Issue: Use the Claude Code Task template

   Title: [CLAUDE] Add VM backup scheduling feature
   Description: Clear requirements and acceptance criteria
   Labels: claude-code, automation
   Assignee: basher83

2. Automatic Processing:

   • Workflow triggers on assignment

   • Creates branch claude/issue-123-add-vm-backup-scheduling-feature

   • Adds comment to issue with progress updates

3. Implementation:

   • Code is analyzed, written, and tested

   • All quality checks must pass

   • Multiple commits with descriptive messages

4. Pull Request:

   • PR #124 created automatically

   • Links to issue #123 with "Closes #123"

   • Includes implementation summary

5. Review: You review and merge the PR

6. Completion: Issue #123 is automatically closed

This automation streamlines the development process while maintaining code quality and project standards.