goose

Goose implements a canonical model registry that normalizes API differences across 20+ LLM providers (OpenAI, Anthropic, Ollama, local models, etc.) through a declarative provider layer. The registry maps provider-specific model names to canonical identifiers and handles wire protocol translation, allowing seamless provider switching without code changes. Built on Rust's type system with compile-time provider validation and runtime fallback chains.

Goose implements a full MCP (Model Context Protocol) client and transport layer that discovers, connects to, and orchestrates external MCP servers as extensions. The system handles stdio/HTTP transport, schema validation, and capability negotiation. Built-in MCP extensions (goose-mcp crate) provide file operations, shell execution, and system tools; external servers can be registered via configuration. Includes security permission system with allowlisting for dangerous operations.

Goose supports spawning subagents to parallelize task execution or create hierarchical agent structures. Parent agents can delegate subtasks to subagents, collect results, and coordinate overall workflow. Subagents run in isolated contexts with their own sessions and tool access. The system supports both synchronous coordination (wait for all subagents) and asynchronous coordination (collect results as they arrive). Subagent communication uses message passing through the session store.

Goose implements a security permission system that allowlists dangerous operations (shell execution, file deletion, network access) and logs all agent actions for audit trails. The system uses a declarative allowlist (ALLOWLIST.md) that specifies which operations are permitted and under what conditions. All agent actions are logged with timestamps, user context, and results. The system supports role-based access control (RBAC) for multi-user deployments.

Goose includes an Open Model Gym benchmarking framework for evaluating agent performance across different LLM models and configurations. The framework defines standardized tasks (coding challenges, refactoring, debugging) with expected outputs, runs agents against these tasks, and measures success rates, latency, and cost. Results are aggregated and compared across models, enabling data-driven model selection. Benchmarks are extensible — users can add custom tasks.

Goose uses a declarative configuration system (YAML-based) for specifying agent behavior, tool access, LLM provider settings, and security policies. Configuration supports environment variable substitution, allowing sensitive values (API keys) to be injected at runtime. The system supports multiple configuration profiles (development, staging, production) and validates configuration at startup. Configuration can be loaded from files, environment variables, or programmatically.

Goose provides native shell execution capabilities through MCP-based tool servers that understand the current working directory, environment variables, and project context. The agent can execute arbitrary shell commands, capture output, and parse results. Built-in tools include file operations (read/write/delete), directory traversal, and command execution with environment isolation. Execution context is tracked across agent steps, enabling stateful workflows (e.g., install dependencies, then run tests).

Goose implements a planning-reasoning loop where the agent decomposes user requests into subtasks, selects appropriate tools (MCP servers), executes them, observes results, and iterates. The loop uses chain-of-thought reasoning to decide when to use tools vs. when to ask for clarification. Built on a state machine that tracks agent state (thinking, tool-calling, waiting for user input) and manages context across iterations. Supports both synchronous execution (wait for tool result before next step) and asynchronous workflows (schedule tasks, return to user).

Goose provides a recipe system where developers define multi-step workflows as YAML configurations that specify task sequences, tool invocations, and conditional logic. Recipes can be scheduled to run on a cron-like schedule or triggered by events. The system supports subagents (spawning child agents for parallel or hierarchical task execution) and recipe composition (recipes calling other recipes). Execution is tracked in a session store with full history and rollback capability.

Goose implements context management that tracks token usage across agent iterations and automatically compacts context when approaching token limits. The system uses summarization, relevance filtering, and history pruning to reduce context size while preserving critical information. Context compaction is transparent to the agent — it observes the same interface but with optimized context. Supports both automatic compaction (triggered by token threshold) and manual compaction (user-initiated).

Goose exposes a REST API (goose-server crate) that allows external clients to invoke agents, manage sessions, and query execution history. The API is automatically documented via OpenAPI 3.0 schema, with TypeScript SDK generation for type-safe client integration. Endpoints support both synchronous (wait for result) and asynchronous (poll for status) execution patterns. Authentication uses OIDC for enterprise deployments.

Goose provides a desktop application (Electron-based UI, with Tauri rewrite in progress) that offers a chat interface for interacting with agents, session management, and settings configuration. The UI supports voice dictation for hands-free task specification and real-time rendering of agent reasoning and tool execution. Desktop app communicates with goose-server via REST API, allowing local or remote agent execution.

Goose provides a command-line interface (goose-cli crate) with an interactive REPL for real-time agent interaction, session management (save/load/resume), and command execution. The CLI supports both interactive mode (chat-like interaction) and batch mode (execute recipe or single task). Sessions are persisted to disk with full execution history, allowing users to resume interrupted tasks or audit past executions.

Goose integrates file operations (read, write, delete, list) as MCP tools with awareness of project structure, language-specific conventions, and code semantics. The agent can understand directory hierarchies, identify configuration files, and infer project type (Python, Node.js, Rust, etc.). File operations preserve formatting and indentation, and support atomic writes to prevent corruption. Built-in tools include file search, diff generation, and syntax-aware editing.