Introduction
If you're a Python developer who loves the terminal, OpenCode is an open-source AI coding agent that transforms the way you analyze and refactor projects. Instead of leaving your command line, you can chat your way through code improvements — asking it to explain functions, suggest revisions, or debug logic errors. This guide walks you through installing OpenCode, connecting it to a free Google Gemini API key, and using it to refactor a simple dice-rolling script. By the end, you’ll have the confidence to apply OpenCode to your own projects. Let’s dive in!
What You Need
Before you start, ensure you have these prerequisites:
- Python 3.11 or higher — the sample project requires it.
- A modern terminal emulator — such as iTerm2, Windows Terminal, or GNOME Terminal.
- An AI provider account — this guide uses Google AI Studio’s free tier to get a Gemini API key. You can also use Anthropic, OpenAI, or GitHub Copilot if you already have subscriptions.
- Background knowledge — basic Python programming and familiarity with your OS command line.
- The sample project — download the dice-rolling script from the link below. You’ll find both the starting and refactored versions to compare.
Get Your Code: Download the sample dice-rolling script (right-click and save).
Step 1: Install and Set Up OpenCode
In this step, you’ll install OpenCode, get a Gemini API key, configure the tool, and verify it works.
Install OpenCode
The fastest method is to use the official installation script. Open your terminal and run:
curl -fsSL https://opencode.ai/install.sh | bashThis script automatically downloads and sets up OpenCode. After installation, verify it’s available:
opencode --versionYou should see a version number. If not, ensure your PATH includes the installation directory.
Get a Free Gemini API Key
Visit Google AI Studio, sign in with your Google account, and create a new API key. Copy the key immediately — you’ll only see it once. The free tier is ample for this guide.
Configure OpenCode
Run OpenCode for the first time:
opencodeIt will prompt you to enter your AI provider. Type gemini and press Enter. Then paste your API key. OpenCode will create a configuration file automatically. You can also set the model (e.g., gemini-2.0-flash) by editing ~/.config/opencode/config.json.
Verify the Setup
In the OpenCode terminal interface, type a simple question about Python, such as:
What is a decorator in Python?Press Enter. You should receive a helpful answer. If you get errors, double-check your API key and internet connection. Once it works, you’re ready to move on.
Step 2: Create or Open a Python Project
OpenCode works best when it understands your project context. For this guide, you’ll use a dice-rolling script. If you downloaded the sample, unzip it and navigate to that folder in your terminal. Alternatively, you can create a new Python file named dice.py with the following code:
import random
def roll_dice(sides=6, count=1):
results = []
for _ in range(count):
results.append(random.randint(1, sides))
return results
if __name__ == "__main__":
num = int(input("How many dice? "))
sides = int(input("Sides per die? "))
print(roll_dice(sides, num))Save the file. Now launch OpenCode from within the same directory:
opencodeOpenCode will load the project context, allowing it to see your file structure and imports.
Step 3: Analyze Your Code with Conversational Commands
With OpenCode running and aware of your project, you can start analyzing. For example, ask it to explain the roll_dice function:
Explain the roll_dice function in detail.It will respond with a breakdown of parameters, logic, and edge cases. You can also ask about potential improvements:
What are the risks of using this code in production?OpenCode’s responses are context-aware — it knows the entire project, not just the current file. This makes it powerful for large codebases. Experiment by asking about imports, error handling, or performance.
Step 4: Refactor with AI Assistance
Now let’s refactor the dice-rolling script. You want to add input validation and support for multiple dice types. Tell OpenCode:
Refactor roll_dice to validate inputs and support a weighted dice option.OpenCode will propose changes, often including code snippets. Review its suggestions and ask for clarifications if needed. For example, you can say:
Show me the diff for the validation part only.Once you’re satisfied, apply the changes manually or copy the suggested code into your file. OpenCode doesn’t modify files automatically — it’s a deliberate assistant that respects your control.
Step 5: Customize with AGENTS.md
OpenCode reads a special file called AGENTS.md (or AGENTS.yaml) in your project root. This file defines custom instructions, such as preferred coding style, documentation standards, or third-party APIs. Create an AGENTS.md file:
# AGENTS.md for Dice Project
- Always include docstrings for every function.
- Use type hints.
- Prefer list comprehensions over explicit loops where possible.OpenCode will follow these guidelines when answering questions. This is especially useful for teams or maintaining consistency across a project.
Tips for Success
Here are a few pointers to get the most out of OpenCode:
- Be specific — vague questions yield vague answers. Instead of "make this better", say "add input validation to roll_dice".
- Iterate — treat OpenCode as a collaborator. Ask follow-up questions to refine its suggestions.
- Use AGENTS.md early — set your coding conventions before starting a project to ensure consistent output.
- Combine with version control — commit your code before major refactoring so you can always revert if a change doesn’t work out.
- Explore other providers — while Gemini is free, you may find Anthropic or OpenAI better for complex tasks. Switch providers anytime by editing the config file.
- Keep your terminal modern — OpenCode works best with a terminal that supports color and links, like iTerm2 or Windows Terminal.
With these steps, you’re now equipped to use OpenCode for AI-assisted Python coding. Happy refactoring!