Typical Directory Structure of a Goose Project: A Complete Guide

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 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, the high-level structure follows this pattern:

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. 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, 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, 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.

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.

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, 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 — Main Agent struct that runs the planning loop
• crates/goose-cli/src/main.rs — CLI entry point, argument parsing, and recipe handling
• crates/goose-server/src/main.rs — Server startup, routing, and API exposure
• crates/goose-mcp/src/lib.rs — Core MCP server implementation and extension loading
• ui/desktop/src/main.ts — Electron main process and IPC wiring
• Cargo.toml — Workspace definition listing all member crates
• README.md — High-level overview and getting-started instructions

To visualize the layout from the command line:

tree -L 2

This yields the concise directory tree:

.
├── 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, server at goose-server/src/main.rs, and desktop UI at 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. 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. 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. The Electron desktop UI lives in ui/desktop/, with the main process defined in 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, supporting features like code execution, filesystem access, and cloud API integrations.

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