Codebase Architecture

​

Project Structure

goose/
├── crates/              # Rust workspace
│   ├── goose            # Core logic
│   ├── goose-acp        # Agent Client Protocol
│   ├── goose-acp-macros # ACP procedural macros
│   ├── goose-cli        # CLI entry point
│   ├── goose-server     # Backend (binary: goosed)
│   ├── goose-mcp        # MCP extensions
│   ├── goose-test       # Test utilities
│   └── goose-test-support # Test helpers
├── ui/
│   └── desktop/         # Electron app
├── evals/
│   └── open-model-gym/  # Benchmarking & evals
├── examples/            # Example extensions
└── documentation/       # Docusaurus site

​

Core Crates

​

goose

• agents/ - Agent implementations and lifecycle management
  • agent.rs - Main agent loop
  • extension.rs - Extension configuration
  • extension_manager.rs - Extension lifecycle
• providers/ - LLM provider integrations
  • base.rs - Provider trait definition
  • anthropic.rs, openai.rs, etc. - Specific providers
  • declarative/ - JSON-based provider configs
  • canonical/ - Model capability registry
• conversation/ - Message handling
  • message.rs - Message types
  • Conversation state management
• config/ - Configuration management
  • Provider configs
  • Extension configs
  • Path management

​

goose-cli

• session - Start interactive session
• configure - Configure providers
• run - Execute recipes
• version - Version info

​

goose-server

• REST API for agent management
• WebSocket for streaming responses
• Session management
• OpenAPI schema generation

​

goose-mcp

• autovisualiser - Automatic visualization generation
• computercontroller - Desktop automation
• memory - Long-term memory storage
• tutorial - Interactive tutorials

​

goose-acp

​

Key Architectural Patterns

​

Provider Trait

#[async_trait]
pub trait Provider: Send + Sync {
    fn get_name(&self) -> &str;
    
    async fn stream(
        &self,
        model_config: &ModelConfig,
        session_id: &str,
        system: &str,
        messages: &[Message],
        tools: &[Tool],
    ) -> Result<MessageStream, ProviderError>;
    
    fn get_model_config(&self) -> ModelConfig;
    // ... more methods
}

• stream() - Primary method for streaming responses
• complete() - Non-streaming completion
• generate_session_name() - Create session titles
• configure_oauth() - OAuth authentication

​

Extension System

• Tools - Functions the agent can call
• Resources - Data sources
• Prompts - Reusable prompt templates

​

Message Flow

User Input
  ↓
Agent (goose/agents/agent.rs)
  ↓
Provider (streaming)
  ↓
Tool Calls → Extension Manager
  ↓
MCP Extensions
  ↓
Tool Results → Agent
  ↓
Provider (next turn)
  ↓
Response

​

Declarative Providers

{
  "name": "groq",
  "engine": "openai",
  "display_name": "Groq (d)",
  "description": "Fast inference with Groq hardware",
  "api_key_env": "GROQ_API_KEY",
  "base_url": "https://api.groq.com/openai/v1/chat/completions",
  "models": [
    {
      "name": "llama-3.3-70b-versatile",
      "context_limit": 131072,
      "max_tokens": 32768
    }
  ],
  "supports_streaming": true
}

​

Entry Points

• CLI: crates/goose-cli/src/main.rs
• Server: crates/goose-server/src/main.rs
• UI: ui/desktop/src/main.ts
• Agent: crates/goose/src/agents/agent.rs

​

Configuration Paths

• Linux: ~/.config/goose/
• macOS: ~/Library/Application Support/goose/
• Windows: %APPDATA%\goose\

config/
  └── providers/       # Provider configurations
data/
  └── sessions/        # Session history
state/                 # Runtime state

​

Testing Architecture

• Unit tests - Within crate files
• Integration tests - crates/*/tests/ directories
• MCP tests - crates/goose/tests/mcp_integration_test.rs
• Test utilities - goose-test and goose-test-support crates

​

Build System

• Cargo - Rust build system and package manager
• Just - Task runner for common commands (see Justfile)
• npm - UI dependencies and scripts
• Hermit - Development environment manager

​

Design Principles

1. Simplicity - Trust Rust’s type system, avoid defensive code
2. Composability - Small, focused components
3. Extensibility - MCP-based extension system
4. Provider agnostic - Works with any LLM
5. Local-first - Runs entirely on your machine

​

Common Code Patterns

​

Error Handling

use anyhow::Result;

fn do_something() -> Result<()> {
    // ...
    Ok(())
}

​

Async Code

use async_trait::async_trait;

#[async_trait]
trait MyTrait {
    async fn process(&self) -> Result<()>;
}

​

Streaming

type MessageStream = Pin<Box<dyn Stream<Item = Result<
    (Option<Message>, Option<ProviderUsage>),
    ProviderError
>> + Send>>;

​

Next Steps

• Learn about Testing
• Build Extensions
• Create Providers
• Understand Tool Creation