Claude Code-Style Agents for GitHub Copilot

Transform GitHub Copilot into an autonomous development assistant with Claude Code's philosophy of transparency, verification, and continuous iteration.

What This Is

Two specialized GitHub Copilot agents that replicate Claude Code's autonomous development experience:

🔍 Query Agent

Your read-only exploration expert:

• Analyzes codebases and explains architecture
• Answers technical questions with code examples
• Plans implementations before execution
• Searches efficiently across your project
• Never modifies files

⚡ Execute Agent

Your autonomous implementer:

• Implements multi-file features with testing
• Self-corrects errors through iteration
• Runs tests after every change
• Commits incremental progress
• Maintains Claude Code's master loop workflow

Key Features

✨ Transparent Operations: Every tool use is announced and explained
🔄 Self-Correction Loops: Automatically fixes errors by iterating
🧪 Continuous Testing: Tests run after every code change
📝 Context Management: Maintains project memory through CLAUDE.md
🎯 Incremental Commits: Logical units committed automatically
🔧 MCP Integration: Extends capabilities with external tools
📚 Agent Skills: Reusable workflows for complex tasks

Quick Start

Prerequisites

• VS Code 1.99+ with GitHub Copilot extension
• Active GitHub Copilot subscription
• Node.js 18+ (for MCP servers)

Installation (5 minutes)

# 1. Create directory structure
mkdir -p .github/agents .github/instructions .github/skills
mkdir -p .vscode .claude

# 2. Copy agent files
cp query.agent.md .github/agents/
cp execute.agent.md .github/agents/

# 3. Copy configuration
cp copilot-instructions.md .github/
cp mcp.json .vscode/

# 4. Copy skills
cp -r skills/* .github/skills/

# 5. Reload VS Code
# Cmd/Ctrl+Shift+P → "Reload Window"

First Test

1. Open Copilot Chat (Ctrl+Alt+I / Cmd+Ctrl+I)
2. Select "query" from agent dropdown
3. Type: "Analyze this project and create CLAUDE.md"
4. Watch Query agent explore your codebase
5. Switch to "execute" agent
6. Type: "Create a simple test function with tests"
7. Watch Execute agent implement, test, and commit

How It Works

The Claude Code Philosophy

Both agents follow Claude Code's master loop:

1. ANALYZE - Understand current state
2. PLAN - Decide next action  
3. EXECUTE - Use tools transparently
4. VERIFY - Check results
5. ITERATE - Fix errors or continue

Agent Specialization

Query Agent focuses on:

• Reading and understanding code
• Searching across the codebase
• Explaining technical concepts
• Creating implementation plans
• Never modifying files

Execute Agent focuses on:

• Making code changes
• Running tests continuously
• Self-correcting errors
• Committing working code
• Always verifying changes

Usage Examples

Understanding Code

Query: "How does authentication work in this project?"

→ Agent searches for auth files
→ Reads implementations
→ Explains the flow
→ Shows key files and patterns

Planning Features

Query: "Create a plan to add OAuth2 authentication"

→ Analyzes current auth system
→ Identifies files to modify
→ Lists steps with verification
→ Hands plan to Execute agent

Implementing Features

Execute: "Implement the OAuth2 plan"

→ Explores current code
→ Installs dependencies
→ Creates strategy files
→ Updates services
→ Adds tests
→ Runs tests after each change
→ Fixes any failures
→ Commits when green

Fixing Bugs

Execute: "Fix the failing test in auth.test.ts"

→ Reads test file
→ Runs tests to see failure
→ Analyzes error message
→ Identifies root cause
→ Applies fix
→ Reruns tests
→ Iterates until passing
→ Commits fix

Project Structure

your-project/
├── .github/
│   ├── agents/
│   │   ├── query.agent.md           # Query agent configuration
│   │   └── execute.agent.md         # Execute agent configuration
│   ├── instructions/
│   │   └── copilot-instructions.md  # Universal behavior rules
│   └── skills/
│       ├── autonomous-implementation/
│       │   └── SKILL.md             # Multi-file implementation workflow
│       └── context-management/
│           └── SKILL.md             # Project memory management
├── .claude/
│   └── CLAUDE.md                    # Project context & memory
└── .vscode/
    ├── settings.json                # VS Code configuration
    └── mcp.json                     # MCP server configuration

Core Concepts

1. Transparency

Every action is announced before execution:

**Next Action**: I'll update auth.service.ts to add validation

[writeFile: "src/auth/auth.service.ts"]

**Changes made**:
- Added validateEmail() function
- Updated login() to use validation

2. Verification Loop

Tests run automatically after changes:

Change file → Run tests → Pass ✓
Change file → Run tests → Fail ✗ → Fix → Retest → Pass ✓

3. Context Management

CLAUDE.md maintains project memory:

# Recent Decisions
- Using bcrypt for password hashing (10 rounds)
- JWT tokens expire in 7 days
- Rate limiting: 5 requests/minute

# Current State
- ✅ Authentication complete
- 🔄 OAuth2 in progress (80%)
- ⏳ Admin dashboard next

4. Self-Correction

Automatic error recovery:

Attempt 1: Change → Test → Fail → Analyze error
Attempt 2: Fix → Test → Fail → Try alternative
Attempt 3: Alternative fix → Test → Pass ✓

Advanced Features

Multi-Model Support

Leverage GitHub Copilot's model flexibility:

# In agent file
model: claude-sonnet-4-5   # For code understanding
model: gpt-4.1             # For terminal proficiency  
model: gemini-3-pro        # For large context

MCP Integration

Extend capabilities with external tools:

{
  "mcpServers": {
    "filesystem": { ... },  // File operations
    "git": { ... },         // Version control
    "terminal": { ... },    // Shell commands
    "database": { ... }     // Database access
  }
}

Agent Skills

Reusable workflows for common tasks:

• autonomous-implementation: Full feature development
• context-management: Project memory maintenance
• Custom skills: Create your own workflows

Configuration

Agent Behavior

Control how agents operate:

{
  "github.copilot.chat.agent.toolConfirmation": "auto",  // Auto-approve safe commands
  "github.copilot.chat.agent.verbosity": "verbose",      // Show all details
  "github.copilot.chat.streaming": true                   // Real-time output
}

Model Selection

Choose optimal models per agent:

# query.agent.md
model: claude-sonnet-4-5  # Best for analysis

# execute.agent.md
model: claude-sonnet-4-5  # Best for implementation

Tool Permissions

Control what agents can do:

# Query agent (read-only)
tools:
  - readFile
  - search
  - grep
  # No write tools

# Execute agent (full access)
tools:
  - readFile
  - writeFile
  - executeCommand
  - runTests

Best Practices

1. Query Before Execute

✅ Query: "How is error handling done?"
→ Execute: "Add error handling following that pattern"

❌ Execute: "Add error handling" (without understanding current patterns)

2. Specific Prompts

✅ "Add email validation to UserService.register()"
❌ "Improve the code"

3. Trust the Iteration

Execute agent may take 2-5 attempts to get it right.
This is expected and means it's self-correcting.

4. Maintain CLAUDE.md

Update after:
- Major architectural decisions
- New coding patterns established  
- Significant features completed

5. Review Before Production

Execute agent commits automatically, but:
- Review diffs before pushing
- Run full test suite locally
- Check CLAUDE.md is current

Comparison: Claude Code vs This Implementation

Feature	Claude Code	These Agents
Transparency	✅ Master loop	✅ Same philosophy
Self-correction	✅ Automated	✅ Multiple attempts
Testing	✅ After each change	✅ After each change
Context management	✅ CLAUDE.md	✅ CLAUDE.md
Terminal access	✅ Native	✅ Via MCP
Multi-model	❌ Single family	✅ Multiple providers
IDE integration	❌ CLI-first	✅ VS Code native
Enterprise governance	⚠️ Limited	✅ Copilot Control Plane

Troubleshooting

Agents not appearing

# Check file locations
ls .github/agents/

# Verify file names
# Must be: *.agent.md

# Reload VS Code
Cmd/Ctrl + Shift + P → "Reload Window"

MCP not working

# Test Node.js
node --version

# Test MCP server
npx -y @modelcontextprotocol/server-terminal

# Check VS Code output
View → Output → "GitHub Copilot Chat"

Tests not running

# Verify test command
npm test

# Update CLAUDE.md
# Add: "Test command: npm test"

# Tell Execute agent
"Read CLAUDE.md for test command"

Documentation

• 📘 Setup Guide - Complete installation instructions
• 📝 Quick Reference - Daily usage cheat sheet
• 🔧 Query Agent - Full agent specification
• ⚡ Execute Agent - Full agent specification
• 🎯 Instructions - Behavior rules

Examples

See working examples in the examples/ directory:

• Feature implementation workflow
• Bug investigation and fix
• Refactoring with tests
• Multi-file architectural changes

Contributing

Want to improve these agents?

1. Report Issues: Share problems or edge cases
2. Suggest Features: Propose new capabilities
3. Share Skills: Create reusable workflow skills
4. Improve Docs: Clarify instructions or add examples

FAQ

Q: Do I need a special Copilot subscription? A: Standard GitHub Copilot works. Pro+ unlocks more features.

Q: Will this work with my language/framework? A: Yes! Agents are language-agnostic. Just update CLAUDE.md with your commands.

Q: How is this different from regular Copilot? A: These agents add Claude Code's autonomous workflow: transparency, testing, iteration, and context management.

Q: Can I customize the agents? A: Absolutely! Edit the .agent.md files to adjust behavior, tools, and instructions.

Q: Will agents commit to my main branch? A: Execute agent commits locally. You control pushing. Consider using feature branches.

Q: What if I don't like a change? A: Git tracks everything. Use git reset or review before pushing.

License

MIT License - Use freely in personal and commercial projects.

Credits

Inspired by:

• Anthropic's Claude Code architecture
• GitHub Copilot's agent framework
• Model Context Protocol specification

Support

• 📖 Read the Setup Guide
• 📝 Check the Quick Reference
• 🔍 Review VS Code Output panel for errors
• 💬 Open an issue for bugs or questions

---

Ready to start? Follow the Setup Guide to install in 5 minutes.

Quick test: Select "query" agent and type "Analyze this project" 🚀