How to Use Goose: Free Open-Source AI Coding Agent Guide

Claude Code has captured the imagination of developers worldwide — but at $20 to $200 per month, it is not cheap. Enter Goose: an open-source AI coding agent developed by Block (formerly Square) that offers nearly identical functionality for free.

In this tutorial, you will learn how to install, configure, and use Goose to write, debug, and deploy code autonomously. We will also show you how to connect it to budget-friendly AI APIs through Qubax AI so you can get Claude Code-level productivity without the premium price tag.

What Is Goose?

Goose is an open-source AI agent that runs in your terminal and can:

• Write code from natural language descriptions
• Debug existing codebases by reading errors and fixing them
• Refactor and modernize legacy code
• Run tests and interpret results
• Deploy applications to cloud platforms
• Manage git operations — commits, branches, PRs
• Answer questions about your codebase

It is built by Block — the financial technology company behind Square, Cash App, and Afterpay. Unlike proprietary tools, Goose is fully open-source under a permissive license, meaning you can inspect, modify, and extend it freely.

Goose vs Claude Code: Quick Comparison

The biggest advantage? Goose works with any LLM provider. You are not locked into one ecosystem — you can use GPT-5, DeepSeek, Gemini, Qwen, or any model accessible via API.

Step 1: Install Goose

Prerequisites

• Node.js 18+ (check with node --version)
• npm or your preferred package manager
• An API key for an LLM provider (we will use Qubax AI)

Installation

Via npm (recommended):

npm install -g @block/goose

Via Homebrew (macOS):

brew install block-goose/tap/goose

From source:

git clone https://github.com/block/goose.git
cd goose
npm install
npm run build
npm link

Verify the installation:

goose --version

Step 2: Configure Your AI Model

Goose needs an LLM to power its reasoning. Here is how to configure it with Qubax AI for the best combination of quality and price:

Create a Qubax AI Account

1. Sign up at qubax.ai
2. Generate an API key from your dashboard
3. You now have access to GPT-5, Claude, Gemini, DeepSeek, and 50+ other models

Configure Goose

Set environment variables for the simplest setup:

export GOOSE_API_KEY="YOUR_QUBAX_API_KEY"
export GOOSE_API_BASE="https://api.qubax.ai/v1"
export GOOSE_MODEL="anthropic/claude-sonnet-4"

Or create a JSON configuration file in your Goose config directory with your model, API base URL, API key, max turns, and temperature settings.

Choosing the Right Model

Different tasks benefit from different models:

# For complex coding tasks (best quality)
export GOOSE_MODEL="anthropic/claude-opus-4"

# For fast, everyday coding (balanced)
export GOOSE_MODEL="anthropic/claude-sonnet-4"

# For maximum savings (cheapest)
export GOOSE_MODEL="deepseek/deepseek-chat"

# For long context windows
export GOOSE_MODEL="google/gemini-2.5-pro"

Compare all available models and pricing at qubax.ai/models.

Step 3: Start Using Goose

Interactive Mode

Launch Goose in your project directory:

cd my-project
goose

You will get an interactive prompt where you can describe tasks in natural language. Goose will then:

1. Explore your codebase to understand the structure
2. Plan the changes needed
3. Write the code — creating new files and editing existing ones
4. Run tests to verify everything works
5. Report what it did

One-Shot Mode

For quick tasks, use the -q flag:

goose -q "Write a Python script that converts CSV to JSON"

goose -q "Find and fix the memory leak in src/cache.js"

Background Mode

For long-running tasks:

goose -q "Refactor the entire authentication module to use OAuth 2.0" &

Step 4: Common Workflows

Building a Feature from Scratch

Simply describe what you want: "Create a REST API for a blog with posts, comments, and user authentication using Express.js, MongoDB, with proper error handling and input validation."

Goose will scaffold the project, create models, routes, controllers, and middleware — all following best practices.

Debugging an Error

Paste your error and Goose will trace it through your code, identify the root cause, write a fix, and test it.

Writing Tests

Ask Goose to write comprehensive unit tests covering edge cases like declined cards, refunds, partial refunds, and currency conversion.

Code Review

Ask Goose to review the latest git diff and suggest improvements for security, performance, and readability.

Step 5: Advanced Configuration

MCP Server Integration

Goose supports Model Context Protocol (MCP) servers, extending its capabilities with database access, filesystem tools, and custom integrations. Define MCP servers in your configuration file to let Goose directly query databases and connect to external services.

Custom Tool Definitions

Define custom tools that Goose can use, like deployment scripts or project-specific commands.

Permission Controls

Control what Goose can do for safety — allow or block specific commands, require approval for sensitive actions, and restrict file system access.

Step 6: Cost Optimization Tips

Since Goose uses API calls, here is how to keep costs low:

1. Use Cheaper Models for Simple Tasks

Switch between models based on task complexity. Use DeepSeek for simple fixes, Claude for complex reasoning.

2. Limit Conversation Length

Goose maintains context across turns. Long conversations use more tokens. Start fresh sessions for new tasks with goose --new-session.

3. Be Specific in Your Prompts

Vague prompts cause Goose to explore more, using more API calls. Be specific about the file, the issue, and the desired outcome.

4. Use Qubax AI for Best Pricing

Qubax AI offers competitive pricing across all major models, with a single API key. No need to manage multiple provider accounts.

Troubleshooting Common Issues

Goose Cannot Connect to the API

Verify your API key and base URL with a simple curl test against the chat completions endpoint.

Goose Is Slow

• Try a faster model like DeepSeek or Gemini Flash
• Reduce max turns in your config
• Check your internet connection

Goose Made Unexpected Changes

Always use Goose in a git repository so you can review and revert changes with git diff and git checkout.

Security Best Practices

1. Never give Goose access to production databases without explicit safeguards
2. Use git so you can always review and revert changes
3. Review code before deploying — Goose is smart but not infallible
4. Set up permission controls to block dangerous commands
5. Keep your API key secure — never commit it to version control

Why Goose + Qubax AI Is the Ultimate Combo

Goose gives you a free, open-source agent framework. Qubax AI gives you affordable access to the best models. Together, they deliver:

• Zero framework cost (Goose is free)
• Best model selection (50+ models via Qubax)
• No vendor lock-in (switch models anytime)
• Open-source transparency (audit the code yourself)
• Community-driven development

Compare this to Claude Code subscription pricing, and the value proposition is clear.

Get Started Today

1. Get a Qubax AI API key: qubax.ai/models
2. Install Goose: npm install -g @block/goose
3. Configure your model: Set the API base to Qubax
4. Start coding: Run goose in your project directory

Read the full API docs at qubax.ai/docs.

FAQ

Is Goose really free?

Yes. Goose is open-source and free to use. You only pay for the LLM API calls it makes, and those costs depend on which model you choose. With budget models like DeepSeek, costs can be just pennies per day.

How does Goose compare to Claude Code?

Goose offers similar functionality — terminal-based coding, file editing, code execution, and git integration. The main differences are that Goose is open-source, supports any LLM (not just Claude), and has no subscription fee.

Can I use Goose with models other than Claude?

Yes! Goose works with any OpenAI-compatible API. Through Qubax AI, you can use GPT-5, Gemini, DeepSeek, Qwen, and dozens of other models.

Is Goose safe to use in production projects?

Goose includes permission controls and approval prompts for sensitive actions. However, always use it in a git repository so you can review and revert changes, and follow your organization code review practices.

Does Goose support MCP servers?

Yes. Goose has full MCP (Model Context Protocol) support, allowing you to extend its capabilities with database access, filesystem tools, and custom integrations.

What is the cheapest way to run Goose?

Use a budget model like DeepSeek or Gemini Flash through Qubax AI. These models cost less than $1 per million tokens while still delivering strong coding performance. See qubax.ai/models for current pricing.