Your Step-by-Step Guide to AI-Powered Python Refactoring with OpenCode

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 | bash

This script automatically downloads and sets up OpenCode. After installation, verify it’s available:

opencode --version

You 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:

opencode

It 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:

opencode

OpenCode 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!