How to Set Up OpenCode CLI Shared Configs for Team Collaboration

Mar 30, 2026

The Problem: Every Team Member Configuring OpenCode Differently

When our team first adopted OpenCode CLI, we quickly ran into a familiar problem. Each developer was setting up their own CLAUDE.md files, creating their own agents, and configuring MCPs independently. The result? Chaos.

Sarah had company security rules in her config. Mike didn’t. The backend team had their database MCPs loaded, while the frontend team was missing them entirely. New team members spent days figuring out the “right” way to configure OpenCode for our projects.

Worse yet, context windows were getting bloated. Some developers loaded every MCP and agent at once, turning a lean coding assistant into a sluggish mess. Others missed critical hooks that could have automated their workflows.

We needed a better approach—a way to share configuration without duplicating effort, maintain consistency across teams, and keep context clean and focused.

The Solution: Layered Configuration Architecture

After experimenting with different approaches, I discovered OpenCode CLI’s support for shared configuration via GitHub-hosted config files. The key insight? Layer your configuration instead of loading everything at once.

Here’s the architecture that works:

┌─────────────────────────────────────────┐
│         Base Configuration               │
│  (Company-wide context, security,       │
│   core agents, essential MCPs)           │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│         Team Configuration               │
│  (Team-specific MCPs, agents,           │
│   specialized skills)                    │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│         Local Configuration              │
│  (Personal preferences, project-         │
│   specific overrides)                    │
└─────────────────────────────────────────┘

This layered approach means:

Base config loads always (company context, security rules, basic agents)
Team configs load on-demand when you switch projects or tasks
Local config references and extends shared settings

Why This Matters for Your Team

Performance

Loading all MCPs and agents at startup creates bloated context windows. By loading team-specific configs on-demand, we keep OpenCode fast and responsive. The backend team’s database MCPs don’t load when a frontend developer is working on UI components.

Consistency

Everyone starts from the same base configuration. Security rules, company context, and core workflows are standardized. No more “works on my machine” configuration issues.

Flexibility

Teams can maintain their specialized tools without forcing everyone else to load them. The DevOps team’s infrastructure MCPs stay separate from the mobile team’s iOS deployment tools.

Scalability

Adding a new team member? They clone one config repo and they’re ready to go. Creating a new team? Copy a template directory and customize.

Repository Structure for Shared Configs

Let me show you how I set up our shared configuration repository:

opencode-configs/
├── base/
│   ├── CLAUDE.md           # Base instructions and context
│   ├── security.md         # Security guidelines
│   └── hooks/
│       └── session-start.sh
├── teams/
│   ├── backend/
│   │   ├── CLAUDE.md       # Backend team context
│   │   ├── agents/         # Backend-specific agents
│   │   └── mcps/           # Database, API MCPs
│   ├── frontend/
│   │   ├── CLAUDE.md       # Frontend team context
│   │   └── agents/         # UI, component agents
│   └── devops/
│       ├── CLAUDE.md       # DevOps team context
│       └── hooks/          # Deployment automation
└── templates/
    └── new-team/           # Template for new teams

This structure keeps everything organized. The base/ directory contains universal settings, while teams/ holds team-specific configurations that load on-demand.

Setting Up Base Configuration

The base configuration defines what every team member gets automatically. Here’s our base/CLAUDE.md:

# Company OpenCode Configuration

## Company Context

We're a SaaS company building project management tools. Our tech stack:
- Backend: Python (FastAPI), PostgreSQL
- Frontend: React, TypeScript, Tailwind CSS
- Infrastructure: AWS, Kubernetes

## Core Agents

Always use these agents for common tasks:
- **planner**: For implementation planning
- **code-reviewer**: For code review after writing
- **tdd-guide**: For test-driven development

## Security Rules

NEVER:
- Commit secrets or API keys
- Use hardcoded credentials
- Skip input validation

ALWAYS:
- Use environment variables for secrets
- Validate all user inputs
- Follow OWASP guidelines

## Standard Workflow

1. Plan before coding (use planner agent)
2. Write tests first (use tdd-guide)
3. Implement features
4. Review code (use code-reviewer)
5. Commit with descriptive messages

This base config ensures everyone follows the same patterns and has access to company context.

Team-Specific Configuration

Each team extends the base with their specialized tools. Here’s an example for the backend team:

# Backend Team Configuration

Extends base configuration with backend-specific settings.

## Team Context

Backend team focuses on:
- API development
- Database design
- Performance optimization
- Security hardening

## Team Agents

- **api-designer**: REST/GraphQL API design
- **db-optimizer**: Query optimization and indexing
- **security-auditor**: Security analysis

## Team MCPs

Load these MCPs on-demand:
- **database**: PostgreSQL schema and query tools
- **aws-cli**: AWS resource management
- **docker**: Container management

## Hooks

Session start hook checks for:
- Database connection status
- API test coverage
- Security scan results

Local Configuration Referencing Shared Config

In each project repository, the local CLAUDE.md references the shared config:

# Project Configuration

## Shared Config Reference

This project uses the backend team configuration from:
github.com/yourcompany/opencode-configs/teams/backend

## Project-Specific Context

This is the authentication microservice:
- JWT token handling
- OAuth2 integration
- Session management

## Override Rules

When working on auth endpoints:
1. Always run security-auditor agent before commits
2. Ensure 90%+ test coverage
3. Check for OWASP Top 10 vulnerabilities

## Load Command

Run this command at session start:
```bash title="Load team configuration"
opencode load-config github.com/yourcompany/opencode-configs/teams/backend

This lightweight local config pulls in the team configuration while adding project-specific context.

## Automating with Session Start Hooks

One of the most powerful features is the session start hook. Here's how I set it up:

```bash title="hooks/session-start.sh"
#!/bin/bash

# Detect which team's project we're in
if [ -f "backend.requirements.txt" ]; then
    TEAM="backend"
elif [ -f "package.json" ] && grep -q "react" "package.json"; then
    TEAM="frontend"
elif [ -f "terraform" ]; then
    TEAM="devops"
else
    TEAM="base"
fi

# Load appropriate team config
echo "Loading $TEAM configuration..."
opencode load-config "github.com/yourcompany/opencode-configs/teams/$TEAM"

# Run team-specific setup
case $TEAM in
    backend)
        python -c "import database; database.check_connection()" 2>/dev/null
        ;;
    frontend)
        npm run type-check 2>/dev/null
        ;;
esac

echo "Session ready for $TEAM development!"

This hook automatically detects the project type and loads the appropriate configuration.

Common Mistakes to Avoid

Loading Everything at Once

❌ Loading all team configs at startup
❌ Including every MCP in base config
❌ Adding all agents to CLAUDE.md

This bloats the context window and slows down responses. Instead, load only what you need for the current task.

Missing Hooks

Hooks automate repetitive tasks. Without them, you’re manually running the same commands every session. Set up session-start hooks to:

Load appropriate team configs
Check environment status
Run initial validation

Ignoring Security in Base Config

Every team member should have security rules loaded by default. Don’t assume everyone knows the security guidelines—make them explicit in the base configuration.

Not Using Templates

When creating a new team, start from the template. This ensures consistency and prevents missing critical configurations.

Real-World Impact

Since implementing shared configurations:

Onboarding time reduced by 70%: New developers clone one repo and start coding
Context window usage optimized: Only relevant MCPs load for each task
Security compliance improved: Base config ensures everyone follows guidelines
Team collaboration enhanced: Shared agents and workflows create common patterns

One team member put it well: “This way your context isn’t bloated with other teams’ skills, but you’re able to pull it whenever you have a related task or need.” That’s exactly the balance we wanted.

Getting Started

Ready to implement shared configs for your team?

Create a opencode-configs repository on GitHub
Set up the base configuration with company-wide settings
Create team-specific directories
Add session-start hooks for automatic loading
Reference the shared config in project CLAUDE.md files

Start small—with just base and one team configuration—and expand as needed. The layered architecture grows naturally with your organization.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!