# Typical Directory Structure of a Goose Project: A Complete Guide > Explore the typical Goose project directory structure in the aaif-goose/goose repository. Understand its layered architecture, separating core logic, evaluations, and UI for efficient development. - Repository: [goose/goose](https://github.com/aaif-goose/goose) - Tags: how-to-guide - Published: 2026-04-07 --- **A standard Goose repository organizes code into a Rust workspace under `crates/`, with separate directories for evaluations (`evals/`) and the desktop UI (`ui/`), following a layered architecture that separates core agent logic, protocol implementations, CLI, server, and MCP extensions.** The typical directory structure of a Goose project follows a modular, layered architecture designed to separate concerns across agent runtime, protocol bindings, and user interfaces. As defined in the repository's [`AGENTS.md`](https://github.com/aaif-goose/goose/blob/main/AGENTS.md) file, the `aaif-goose/goose` codebase uses a Cargo workspace configuration that divides functionality into distinct crates, evaluation suites, and frontend components. ## Overview of the Repository Layout The repository root contains three primary directories that organize the codebase by function. According to the source tree listed in [`AGENTS.md`](https://github.com/aaif-goose/goose/blob/main/AGENTS.md), the high-level structure follows this pattern: ```text crates/ ├── goose ├── goose-acp ├── goose-acp-macros ├── goose-cli ├── goose-server ├── goose-mcp ├── goose-test └── goose-test-support evals/open-model-gym/ ui/desktop/ ``` This layout separates core Rust functionality from benchmarking infrastructure and the Electron-based user interface. ## The `crates/` Directory: Core Rust Workspace The `crates/` directory functions as a Cargo workspace defined in the root [`Cargo.toml`](https://github.com/aaif-goose/goose/blob/main/Cargo.toml). This structure enables independent versioning and compilation of each component while maintaining internal dependencies across the typical directory structure of a Goose project. ### `goose/` — Core Agent Engine The foundational crate contains the main `Agent` struct that runs the planning loop. Located at [`crates/goose/src/agents/agent.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/agents/agent.rs), this crate orchestrates plans, tool calls, and memory management for the autonomous agent runtime. ### `goose-acp/` — Agent Client Protocol Implements the Agent Client Protocol (ACP), exposing a standardized API for external clients. This crate defines the communication layer between the agent core and consuming applications. ### `goose-acp-macros/` — Procedural Macros Contains procedural macros that generate boilerplate code for ACP types, reducing repetitive implementations across the protocol layer. ### `goose-cli/` — Command-Line Interface Provides the CLI binary (`goose`) that parses commands, loads recipes, and drives the agent. The entry point resides in [`crates/goose-cli/src/main.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose-cli/src/main.rs), handling argument parsing and recipe initialization. ### `goose-server/` — Backend Server Contains the backend HTTP server (`goosed`) that exposes the agent over HTTP and WebSocket protocols. The server startup and routing logic is defined in [`crates/goose-server/src/main.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose-server/src/main.rs). ### `goose-mcp/` — Model Context Protocol Extensions Implements MCP server extensions including code execution, filesystem access, and cloud API integrations. The core implementation resides in [`crates/goose-mcp/src/lib.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose-mcp/src/lib.rs). ### `goose-test/` and `goose-test-support/` — Testing Infrastructure Shared test utilities, fixtures, and mock providers used across the workspace for integration testing and quality assurance. ## Supporting Infrastructure ### `evals/open-model-gym/` — Evaluation Suites Contains scripts and datasets for benchmarking Goose performance on open-model-gym evaluations. This directory houses the testing infrastructure for measuring agent capabilities against standardized tasks. ### `ui/desktop/` — Electron Frontend The desktop application built with Electron, React, and TypeScript. The main process entry point is located at [`ui/desktop/src/main.ts`](https://github.com/aaif-goose/goose/blob/main/ui/desktop/src/main.ts), handling window creation and IPC wiring between the UI and the underlying Rust backend. ## Key Source Files and Entry Points Understanding the codebase requires familiarity with these critical files: - **[`crates/goose/src/agents/agent.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/agents/agent.rs)** — Main `Agent` struct that runs the planning loop - **[`crates/goose-cli/src/main.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose-cli/src/main.rs)** — CLI entry point, argument parsing, and recipe handling - **[`crates/goose-server/src/main.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose-server/src/main.rs)** — Server startup, routing, and API exposure - **[`crates/goose-mcp/src/lib.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose-mcp/src/lib.rs)** — Core MCP server implementation and extension loading - **[`ui/desktop/src/main.ts`](https://github.com/aaif-goose/goose/blob/main/ui/desktop/src/main.ts)** — Electron main process and IPC wiring - **[`Cargo.toml`](https://github.com/aaif-goose/goose/blob/main/Cargo.toml)** — Workspace definition listing all member crates - **[`README.md`](https://github.com/aaif-goose/goose/blob/main/README.md)** — High-level overview and getting-started instructions To visualize the layout from the command line: ```bash tree -L 2 ``` This yields the concise directory tree: ```text . ├── crates │ ├── goose │ ├── goose-acp │ ├── goose-acp-macros │ ├── goose-cli │ ├── goose-server │ ├── goose-mcp │ ├── goose-test │ └── goose-test-support ├── evals │ └── open-model-gym └── ui └── desktop ``` ## Summary - The typical directory structure of a Goose project centers on a Rust workspace in `crates/` containing eight functional crates - **Core logic** resides in `crates/goose/` while **protocol implementations** split between `goose-acp/` and `goose-mcp/` - **Entry points** are clearly separated: CLI at [`goose-cli/src/main.rs`](https://github.com/aaif-goose/goose/blob/main/goose-cli/src/main.rs), server at [`goose-server/src/main.rs`](https://github.com/aaif-goose/goose/blob/main/goose-server/src/main.rs), and desktop UI at [`ui/desktop/src/main.ts`](https://github.com/aaif-goose/goose/blob/main/ui/desktop/src/main.ts) - **Testing infrastructure** spans dedicated `goose-test/` crates and the `evals/open-model-gym/` benchmarking directory - The architecture follows a layered pattern separating agent runtime, protocol bindings, interfaces, and extensions ## Frequently Asked Questions ### What is the main entry point for the Goose CLI? The CLI entry point is located at [`crates/goose-cli/src/main.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose-cli/src/main.rs). This file handles argument parsing, recipe loading, and initializes the agent runtime. The compiled binary is named `goose` according to the source code implementation. ### Where is the core agent logic implemented in a Goose project? The core agent logic lives in [`crates/goose/src/agents/agent.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose/src/agents/agent.rs). This file contains the main `Agent` struct that orchestrates the planning loop, tool execution, and memory management as implemented in the `aaif-goose/goose` repository. ### How are the Goose server and desktop UI organized? The backend HTTP server (`goosed`) resides in `crates/goose-server/` with its entry point at [`src/main.rs`](https://github.com/aaif-goose/goose/blob/main/src/main.rs). The Electron desktop UI lives in `ui/desktop/`, with the main process defined in [`src/main.ts`](https://github.com/aaif-goose/goose/blob/main/src/main.ts) handling window creation and IPC communication with the Rust backend. ### What crate handles the Model Context Protocol (MCP) in Goose? The `goose-mcp` crate in `crates/goose-mcp/` handles all MCP implementations. The core server logic and extension loading mechanisms are defined in [`src/lib.rs`](https://github.com/aaif-goose/goose/blob/main/src/lib.rs), supporting features like code execution, filesystem access, and cloud API integrations.