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

> Explore the main modules and packages in the aaif-goose/goose repository. Understand the architecture of key crates like goose, goose-cli, and goose-server for agent scheduling and LLM management.

- Repository: [goose/goose](https://github.com/aaif-goose/goose)
- Tags: architecture
- Published: 2026-04-07

---

**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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`:

```rust
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`](https://github.com/aaif-goose/goose/blob/main/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:

```rust
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`](https://github.com/aaif-goose/goose/blob/main/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:

```rust
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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/lib.rs) – Public module re-exports for the core agent engine.
- [`crates/goose-cli/src/lib.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose-cli/src/lib.rs) – CLI façade and argument parsing logic.
- [`crates/goose-server/src/state.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose-server/src/state.rs) – Core server state machine handling MCP connections.
- [`crates/goose-sdk/src/lib.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose-sdk/src/lib.rs) – High-level SDK API for application embedding.
- [`crates/goose-acp/src/lib.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose-acp/src/lib.rs) – ACP request/response schemas and transport adapters.
- [`crates/goose-mcp/src/lib.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose-mcp/src/lib.rs) – MCP utilities for registering extensions.
- [`crates/goose/src/providers/mod.rs`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/providers/mod.rs), allowing seamless swapping of backend language models.