opencode Python: A practical guide for Python developers

opencode is a terminal coding agent that can edit Python files, run shell commands, and read project instructions from AGENTS.md. Start it in the project root after you set up a virtual environment and document the commands the agent should use. For a broader introduction to opencode itself, see the opencode page and How to use opencode: a step-by-step guide.

Why opencode fits Python work

opencode works well for Python because it sits in the same environment as a developer: it can activate or use the project virtual environment, run pytest, mypy, and ruff, and read pyproject.toml. Unlike a generic chat assistant, it can apply edits and re-run the tests after each change, which is the core loop of Python maintenance. Because Python’s runtime is available, opencode can also execute small scripts to inspect objects, check imports, or verify behavior before writing the final code. The agent can use the same pyproject.toml configuration as CI, so mypy and ruff flags stay consistent.

The value is highest when the project has clear rules. A Python project with a reproducible environment, type hints, and configured linters gives the agent fast feedback. That turns opencode from a code generator into a contributor that can catch its own mistakes through tests and static checks.

Setting up the project for opencode

Before starting opencode, create a virtual environment and install the project in editable mode. Keep all tool configuration in pyproject.toml so both you and the agent use the same commands. The most important file is AGENTS.md: opencode reads it from the project root and treats it as project instructions. Keep the pytest, mypy, and ruff settings in pyproject.toml under [tool.pytest.ini_options], [tool.mypy], and [tool.ruff]. That way opencode does not need to guess flags, and local runs match CI exactly.

A minimal but practical AGENTS.md for a Python project looks like this:

# Project instructions

Python 3.12, package name `acme_utils`, source in `src/acme_utils/`, tests in `tests/`.
Use the virtual environment in `.venv`. Run all commands from the project root.

## Commands

- Install: `uv sync --all-extras`
- Run tests: `uv run pytest -q`
- Type check: `uv run mypy src`
- Lint: `uv run ruff check src tests`
- Format check: `uv run ruff format --check src tests`

## Conventions

- Use `from __future__ import annotations` in every module.
- Add type hints to all public functions and methods.
- Keep tests independent; use fixtures from `tests/conftest.py` only.
- Do not edit `pyproject.toml` or the lockfile without asking first.
- After any change, run tests, type check, and lint. Report all command output.
- If a test is flaky, mark it with `@pytest.mark.flaky` and explain why.

If you use pip instead of uv, replace the commands with python -m pip install -e ., python -m pytest -q, and python -m mypy src. The point is not the exact tool but consistency: the agent should run the same commands as a human before declaring a task done.

A working loop for Python changes

A productive loop is plan, edit, verify, and review. Start by asking opencode to explore the relevant modules and propose a plan. Then ask for a small, testable change. After each agent turn, run the full test suite yourself or ask opencode to run it and show the output. Review the diff line by line, especially around public APIs, type hints, and test changes. When a test fails, paste the pytest output back to opencode and ask it to fix only that failure. Do not let the agent rewrite unrelated tests or weaken assertions to make the suite pass.

Typical prompts that keep Python work tight:

• Read src/acme_utils/parser.py and tests/test_parser.py. List the smallest three changes needed to add a parse_date function without changing existing behavior.
• Add a parse_date function in src/acme_utils/parser.py, type hint it, and add pytest tests for ISO dates, invalid dates, and timezone-aware values.
• Run uv run pytest -q and uv run mypy src. Show the diff. Do not edit tests after they pass unless I ask.
• Review the current diff for missing type hints, accidental changes to pyproject.toml, and Python style issues. Report only.
• Refactor the report module to use dataclasses instead of dicts, keep all existing tests green, and run uv run ruff check src tests before finishing.

The key is to keep each prompt scoped. If you ask opencode to modernize the whole codebase, it may touch many files and produce a diff that is hard to review. Small prompts produce small diffs, and small diffs are easier to trust.

Python tasks it does well and where to watch closely

opencode handles many Python tasks well because they are mechanical and have clear feedback from tests and type checkers. The table below lists common areas and the pitfalls to watch.

Python-specific pitfalls to watch closely:

• Virtual environment confusion: if opencode runs commands outside the venv, dependencies may be missing. Always specify the venv in AGENTS.md and in prompts.
• Import side effects: the agent may edit __init__.py or remove an import that happens to trigger side effects. Keep re-exports explicit.
• Type checker false positives: mypy may flag issues from third-party stubs or dynamic code. Tell the agent not to ignore errors without explaining the reason.
• Ruff autofixes: ruff check --fix or ruff format can rewrite code that was intentionally formatted. Ask the agent to show the diff before applying format changes.
• Dynamic tests and monkeypatching: pytest fixtures with monkeypatch or async tests can be fragile. Have opencode run the affected test file several times if there is any hint of flakiness.

How to test and verify Python changes

The agent should never claim a Python task is done without running the test suite, type checker, and linter. In practice, ask it to run:

• pytest with a specific test file during development, then the full suite at the end.
• mypy src to catch type errors introduced by the change.
• ruff check src tests and, if you enforce formatting, ruff format --check.

A good prompt for verification is: Run the full test suite, mypy on src, and ruff check. Show all command output, then describe the diff in five bullet points. Do not edit anything unless a test fails.

If pytest fails, give opencode the exact failure output. Ask it to fix the failing test or the source code, but not to change unrelated tests. If mypy reports errors in code you did not ask to modify, tell opencode to leave that module alone and note the pre-existing issue. This keeps the agent focused and prevents type-checking rabbit holes.

Parallel agents on a Python project with AgentVera

AgentVera is a desktop app that runs opencode alongside other coding agents in separate terminal panels. For a Python project, the git worktree support matters most: each agent can work in its own worktree, so parallel agents don’t overwrite each other’s files. Automatic code review after each agent turn catches Python-specific issues like missing type hints or broken tests, with findings linking to file:line. Checkpoints let you undo a bad refactor and replay a session, and token budgets prevent an agent from burning through your API quota on long refactoring tasks.

Final thoughts on using opencode for Python

Used deliberately, opencode can speed up Python development without replacing your own judgment. Keep AGENTS.md current, demand tests and type checks, and review every diff. For parallel work or review-heavy workflows, AgentVera’s worktrees and checkpoints add safety.