Main Modules and Packages in the Goose Repository: Complete Architecture Guide

The Goose repository is organized as a Cargo workspace containing nine primary crates—including goose, goose-cli, goose-server, goose-sdk, and goose-acp—with the core goose crate housing approximately 30 logical modules for agent scheduling, conversation management, and LLM provider abstraction.

Goose is an open-source AI agent framework written in Rust, distributed as a single Cargo workspace where each directory under crates/ represents a publishable package with a distinct architectural responsibility. Understanding the main modules and packages in the Goose repository is essential for developers looking to extend the agent engine, embed capabilities into third-party applications, or deploy it as a networked service.

Core Crates: The Nine Main Packages

The workspace root Cargo.toml defines the following nine crates that constitute the public API surface of the project:

• goose – The core agent engine located in crates/goose/src/lib.rs, responsible for scheduling, tool monitoring, conversation handling, and provider abstraction.
• goose-cli – Command-line interface in crates/goose-cli/src/lib.rs that drives interactive terminal sessions and parses arguments.
• goose-server – Backend HTTP/TLS server in crates/goose-server/src/state.rs exposing the agent via the Model Context Protocol (MCP) and RPC endpoints.
• goose-sdk – Public SDK for embedding Goose in other Rust programs via crates/goose-sdk/src/lib.rs, providing high-level helpers for creating Goose instances.
• goose-acp – Implementation of the Agent Client Protocol (ACP) in crates/goose-acp/src/lib.rs, handling the JSON-based wire format for tool calls and streaming responses.
• goose-acp-macros – Procedural macros in crates/goose-acp-macros/src/lib.rs that generate ACP-compatible request/response structs from schema definitions.
• goose-mcp – Helpers for the Model Context Protocol (MCP) in crates/goose-mcp/src/lib.rs, supporting extensions and tool-plugins.
• goose-test – Shared test utilities and fixtures used across the workspace.
• goose-test-support – Additional integration testing helpers including OTEL exporters and session mocks.

Internal Architecture of the Core Goose Crate

The goose crate itself is subdivided into approximately 30 logical modules declared in crates/goose/src/lib.rs. Each module resides in its own subdirectory under src/ and handles a specific domain of the agent’s functionality.

Key Internal Modules

• agents – Defines the Agent trait and built-in agent implementations.
• providers – LLM provider implementations for OpenAI, Anthropic, Amazon Bedrock, and others, located in crates/goose/src/providers/ with the trait defined in mod.rs.
• conversation – Manages chat history, message turns, and conversation state.
• execution – Executes tool calls, subprocesses, and async actions.
• scheduler and scheduler_trait – Implements cron-like job scheduling and repetition logic.
• context_mgmt – Handles long-term memory, embeddings, and vector store interactions.
• acp – Re-exports ACP client/server types for internal use.
• mcp_utils – Internal utilities for dealing with the Model Context Protocol.
• tracing – OpenTelemetry and Jaeger integration for distributed tracing.
• security – Secure storage of secrets using OS keyring and vault mechanisms.

Practical Integration Examples

Running Goose from the Command Line

To interact with Goose via the terminal, import the CLI crate and instantiate a CliSession:

use goose_cli::Cli;
use goose_cli::session::CliSession;

#[tokio::main]
async fn main() {
    // Parse command-line arguments (flags, recipe path, etc.)
    let cli = Cli::parse();

    // Create a top-level session that owns the agent runtime
    let mut session = CliSession::new(cli).await.expect("Failed to start session");

    // Run the interactive loop (or a single recipe)
    session.run().await.expect("Execution error");
}

Entry point: crates/goose-cli/src/lib.rs exports both Cli and CliSession structures.

Embedding Goose via the SDK

For programmatic usage in other Rust applications, use the SDK crate:

use goose_sdk::Goose;
use goose_sdk::config::GooseConfig;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Load a configuration file (or build one programmatically)
    let cfg = GooseConfig::load_from_path("goose.yaml").await?;

    // Build the agent
    let goose = Goose::new(cfg).await?;

    // Send a simple user message and await the assistant's reply
    let response = goose
        .chat("Write a short poem about spring.")
        .await?;

    println!("Assistant: {}", response.message());

    Ok(())
}

Entry point: crates/goose-sdk/src/lib.rs provides the Goose struct and configuration builders.

Implementing a Custom Provider

To add a custom LLM provider within the core crate, implement the Provider trait:

use goose::providers::{Provider, ProviderConfig};

pub struct MyProvider;

#[async_trait::async_trait]
impl Provider for MyProvider {
    async fn chat(&self, _msg: &str, _cfg: &ProviderConfig) -> anyhow::Result<String> {
        // Custom logic – e.g., call an internal model server
        Ok("Hello from MyProvider!".to_string())
    }
}

Relevant modules: crates/goose/src/providers/ contains the trait definition in mod.rs and all built-in implementations.

Key Entry Points and Source Files

When navigating the Goose codebase, these files serve as the primary entry points for each module:

• crates/goose/src/lib.rs – Public module re-exports for the core agent engine.
• crates/goose-cli/src/lib.rs – CLI façade and argument parsing logic.
• crates/goose-server/src/state.rs – Core server state machine handling MCP connections.
• crates/goose-sdk/src/lib.rs – High-level SDK API for application embedding.
• crates/goose-acp/src/lib.rs – ACP request/response schemas and transport adapters.
• crates/goose-mcp/src/lib.rs – MCP utilities for registering extensions.
• crates/goose/src/providers/mod.rs – Definition of the Provider trait.

Summary

• The Goose repository uses a Cargo workspace architecture with nine primary crates covering CLI, server, SDK, protocol, and testing concerns.
• The goose crate contains the bulk of the agent logic, organized into ~30 logical modules including providers, scheduling, conversation management, and security.
• Three main entry points exist for different use cases: goose-cli for terminal usage, goose-server for HTTP/MCP APIs, and goose-sdk for library embedding.
• ACP and MCP crates (goose-acp, goose-mcp) implement the wire protocols used for extension communication and tool standardization.

Frequently Asked Questions

What is the difference between goose-cli and goose-server?

goose-cli provides a terminal-based interactive interface for running agents locally, parsing command-line arguments, and managing interactive sessions. In contrast, goose-server exposes the agent as a backend HTTP/TLS service using the Model Context Protocol (MCP), designed for remote access and integration with other networked applications.

How do I embed Goose in my own Rust application?

Import the goose-sdk crate and use Goose::new() with a GooseConfig to instantiate an agent programmatically according to the crates/goose-sdk/src/lib.rs implementation. Once initialized, call methods like .chat() to send messages and receive responses from the configured LLM provider.

What is the ACP protocol in Goose?

The Agent Client Protocol (ACP) is a JSON-based wire format implemented in crates/goose-acp/src/lib.rs that standardizes tool calls, streaming responses, and session management between the Goose agent and its clients. The companion goose-acp-macros crate provides procedural macros to generate compatible request/response structs.

Where are the LLM provider implementations located?

Provider implementations for OpenAI, Anthropic, Amazon Bedrock, and others reside in the providers module within the core goose crate, specifically under crates/goose/src/providers/. Each provider implements the Provider trait defined in crates/goose/src/providers/mod.rs, allowing seamless swapping of backend language models.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}