Managing Goose Configurations Across Multiple Projects: A Practical Guide

Viet Bui — Fri, 31 Oct 2025 06:49:01 +0000

Managing goose Configurations Across Multiple Projects: A Practical Guide

goose #hacktoberfest #devops #productivity

Introduction

Working with goose across multiple projects comes with challenges. One major issue is the time and effort it takes for teams to set up configurations: "Wait, what provider did we use for this React app? Which LLM model for the Django server? Did you turn off auto-execute for this SECRET project?"

Without a systematic structure, teams constantly ask these questions and fix inconsistencies. Fortunately, goose provides several tools to help manage configurations more effectively.

Understanding goose Configuration

goose stores its global configuration in ~/.config/goose/config.yaml and uses your system's keyring for sensitive information like API keys. You can set up your configuration interactively:

goose configure

This command walks you through provider setup, model selection, and extension configuration.

Environment Variable Overrides

goose respects environment variables, allowing you to override settings per project or session:

export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="gpt-4o"
export GOOSE_MODE="auto"
goose session

Common environment variables include:

GOOSE_PROVIDER - LLM provider selection
GOOSE_MODEL - Model selection
GOOSE_MODE - Operation mode
OPENAI_API_KEY - OpenAI API key
ANTHROPIC_API_KEY - Anthropic API key

Project-Specific Configuration Strategies

1. Environment Files

Create project-specific environment files to standardize settings:

# project-a/.env.goose
export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="gpt-4o-mini"
export GOOSE_MODE="auto"

# Usage
cd project-a
source .env.goose
goose session --name "project-a-work"

2. Wrapper Scripts

Create scripts that set up the environment and launch goose:

#!/bin/bash
# scripts/goose-frontend.sh
export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="gpt-4o"
cd /path/to/frontend-project
goose session --name "frontend-work" "$@"

3. Session Management

goose includes built-in session management that helps organize work by project:

# Create named sessions for different projects
goose session --name "frontend-auth-feature"
goose session --name "backend-api-refactor"

# Resume previous sessions
goose session --name "frontend-auth-feature" --resume

Project Tracking Features

goose automatically tracks your project directories:

# Resume your most recent project
goose project

# Browse and select from recent projects
goose projects

This makes it easy to switch between different codebases while maintaining separate contexts.

Configuration Validation Script

Here's a simple script to check your goose environment setup:

#!/bin/bash
# validate-goose-setup.sh
echo "🔍 Checking goose setup..."

# Check if goose is available
if ! command -v goose &> /dev/null; then
    echo "❌ goose command not found"
    exit 1
fi

echo "✅ goose is installed"

# Check environment variables
ENV_VARS=("GOOSE_PROVIDER" "GOOSE_MODEL")
for var in "${ENV_VARS[@]}"; do
    if [ -n "${!var}" ]; then
        echo "✅ $var = ${!var}"
    else
        echo "ℹ️  $var not set (using global config)"
    fi
done

# Check for API keys
API_KEYS=("OPENAI_API_KEY" "ANTHROPIC_API_KEY")
for key in "${API_KEYS[@]}"; do
    if [ -n "${!key}" ]; then
        echo "✅ $key is configured"
    fi
done

echo "✅ Setup check complete"

Team Configuration Strategies

Small Teams

Share environment file templates in your repositories
Document required environment variables in README files
Use consistent naming for session names across the team

Medium Teams

Create a shared repository of configuration scripts
Standardize on provider and model choices for consistency
Document configuration decisions and rationale

Large Organizations

Establish configuration standards and templates
Create onboarding documentation for goose setup
Consider centralized script distribution for common configurations

Troubleshooting Common Issues

Configuration Not Working

# Check current configuration
goose info
goose info --verbose

# Reconfigure if needed
goose configure

Environment Variables Not Taking Effect

# Verify variables are set
env | grep GOOSE
env | grep API_KEY

# Make sure to export variables
export GOOSE_PROVIDER="openai"  # Not just GOOSE_PROVIDER="openai"

Session Management Issues

# List available sessions to see what exists
goose session list

# Check project tracking
goose projects

Best Practices

Security

Store API keys in environment variables, not in code
Use goose's keyring integration via goose configure
Add environment files to .gitignore

Organization

Use descriptive session names that include project and feature context
Keep environment files in project roots for easy access
Document your configuration choices in project README files

Team Coordination

Establish team standards for provider and model selection
Share configuration templates and scripts
Document any project-specific requirements or constraints

Real-World Example

Here's how you might organize configurations for a multi-project setup:

my-projects/
├── frontend-app/
│   ├── .env.goose
│   └── README.md
├── backend-api/
│   ├── .env.goose  
│   └── README.md
└── scripts/
    ├── goose-frontend.sh
    ├── goose-backend.sh
    └── validate-setup.sh

Each .env.goose file contains project-appropriate settings, and the scripts provide convenient ways to launch goose with the right configuration.

Conclusion

Managing goose configurations across projects becomes much easier when you leverage environment variables, session management, and goose's built-in project tracking. Start with simple environment files and wrapper scripts, then build more sophisticated tooling as your team's needs grow.

Key Takeaways:

Use goose configure for global setup
Override settings with environment variables per project
Leverage session names and project tracking for organization
Create simple scripts and templates to reduce setup friction
Document your configuration decisions for team consistency

The goal is to reduce the cognitive overhead of switching between projects while maintaining the flexibility to use different providers, models, and settings as needed.

Resources

block / goose

an open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM

goose

a local, extensible, open source AI agent that automates engineering tasks

goose is your on-machine AI agent, capable of automating complex development tasks from start to finish. More than just code suggestions, goose can build entire projects from scratch, write and execute code, debug failures, orchestrate workflows, and interact with external APIs - autonomously.

Whether you're prototyping an idea, refining existing code, or managing intricate engineering pipelines, goose adapts to your workflow and executes tasks with precision.

Designed for maximum flexibility, goose works with any LLM and supports multi-model configuration to optimize performance and cost, seamlessly integrates with MCP servers, and is available as both a desktop app as well as CLI - making it the ultimate AI assistant for developers who want to move faster and focus on innovation.

Quick Links

Quickstart
Installation
Tutorials
Documentation
Governance
Custom Distributions - build your own goose distro with preconfigured providers…

View on GitHub

Created for Goose Hacktoberfest 2025. Submit improvements!

✅ This guide has been verified with Goose v1.12.0 to ensure all commands and configurations work correctly.

What configuration challenges have you faced with Goose? Share below! 👇

goose #hacktoberfest #devops #automation #opensource

DEV Community: Viet Bui