DEV Community

Cover image for Managing goose Configurations Across Multiple Projects
Lymah
Lymah

Posted on

Managing goose Configurations Across Multiple Projects

#goose #ai #llm #opensource

As development teams scale their use of goose across multiple projects, a new challenge emerges: how do you maintain consistent configurations while adapting to each project's unique needs? In my previous post on team environments, we explored shared workflows within a single project. Now, let's tackle the multi-project configuration challenge.

The Multi-Project Configuration Problem

When working with goose across multiple projects, teams often face:

  • Configuration drift between projects leading to inconsistent behavior
  • Duplicated configuration that becomes painful to maintain
  • Context switching overhead when moving between projects
  • Onboarding friction as team members learn different configurations for each project

The goal is to establish a scalable configuration strategy that maintains consistency where needed while allowing project-specific customization.

Configuration Hierarchy Strategy

The most effective approach uses a three-tier configuration hierarchy:

1. Global Base Configuration

Create a shared base configuration that defines organization-wide standards:

# ~/.config/goose/profiles.yaml (global)
default:
  provider: openai
  processor: gpt-4
  accelerator: gpt-4
  moderator: truncate

organization-standards:
  provider: openai
  processor: gpt-4
  accelerator: gpt-4
  moderator: truncate
  toolkits:
    - name: developer
    - name: github
      requires:
        GITHUB_TOKEN: github-token
Enter fullscreen mode Exit fullscreen mode

This global configuration serves as your baseline, ensuring all projects start with consistent standards.

2. Project-Specific Configuration

Each project maintains its own .goose/profiles.yaml that extends or overrides the base:

# project-a/.goose/profiles.yaml
default:
  provider: openai
  processor: gpt-4
  accelerator: gpt-4
  moderator: truncate
  toolkits:
    - name: developer
    - name: github
      requires:
        GITHUB_TOKEN: github-token
    - name: repo_context
      requires:
        path: .

backend-dev:
  extends: default
  toolkits:
    - name: docker
    - name: database
Enter fullscreen mode Exit fullscreen mode

3. Personal Overrides

Individual developers can customize further with local overrides:

# project-a/.goose/profiles.local.yaml (gitignored)
default:
  provider: anthropic  # Personal preference
  processor: claude-sonnet-4.5
Enter fullscreen mode Exit fullscreen mode 
## Practical Implementation Strategies

### Strategy 1: Configuration Templates Repository

Create a dedicated repository for configuration templates:
goose-configs/
├── README.md
├── templates/
│   ├── base/
│   │   └── profiles.yaml
│   ├── web-app/
│   │   └── profiles.yaml
│   ├── api-service/
│   │   └── profiles.yaml
│   └── data-pipeline/
│       └── profiles.yaml
└── scripts/
    ├── init-project.sh
    └── sync-config.sh
Enter fullscreen mode Exit fullscreen mode

init-project.sh example:

#!/bin/bash
# Initialize goose config for a new project

PROJECT_TYPE=$1
TEMPLATE_PATH="templates/${PROJECT_TYPE}/profiles.yaml"

if [ ! -f "$TEMPLATE_PATH" ]; then
    echo "Unknown project type: $PROJECT_TYPE"
    echo "Available types: base, web-app, api-service, data-pipeline"
    exit 1
fi

mkdir -p .goose
cp "$TEMPLATE_PATH" .goose/profiles.yaml

echo "✓ goose configuration initialized for $PROJECT_TYPE"
echo "Next steps:"
echo "1. Review .goose/profiles.yaml"
echo "2. Add .goose/profiles.local.yaml to .gitignore"
echo "3. Commit .goose/profiles.yaml to version control"
Enter fullscreen mode Exit fullscreen mode

Strategy 2: Configuration as Code with Validation

Implement configuration validation to catch issues early:

# .goose/profiles.yaml with schema validation
default:
  provider: openai
  processor: gpt-4
  accelerator: gpt-4
  moderator: truncate

  # Validation metadata
  _metadata:
    schema_version: "1.0"
    required_env_vars:
      - OPENAI_API_KEY
      - GITHUB_TOKEN
    team: "platform-team"
    last_updated: "2025-10-30"
Enter fullscreen mode Exit fullscreen mode

Create a validation script:

# scripts/validate-goose-config.py
import yaml
import os
import sys

def validate_config(config_path):
    """Validate Goose configuration file"""
    errors = []

    with open(config_path) as f:
        config = yaml.safe_load(f)

    # Check required environment variables
    metadata = config.get('default', {}).get('_metadata', {})
    required_vars = metadata.get('required_env_vars', [])

    for var in required_vars:
        if not os.getenv(var):
            errors.append(f"Missing required environment variable: {var}")

    # Validate profile structure
    for profile_name, profile in config.items():
        if profile_name.startswith('_'):
            continue

        if 'provider' not in profile:
            errors.append(f"Profile '{profile_name}' missing required 'provider' field")

    return errors

if __name__ == '__main__':
    errors = validate_config('.goose/profiles.yaml')
    if errors:
        print("❌ Configuration validation failed:")
        for error in errors:
            print(f"  - {error}")
        sys.exit(1)
    else:
        print("✓ Configuration valid")
Enter fullscreen mode Exit fullscreen mode

Strategy 3: Environment-Specific Profiles

Structure profiles to handle different environments:

# .goose/profiles.yaml
default:
  provider: openai
  processor: gpt-4
  accelerator: gpt-4
  moderator: truncate
  toolkits:
    - name: developer

development:
  extends: default
  toolkits:
    - name: developer
    - name: github
    - name: docker
      requires:
        DOCKER_HOST: "unix:///var/run/docker.sock"

staging:
  extends: default
  toolkits:
    - name: developer
    - name: github
    - name: kubernetes
      requires:
        KUBE_CONFIG: staging-config

production:
  extends: default
  toolkits:
    - name: developer
    - name: github  
    - name: kubernetes
      requires:
        KUBE_CONFIG: production-config
  # More restrictive settings for production
  moderator: conservative
Enter fullscreen mode Exit fullscreen mode

Syncing Configurations Across Projects

Automated Sync Script 

#!/bin/bash
# scripts/sync-goose-configs.sh
# Sync base configuration across all projects

CONFIG_REPO="git@github.com:your-org/goose-configs.git"
TEMP_DIR=$(mktemp -d)

# Clone config repository
git clone "$CONFIG_REPO" "$TEMP_DIR"

# Find all projects with goose configs
find ~/projects -name ".goose" -type d | while read goose_dir; do
    project_dir=$(dirname "$goose_dir")
    project_name=$(basename "$project_dir")

    echo "Syncing config for $project_name..."

    # Backup existing config
    cp "$goose_dir/profiles.yaml" "$goose_dir/profiles.yaml.bak"

    # Merge base config with project-specific settings
    python3 "$TEMP_DIR/scripts/merge-configs.py" \
        "$TEMP_DIR/templates/base/profiles.yaml" \
        "$goose_dir/profiles.yaml" \
        > "$goose_dir/profiles.yaml.new"

    # Replace if merge successful
    if [ $? -eq 0 ]; then
        mv "$goose_dir/profiles.yaml.new" "$goose_dir/profiles.yaml"
        echo "✓ Updated $project_name"
    else
        echo "✗ Failed to update $project_name"
        rm "$goose_dir/profiles.yaml.new"
    fi
done

# Cleanup
rm -rf "$TEMP_DIR"
Enter fullscreen mode Exit fullscreen mode

Best Practices for Multi-Project Management

1. Document Your Configuration Strategy

Create a clear README in your configuration repository:

# goose Configuration Standards

## Configuration Hierarchy

1. **Global base** (~/.config/goose/profiles.yaml)
2. **Project-specific** (.goose/profiles.yaml) - Committed to git
3. **Personal overrides** (.goose/profiles.local.yaml) - Gitignored

## Project Types and Templates

- **web-app**: Frontend applications (React, Vue, Angular)
- **api-service**: Backend APIs and microservices
- **data-pipeline**: ETL and data processing projects
- **infrastructure**: Terraform, Kubernetes configurations

## Adding a New Project

`./scripts/init-project.sh <project-type>`


## Updating Configurations

Run monthly to sync base configurations:

`./scripts/sync-goose-configs.sh`
Enter fullscreen mode Exit fullscreen mode

2. Version Control Strategy

DO commit to git:

.goose/profiles.yaml (project configuration)
.goose/toolkit-configs/ (shared toolkit settings)
Documentation about configuration choices

DO NOT commit to git:

.goose/profiles.local.yaml (personal overrides)
.goose/sessions/ (session history)
API keys or secrets

Add to .gitignore:

# Goose personal configurations and sessions
.goose/profiles.local.yaml
.goose/sessions/
.goose/**/*.log
Enter fullscreen mode Exit fullscreen mode

3. Toolkit Management Across Projects

Standardize commonly used toolkits:

# Standard toolkit configurations
default:
  toolkits:
    # Core toolkits - always included
    - name: developer

    # Version control - most projects
    - name: github
      requires:
        GITHUB_TOKEN: github-token

    # Project-specific toolkits added per project
    # Examples: docker, kubernetes, database, etc.
Enter fullscreen mode Exit fullscreen mode

4. Environment Variable Management

Use a consistent approach for environment variables across projects:
Option A: .env files (per project)

# .env.goose (gitignored)
GOOSE_PROVIDER=openai
OPENAI_API_KEY=sk-...
GITHUB_TOKEN=ghp_...
Enter fullscreen mode Exit fullscreen mode

Option B: Shared secrets manager

# Use tools like 1Password, AWS Secrets Manager, or HashiCorp Vault
export OPENAI_API_KEY=$(op read "op://Development/Goose/OPENAI_API_KEY")
Enter fullscreen mode Exit fullscreen mode

5. Testing Configuration Changes

Before rolling out configuration changes, test in a sandbox:

# Test configuration in a sandbox project
mkdir -p /tmp/goose-config-test
cd /tmp/goose-config-test
cp -r ~/goose-configs/templates/base/.goose .
goose session start --profile default

# Verify configuration loaded correctly
# Test key workflows
# Check for errors or warnings

## Advanced Patterns

### Pattern 1: Monorepo Configuration

For monorepos with multiple sub-projects:

monorepo/
├── .goose/
│   └── profiles.yaml          # Root configuration
├── packages/
│   ├── frontend/
│   │   └── .goose/
│   │       └── profiles.yaml  # Frontend-specific
│   ├── backend/
│   │   └── .goose/
│   │       └── profiles.yaml  # Backend-specific
│   └── shared/
│       └── .goose/
│           └── profiles.yaml  # Shared library config
Enter fullscreen mode Exit fullscreen mode

Pattern 2: Dynamic Profile Selection

Use shell aliases to quickly switch contexts:

# ~/.bashrc or ~/.zshrc
alias goose-fe='cd ~/projects/myapp/frontend && goose session start --profile frontend'
alias goose-be='cd ~/projects/myapp/backend && goose session start --profile backend'
alias goose-infra='cd ~/projects/myapp/infra && goose session start --profile infrastructure'
Enter fullscreen mode Exit fullscreen mode

Pattern 3: Configuration Inheritance Chain 

# Complex inheritance for specialized needs
base:
  provider: openai
  processor: gpt-4

python-base:
  extends: base
  toolkits:
    - name: developer
    - name: python

django-app:
  extends: python-base
  toolkits:
    - name: database
    - name: docker

ml-pipeline:
  extends: python-base
  toolkits:
    - name: jupyter
    - name: data-science
Enter fullscreen mode Exit fullscreen mode

Monitoring and Maintenance

Configuration Drift Detection

Create a script to identify configuration drift:

# scripts/detect-config-drift.py
import yaml
import os
from pathlib import Path

def compare_configs(base_config, project_config):
    """Compare project config against base and report differences"""
    differences = []

    # Compare provider settings
    if project_config.get('provider') != base_config.get('provider'):
        differences.append(
            f"Provider mismatch: {project_config.get('provider')} vs {base_config.get('provider')}"
        )

    # Add more comparison logic
    return differences

# Scan all projects
projects_dir = Path.home() / 'projects'
for goose_config in projects_dir.glob('**/.goose/profiles.yaml'):
    # Load and compare...
    pass
Enter fullscreen mode Exit fullscreen mode

Regular Maintenance Schedule

Establish a maintenance routine:

  • Weekly: Review new toolkit releases and compatibility
  • Monthly: Audit configurations across projects for drift
  • Quarterly: Update base templates and roll out to projects
  • Annually: Review and refactor configuration strategy

Troubleshooting Common Issues

Issue 1: Configuration Not Loading

Problem: Goose not picking up project configuration
Solution: Check configuration precedence

# Debug which config is being used
goose config show --verbose

# Verify file exists and is valid YAML
cat .goose/profiles.yaml | python -m yaml
Enter fullscreen mode Exit fullscreen mode

Issue 2: Toolkit Conflicts

Problem: Toolkits behaving differently across projects
Solution: Standardize toolkit versions and dependencies

default:
  toolkits:
    - name: developer
      version: "1.0.0"  # Pin versions when possible
Enter fullscreen mode Exit fullscreen mode

Issue 3: Environment Variable Confusion

Problem: Different projects expecting different environment variables
Solution: Use project-specific .env files and document clearly

# Add to project README
## Required Environment Variables
- GOOSE_PROVIDER: OpenAI or Anthropic
- OPENAI_API_KEY: Your OpenAI API key
- GITHUB_TOKEN: GitHub personal access token
Enter fullscreen mode Exit fullscreen mode

Conclusion

Managing goose configurations across multiple projects requires a thoughtful strategy that balances consistency with flexibility. By implementing a configuration hierarchy, using templates, automating synchronization, and following best practices, you can scale goose across your organization without sacrificing maintainability.

Key takeaways

  • Establish a clear hierarchy: Global base → Project-specific → Personal overrides
  • Use configuration templates: Create reusable templates for common project types
  • Automate where possible: Scripts for initialization, validation, and synchronization
  • Version control strategically: Commit shared configs, ignore personal overrides
  • Document thoroughly: Make it easy for team members to understand and follow standards
  • Monitor for drift: Regularly audit configurations to maintain consistency.

As your team grows and adopts goose more widely, these strategies will help you maintain a scalable, consistent configuration management approach that empowers developers rather than constrains them.

Do you have questions about managing Goose across your projects? Drop a comment below

Top comments (0)