🐻 Berko Multi-Agent Extension

Build AI agent teams that collaborate on complex tasks using GitHub Copilot

🎯 What is Berko?

Berko is a VS Code extension that lets you create teams of AI agents that work together on your tasks. Instead of chatting with a single AI, you can:

• 🏗️ Create specialized agents (Frontend Dev, Backend Dev, QA, Tech Lead, etc.)
• 🤝 Watch them collaborate - agents can mention and delegate to each other
• 💬 Join the conversation - type messages anytime during agent discussions
• 📝 Persist context - each conversation remembers its history
• 📋 Define team rules - each team can have its own set of shared rules
• 🎨 Per-agent models - assign different AI models to different agents
• 🛠️ Skills support - agents can auto-discover and use skills from .github/skills/
• 📂 Use existing agents - compatible with .github/agents/ and standard agent formats

⚡ One-Time Setup (5 minutes)

Before using Berko, you need to install and authenticate the GitHub Copilot CLI.

Prerequisites:

• GitHub Copilot subscription (active)
• Node.js 18+ (for npm)

Step 1: Install GitHub Copilot CLI

Open VS Code's integrated terminal (`Ctrl+``) and run:

npm install -g @github/copilot

⚠️ Important: Install from VS Code's terminal to ensure it works immediately. Installing from external terminals may require a VS Code restart.

Step 2: Authenticate with GitHub

In the same VS Code terminal:

copilot

Once the CLI starts, type:

/login

Follow the browser authentication flow to connect your GitHub account.

Step 3: Verify Installation

copilot --version

If you see a version number, you're ready to go! 🎉

🚀 Quick Start

Step 1: Create Your First Team

1. Open VS Code in any workspace
2. Click the Berko bear icon 🐻 in the sidebar
3. Click "+" next to "Teams" to create a new team
4. Enter a name (e.g., "Development Team")

Step 2: Create Agents

Click "+" next to "Available Agents" to create a new agent:

1. Enter an agent name (e.g., "Senior Developer")
2. The agent file opens for editing
3. Customize their role, personality, and instructions in the markdown file

Agents are stored in agents/ folder as .md files.

Step 3: Add Agents to Your Team

From the "Available Agents" section:

1. Find the agent you want to add
2. Right-click the agent → "Add to Team"
3. Select which team to add them to

You can also:

• Right-click a team → "Add Agent" to browse available agents
• Add the same agent to multiple teams

Step 4: Start Chatting!

1. Click on a team to select all its agents
2. Type a message and press Send
3. Watch the agents initialize and respond
4. Use @AgentName to mention specific agents

📖 Core Features

🧑‍🤝‍🧑 Team-Based Organization

Create multiple teams for different projects or workflows:

• Development Team: Frontend, Backend, DevOps
• Design Team: UX Designer, UI Designer, Researcher
• Review Team: Code Reviewer, Security Auditor, QA

Teams are stored in .berko/teams/ as .team.md files with YAML frontmatter and team rules in the markdown body.

💬 Multi-Agent Conversations

Agents collaborate through @mentions:

• You send a message → Agent responds
• Agent mentions @Teammate → Message is routed automatically
• Parallel processing: Mention multiple agents (@Senior and @Junior) - they work simultaneously!

📋 Team Rules

Define shared rules in your .team.md file that all agents follow:

• Communication guidelines
• Coding standards
• Workflow conventions
• Quality requirements

Team rules are automatically injected into every agent's initialization.

🎨 Per-Agent Model Selection

Assign different AI models to different agents for cost optimization:

---
name: "QuickResponder"
description: "Fast responses for simple tasks"
model: "gpt-5-mini"
---

---
name: "DeepThinker"  
description: "Complex analysis and architecture"
model: "claude-opus-4.5"
---

Available Models: | Model | Description | |-------|-------------| | claude-opus-4.5 | Most powerful | | claude-sonnet-4.5 | Balanced | | claude-sonnet-4 | Fast Sonnet | | claude-haiku-4.5 | Fastest Claude | | gpt-5.2 | Latest GPT | | gpt-5.1 | GPT 5.1 | | gpt-5 | GPT 5 | | gpt-5-mini | Fast GPT-5 | | gpt-5.1-codex-max | Max coding | | gpt-5.1-codex | Coding optimized | | gpt-5.1-codex-mini | Fast coding | | gpt-4.1 | GPT 4.1 | | gemini-3-pro-preview | Google Gemini |

🛠️ Skills Support

Berko auto-discovers skills from .github/skills/ in your workspace:

your-workspace/
├── .github/
│   └── skills/
│       └── kusto-cli/
│           ├── SKILL.md
│           └── QUICKREF.md

Agents can reference and use skill knowledge automatically.

📂 Conversation History

• Create multiple conversations
• Each conversation has its own agent sessions
• Resume previous conversations with full memory
• Sessions persist across VS Code restarts

🛠️ Agent Configuration

Agents are defined in Markdown files with YAML frontmatter:

---
name: "Senior"
description: "Experienced developer who mentors juniors"
role: "Lead Developer"
model: "claude-sonnet-4"
tools: []
---

# Senior Developer

## Purpose
You are a senior developer with 10+ years of experience.
You write clean, maintainable code and mentor junior developers.

## Guidelines
- Write clean, maintainable code
- Follow SOLID principles  
- Delegate simpler tasks to @Junior
- Always explain your reasoning

Frontmatter Properties

The markdown body becomes the agent's system prompt.

📋 Team Configuration

Teams are defined in .berko/teams/ as .team.md files:

---
name: "DevTeam"
description: "Core development team"
agents:
  - "agents/senior.md"
  - "agents/junior.md"
  - ".github/agents/reviewer.md"
---

# Team Rules

## Communication Guidelines
- Be concise and technical
- Use code blocks for all code
- Mention @Name when delegating tasks

## Quality Standards
- All code must have error handling
- Include unit tests for new features
- Follow existing code patterns

🗂️ File Structure

Recommended Structure

your-workspace/
├── .berko/
│   └── teams/
│       ├── dev-team.team.md      # Team definitions
│       └── qa-team.team.md
├── .github/
│   ├── agents/                    # GitHub Copilot agents (auto-discovered)
│   │   └── copilot-expert.md
│   └── skills/                    # Skills for agents
│       └── my-skill/
│           └── SKILL.md
├── agents/                        # Your agents (auto-discovered)
│   ├── senior.md
│   ├── junior.md
│   └── reviewer.md
├── .berko-sessions/               # Session persistence (auto-generated)
│   └── {conversation-id}/
│       ├── Senior.session
│       └── Junior.session
└── .berko-conversations/          # Chat history (auto-generated)

Auto-Discovery Paths

Berko automatically discovers agents from:

• agents/ - Standard agents folder
• .github/agents/ - GitHub Copilot format
• .berko/agents/ - Berko-specific agents

Agents appear in "Available Agents" and can be added to any team.

⌨️ Commands

Context Menu Actions

On Teams:

• 📝 Edit Team Rules - Open the .team.md file
• ➕ Add Agent - Add an available agent to this team
• 🧹 Clear Sessions - Reset all agent memory in this team
• 🗑️ Delete Team - Remove the team

On Agents:

• 📝 Edit Agent - Open the agent .md file
• 🔄 Add to Team - Add this agent to a team
• ➖ Remove from Team - Remove from current team
• 🧹 Clear Session - Reset this agent's memory
• 🗑️ Delete Agent - Remove the agent file

💡 Tips & Tricks

Use @mentions for Directed Tasks

@Junior please implement the login form
@Senior please review @Junior's implementation

Parallel Processing

@Frontend and @Backend implement the user profile feature

Both agents work simultaneously!

Create Workflow Chains

Define in your agent prompts:

After completing your task, ask @QA to verify the implementation.

Leverage Specialists

Create agents with specific expertise:

• Database Expert - SQL optimization, schema design
• Security Auditor - Vulnerability scanning, best practices
• Performance Engineer - Profiling, optimization

Mix Models for Efficiency

🔧 Settings

Access via VS Code Settings > Extensions > Berko:

🐛 Troubleshooting

"Copilot CLI not found"

1. Open VS Code's integrated terminal (`Ctrl+``)
2. Run: npm install -g @github/copilot
3. Verify: copilot --version

If you installed from an external terminal, restart VS Code completely.

"Authentication required"

1. Open VS Code terminal
2. Run: copilot
3. Type: /login
4. Complete the browser authentication

Agent not adopting persona

1. Clear the agent's session (right-click → Clear Session)
2. Start a new conversation
3. Check the debug console (Extension Host) for [INIT] logs

Agents not responding

1. Check CLI: copilot --version (in VS Code terminal)
2. Check auth: copilot then /status
3. Clear sessions and try again
4. Check Extension Host console for errors

Slow initialization

First-time agent initialization takes ~30-60 seconds. Subsequent messages are faster.

Changes to agent file not working

Agent files are re-read on initialization. Either:

• Start a new conversation, or
• Clear the agent's session to force re-initialization

📋 Requirements

🤝 Contributing

🚧 Coming Soon! This project will be open-sourced and ready for contributions. Stay tuned!

📄 License

MIT License

Happy collaborating with your AI team! 🐻