Skip to content

Goose

What it is

Goose is an open-source, extensible AI agent designed to go beyond simple code suggestions. It is built to install, execute, edit, and test code autonomously or with human supervision, using any LLM that supports tool-calling. Hosted by the Agentic AI Foundation (AAIF), it serves as a robust platform for building and deploying specialized developer agents. As of early January 2027, it fully integrates the Model Context Protocol (MCP 3.1 / FastMCP 3.1) Task Protocol and is optimized for frontier reasoning models such as Claude 5.6, GPT-5.6, Gemini 4.0 Ultra, Gemma 4, DeepSeek-V4, and Qwen 3.6 VL.

What problem it solves

It bridges the gap between static code completion and full-loop agentic software engineering. Goose can manage its own environment, install dependencies, and run scripts to verify its work, reducing the manual "context switching" developers often face when integrating AI-generated code. It solves the "execution gap" by running the code it writes to ensure correctness (and automatically fixing errors via traceback loops) before presenting it to the user.

Where it fits in the stack

Automation & Orchestration / Agents. It is an agentic layer that sits on top of LLMs (like Claude 5.6, GPT-5.6, Gemini 4.0 Ultra, or local models) and interacts with the filesystem and shell. It is a direct open-source alternative to tools like Aider or OpenHands.

Typical use cases

  • Automated Bug Fixing: Providing an issue description and letting Goose find, fix, and verify the solution with unit tests.
  • Environment Setup: Asking Goose to "set up a new React project with Tailwind and Vitest" and letting it handle all shell commands, config, and tests.
  • Large-Scale Refactoring: Executing systematic code changes across hundreds of files with automated verification loops.
  • Agentic CI/CD Remediation: Integrating Goose into pipeline scripts to automatically attempt remediation for common build or dependency failures.

Strengths

  • Extensible Toolkit: Users can easily add new "Toolkits" (e.g., specific DB connectors, proprietary API clients, or FastMCP 3.1 servers) to Goose.
  • AAIF Governance: Community-driven development ensures neutrality, vendor independence, and long-term stability.
  • Model Agnostic: Seamlessly switches between Anthropic, OpenAI, Google, and local models via Ollama or LiteLLM.
  • Session Management: Supports durable, stateful sessions, allowing users to pause, resume, and audit complex multi-step agentic missions.
  • MCP 3.1 / FastMCP 3.1 Task Protocol: Allows external agents to delegate background execution tasks directly to Goose over the network with complete state verification.

Limitations

  • Security Responsibility: Giving an agent shell and filesystem access requires the user to manage trust boundaries and sandboxing (e.g., running in Docker/VMs).
  • Token Efficiency: Complex tasks can involve many iterations, leading to high token consumption if the model loops on difficult problems.
  • Rapid Evolution: Frequent core updates can lead to breaking changes in experimental toolkits.

When to use it

  • When you need a full-loop agentic software engineer that can fix bugs and run tests autonomously.
  • When you want a neutral, open-source platform for building your own specialized coding agents.
  • When you need to automate repetitive system administration or development tasks that require both shell execution and code editing.

When not to use it

  • For simple, single-file code completion where a lightweight tool like standard Copilot is faster.
  • In highly restricted environments where giving an AI agent shell/filesystem access is strictly prohibited.
  • If you prefer a purely GUI-based tool (Goose is optimized for CLI and agentic API usage).

Getting started

Installation

Goose can be installed via its official installer or as a Python package.

# Recommended installer
curl -fsSL https://goose.run/install.sh | sh

Basic Usage

# Start an interactive Goose session
goose session

# Execute a one-off mission
goose run "Audit the current directory for security vulnerabilities in package.json and fix them."

CLI examples

Mission Execution

# Run a specific mission with a defined model
goose run "Refactor all exported functions in src/utils to use arrow syntax" --model claude-5-6-sonnet

# Run an autonomous verification loop
goose run "Run pytest and fix any failures found in the test suite" --max-turns 15

# List active sessions
goose session list

Toolkit and FastMCP 3.1 Management

# List available toolkits
goose tools list

# Enable a specific toolkit for a session
goose session --toolkit developer

# Connect Goose directly to an external FastMCP 3.1 server
goose session --mcp-server http://localhost:8080/mcp

API examples

Python Agentic API

Goose can be used as a library to build custom agent applications under early January 2027 SOTA specs: 

from goose.agent import GooseAgent
from goose.config import AgentConfig

# Initialize with advanced token limits and prompt templates
config = AgentConfig(
    model="gpt-5.6-turbo",
    temperature=0.2,
    max_tokens_per_turn=4096,
    protocol_version="FastMCP 3.1"
)

agent = GooseAgent(config=config)
response = agent.execute("Create a summary report of the current git status and stage modified files.")
print(response.content)

Custom FastMCP 3.1-Compatible Toolkit Definition with Strict Pydantic v2

This example demonstrates custom toolkit validation utilizing strict Pydantic v2 schemas, complete with input filtering, custom validation rules, and configuration constraints. 

import re
from goose.toolkit import Toolkit, tool
from pydantic import BaseModel, Field, field_validator, ConfigDict

class NetworkQuery(BaseModel):
    # Strict validation configurations in Pydantic v2
    model_config = ConfigDict(
        extra="forbid",
        str_strip_whitespace=True,
        validate_assignment=True
    )

    hostname: str = Field(
        ...,
        description="The host to run diagnostics on, matching domain/IP standards"
    )

    @field_validator("hostname")
    @classmethod
    def validate_hostname(cls, value: str) -> str:
        # Prevent shell injection attacks or invalid domain characters
        sanitized = value.strip().lower()
        if not re.match(r"^[a-zA-Z0-9.-]+$", sanitized):
            raise ValueError("Hostname contains invalid characters. Only alphanumeric, '.' and '-' are allowed.")
        if len(sanitized) > 253:
            raise ValueError("Hostname is too long.")
        return sanitized

class DiagnosticsToolkit(Toolkit):
    @tool
    def ping_host(self, query: NetworkQuery) -> str:
        """Runs a ping check against the validated hostname and returns a diagnostic summary."""
        import subprocess
        try:
            # Safe execution using list arguments, avoiding shell=True
            res = subprocess.run(
                ["ping", "-c", "3", query.hostname],
                capture_output=True,
                text=True,
                timeout=5
            )
            return res.stdout if res.returncode == 0 else f"Ping completed with non-zero code:\n{res.stderr}"
        except subprocess.TimeoutExpired:
            return f"Error: Diagnostic ping timed out after 5 seconds against {query.hostname}."
        except Exception as e:
            return f"Ping failed during invocation: {str(e)}"

Sources / references

Contribution Metadata

  • Last reviewed: 2027-01-07
  • Confidence: high