Development Setup

Set up your development environment for contributing to Goose

This guide walks you through setting up a local development environment for Goose.

Prerequisites

Goose includes Rust binaries alongside an Electron app for the GUI.

Hermit

We use Hermit to manage development dependencies (Rust, Node, npm, just, etc.).

Activate Hermit when entering the project:

source bin/activate-hermit

Or add shell hook auto-activation so Hermit activates automatically when you cd into the project (recommended).

WSL Users (Windows)

For WSL users, install additional dependencies:

sudo apt update
sudo apt install build-essential  # Core build tools
sudo apt install libxcb1-dev       # X C Binding library

Building the Rust CLI

First Build

cd goose
source ./bin/activate-hermit
cargo build

Debug builds are available in ./target/debug/:

./target/debug/goose --help

First-Time Configuration

Configure a provider connection:

./target/debug/goose configure

Start a session:

./target/debug/goose session

Development Commands

# Verify changes compile
cargo check

# Run tests
cargo test
cargo test -p goose          # specific crate

# Format code
cargo fmt

# Run linter
cargo clippy --all-targets -- -D warnings

# Quick iteration
cargo run -p goose-cli -- session

Building the Desktop UI

Running the UI

just run-ui

This command:

1. Builds a release build of Rust (cargo build -r)
2. Starts the Electron process
3. Opens a window for first-time setup

Make GUI changes in ui/desktop.

UI-Only Development

If you’re only working on the UI and don’t need to rebuild Rust:

just run-ui-only

Debug Build UI

Run the UI with debug Rust binaries (faster compilation):

just run-dev

UI Testing

cd ui/desktop
npm test

Working with the Server

Debugging the Server

To debug the Goose server, run it from an IDE with:

export GOOSE_SERVER__SECRET_KEY=test
cargo run --package goose-server --bin goosed -- agent
# OR
just run-server

The server listens on port 3000 by default. Change with GOOSE_PORT environment variable.

Connect the UI to your running server:

just debug-ui

This allows breakpoints and stepping through server code while interacting with the UI.

Regenerating OpenAPI Schema

The file ui/desktop/openapi.json is automatically generated. After making server API changes:

just generate-openapi

This regenerates openapi.json and rebuilds the TypeScript client.

Never edit ui/desktop/openapi.json manually. Make changes in crates/goose-server/src/.

Environment Variables

Provider Configuration

Change provider without reconfiguring:

export GOOSE_PROVIDER=openai
# With API key
export OPENAI_API_KEY=sk-...

Supported provider env vars:

• ANTHROPIC_API_KEY
• OPENAI_API_KEY
• DATABRICKS_HOST
• GOOGLE_API_KEY
• etc.

Isolating Test Environments

Use GOOSE_PATH_ROOT to isolate test data:

# Test with clean environment
export GOOSE_PATH_ROOT="/tmp/goose-test"
./target/debug/goose session

# Or for a single command
GOOSE_PATH_ROOT="/tmp/goose-dev" cargo run -p goose-cli -- session

This creates isolated config/, data/, and state/ directories, preventing test sessions from affecting your main installation.

Development Loop

Typical workflow when making changes:

# 1. Activate hermit (if not auto-activated)
source bin/activate-hermit

# 2. Make your changes

# 3. Format code
cargo fmt

# 4. Build
cargo build

# 5. Test
cargo test -p <crate>

# 6. Lint
cargo clippy --all-targets -- -D warnings

# 7. If server changes, regenerate OpenAPI
just generate-openapi

Useful Just Commands

We use just as a command runner. See all available commands:

just --list

Commonly used commands:

just release-binary       # Release build + OpenAPI
just run-ui               # Build and run UI
just run-server           # Run server
just generate-openapi     # Regenerate OpenAPI schema
just check-everything     # Run all style checks

Enabling Traces with Langfuse

For local tracing:

1. Start local Langfuse
2. Create organization, project, and API credentials
3. Set environment variables:

export LANGFUSE_INIT_PROJECT_PUBLIC_KEY=publickey-local
export LANGFUSE_INIT_PROJECT_SECRET_KEY=secretkey-local

4. View traces at http://localhost:3000

Next Steps

• Learn about Architecture
• Understand Testing
• Build Extensions
• Create Providers