Overview
Goose is an open-source, locally-running AI developer agent built by Block (formerly Square). It works directly on your machine, reading files, running commands, writing and editing code, and interacting with external tools via natural language instructions. Think of it as a coding co-pilot that executes tasks, not just suggests them.
Unlike browser-based AI assistants, Goose runs entirely in your environment. It does not send your code to a third-party cloud unless you configure a cloud model explicitly. This makes it ideal for enterprise environments where data privacy and on-premise operation are required.
What Problem Does Goose Solve?
Developers spend significant time on repetitive tasks: scaffolding modules, writing boilerplate, running test cycles, and making coordinated changes across multiple files. Goose automates these loops. You describe the goal in plain language, Goose figures out the steps, calls the right tools, and iterates until done.
How Goose Fits in the Shakudo Stack
Goose connects to:
- LiteLLM or Ollama: for model routing to cloud or local LLMs.
- MCP Servers: any MCP-compatible server in your environment becomes a Goose tool.
- Developer workstations or JupyterHub sessions: Goose runs as a local process.
- Git repositories: Goose reads and writes code files directly.
Key Concepts
- Extensions: each extension adds a set of tools (developer extension adds file read/write and shell execution).
- MCP (Model Context Protocol): open standard for external tool communication.
- Sessions: each run is a session with memory; can be paused and resumed.
- Profiles: saved config specifying extensions, model, and defaults.
What Goose Is Not
- Not a chat interface like Dify or Open-WebUI. It is a task-execution agent.
- Not a model itself. It is an orchestration layer that calls whatever LLM you point it at.
- Not fully autonomous without supervision. Run in scoped environments.
Knowledge Gaps
Goose is relatively new in Shakudo deployments. Where Shakudo-specific steps are not fully established, this KB documents upstream open-source defaults and flags areas needing customer-specific configuration.
Configuration Management
Profiles: team-wide standardisation
Use a shared profiles.yaml checked into a team repository so every developer uses the same model, extensions, and defaults:
# ~/.config/goose/profiles.yaml
default:
provider: openai
model: gpt-4o
api_key: ${LITELLM_API_KEY}
api_base: <https://litellm.internal.company.com/v1>
extensions:
- type: builtin
name: developer
Document: which models are approved at which tiers, which extensions are default vs. opt-in, where session logs are stored.
Environment Variables
Never hardcode sensitive values in profiles.yaml. Inject via shell profile or JupyterHub pod spec:
- LITELLM_API_KEY: model gateway key.
- GOOSE_PROVIDER: override the default provider at runtime.
- GOOSE_MODEL: override the default model at runtime.
- Custom env vars required by MCP server extensions (DB credentials, internal API keys).
Security Basics
Scope file access
Goose can read and write any file the running user has access to. On shared environments, run Goose in a user account with limited scope. Do not run Goose as root.
Data privacy and model routing
Goose sends prompt content, which may include file contents, to the configured LLM. For sensitive environments:
- Route through LiteLLM to control which provider receives data.
- Use an on-premise Ollama deployment when data must not leave the cluster.
- Avoid pasting credentials into the Goose prompt. Reference them by environment variable name.
MCP server trust
Any connected MCP server can provide Goose with tool definitions. Only connect MCP servers from trusted sources. Review tool definitions before enabling in production.
Performance Considerations
- Start a fresh session for each major task. Long sessions accumulate context and slow down.
- Scope Goose to the relevant subdirectory rather than a large monorepo root.
- Ensure Ollama model fits in GPU VRAM. CPU inference is significantly slower.
- Use smaller models (llama3.2:8b) for simple tasks. Reserve large models for complex reasoning.
Scaling Considerations
Goose is a per-developer tool, not a shared service. Scaling concerns are primarily around LLM backend capacity:
- LiteLLM handles rate limiting and load balancing. Configure concurrency limits there.
- Ollama can serve multiple concurrent requests if GPU VRAM permits.
Updates and Maintenance
pip install --upgrade goose-ai
After upgrading, validate profiles and extensions with a quick session (Deployment Runbook, Step 4).
Recommended Git Workflow
Goose writes directly to your file system. Always work in a git repository:
- Create a feature branch before starting a Goose session that will modify files.
- Run git diff after Goose finishes to review every change before committing.
- Squash Goose-generated commits into a clean, descriptive commit before opening a PR.
- For risky refactors, ask Goose to explain its plan before making any changes.
Deployment Issues
goose command not found
- Check: pip show goose-ai to find the install location.
- Fix: export PATH="$HOME/.local/bin:$PATH". Add to pod shell profile for JupyterHub.
pip install fails with dependency conflicts
- Check: pip install goose-ai --dry-run for conflict details.
- Fix: python -m venv goose-env && source goose-env/bin/activate && pip install goose-ai
Goose starts and immediately exits
- Check: goose session --debug for verbose startup output.
- Fix: ensure profiles.yaml exists with at least a provider and model.
Connection Issues
Could not connect to model provider
- Check: curl <api_base>/models. Verify API key is set and not expired.
- Fix: use internal service DNS name for cluster-internal LiteLLM. Check network policy.
Authentication error
- Check: echo $LITELLM_API_KEY to confirm it is non-empty and matches LiteLLM config.
- Fix: re-export in current shell, or restart JupyterHub pod.
MCP extension fails to connect
- Check: run the MCP server manually for startup errors.
- Fix: correct cmd and args in profiles.yaml. Ensure required env vars are in the env block.
Performance Issues
Responses are very slow
- Check: is the session very long? Is the LLM backend under load?
- Fix: fresh session. Check ollama ps for GPU-loaded model. Switch to a faster model.
Context limit reached
- Check: incomplete output or context-length error from the model.
- Fix: fresh session, smaller task scope, or switch to a larger-context model.
Misconfigurations
Goose using the wrong model
- Check: goose info. Check GOOSE_MODEL and GOOSE_PROVIDER env vars.
- Fix: unset conflicting env vars or update the profile explicitly.
Goose cannot write files
- Check: ls -la <directory> for write permissions.
- Fix: adjust permissions. Do not use root as a workaround.
Goose repeating the same failed action
- Check: LLM cannot interpret the error output.
- Fix: Ctrl+C, restart with clearer instructions, confirm required extension is loaded.
Frequently Asked Questions
Does Goose send my code to external servers?
It depends on the configured model. If routing to OpenAI/Anthropic/Vertex via LiteLLM, prompt content including file contents is sent to that provider. If using local Ollama, nothing leaves the cluster. For sensitive environments, use Ollama or a self-hosted model.
Can multiple developers share the same Goose instance?
No. Goose is per-user and per-session. Each developer runs their own instance. Share profiles.yaml via a team repository.
Can Goose run on a schedule?
Yes, in a limited way. Use goose run --task in a shell script scheduled with cron or Kestra. Best for deterministic, well-scoped tasks.
How does Goose compare to GitHub Copilot or Cursor?
Copilot and Cursor suggest code as you type. Goose executes tasks end-to-end including running commands and multi-file changes. They are complementary, not replacements.
What if Goose modifies the wrong files?
Goose has no built-in undo. Always work in a git repository. Review with git diff and revert with git checkout. For high-risk tasks, ask Goose to explain its plan before making any changes.
