Sitemap
CodeToDeploy

Tech Insights | Careers | Jobs

Customizing Opencode for Professional Python Development

8 min readMay 16, 2026

--

As a Python developer, I’ve always sought tools that enhance productivity without compromising code quality. When I discovered Opencode, I was impressed by its flexibility and decided to customize it specifically for Python development.

⏳ Limited-Time Udemy Offer
Don’t wait — Top Udemy Tech Courses are now available at huge discounts.
🎟️ Use auto-applied discount at checkout (limited-time offer) — grab it before it expires!

👉 Start now on Udemy

Press enter or click to view image in full size

While this guide focuses on Python customization, the same approach serves as a template that can be adapted for any programming language — simply adjust the tool-chain, formatting rules, and testing standards to match your target language.

The same style and testing rules work seamlessly with Claude Code as well, providing a consistent development experience across both platforms. In this post, I’ll share my setup, explaining each component and how it contributes to a superior development experience.

Project Structure

Here’s the complete file structure of my customized Opencode Python setup:

~/.config/opencode/
├── opencode.json # Main configuration file
├── AGENTS.md # Agent instructions
├── README.md
├── rules/
│ ├── git.md # Git branch naming and commit conventions
│ ├── python-style.md # Python toolchain, style, and code rules
│ ├── python-testing.md # Testing standards and patterns
│ └── templates.md # Project templates reference
├── skills/
│ ├── code-cleanup/ # YAGNI/DRY/KISS cleanup workflow
│ ├── code-refactor/ # Legacy Python modernization
│ ├── code-review/ # Final-gate review workflow
│ ├── ddg-search/ # Web search via DuckDuckGo
│ ├── mcp-builder/ # MCP server creation guide
│ ├── python-testing/ # Testing patterns and coverage
│ └── repomix/ # Codebase packaging tool
└── templates/ # Project scaffolding templates

This structure serves as a template adaptable to any programming language. Simply replace the language-specific components — rules like python-style.md, python-testing.md, and the Python tool-chain in opencode.json — with equivalents for your target language (e.g., javascript-style.md, go-testing.md, etc.).

Components Explained

AGENTS.md

The AGENTS.md file defines the core agent guidelines for the Opencode system:

  • Mandate: Discover → Plan → Execute → Verify
  • Authority: Proceed & Notify (refactoring, deps, tests) / Propose & Wait (architecture, APIs, new deps) / Do Not Touch (secrets, CI/CD, destructive ops)
  • Process: Surface assumptions → search patterns → read rules → plan (with non-goals + rollback path) → execute one module per pass (skill chain: @cleanup → @refactor → @review)
  • Always-On Rules: References @rules/python-style.md, @rules/python-testing.md, @rules/git.md
  • Required Output: Discovery Report, Strategic Plan, Assumptions & Risks, Proposed Changes, Skipped Candidates, Verification Pyramid
  • Halt & Escalate: Security vulnerabilities, scope exceeding 5 extra files, contradictory requirements, bypassing architecture, destructive ops, sub-agent conflicts

agents/ Directory

Contains sub-agent definitions, each with its own model assignment, permissions, and invocation instructions.

skills/ Directory

On-demand invoke-able workflows, each with specialized instructions and bundled scripts.

With this structure in mind, let’s explore why customizing Opencode is beneficial.

Customize Opencode for Python?

Opencode is powerful out of the box, but its true strength lies in its configuration. By tailoring it to Python’s ecosystem and best practices, I’ve created a development environment that:

  1. Enforces consistent code style and formatting
  2. Automates testing and quality checks
  3. Integrates seamlessly with Python tooling (uv, ruff, mypy, pytest)
  4. Provides security scanning out of the box
  5. Reduces cognitive load through automation

The key takeaway is that Opencode’s real power comes from its configuration. By tailoring it to your specific language and workflow needs, you can create a development environment that not only catches errors early but also makes the entire development process more enjoyable and productive.

Let’s dive into the specifics of my configuration.

Core Configuration: opencode.json

The foundation of my setup is in opencode.json. Here are the key sections I've customized:

Instructions and Agents

{
"instructions": ["~/.config/opencode/rules/*.md"],
"default_agent": "plan",
"small_model": "opencode/big-pickle",
"agent": {
"build": {
"model": "opencode/minimax-m2.5-free"
},
"plan": {
"model": "opencode/nemotron-3-super-free"
}
}
}

This configuration:

  • Loads all rule files from the rules directory (my Python-specific guidelines)
  • Sets the default agent to “plan” for thoughtful problem-solving
  • Uses different models for different tasks (smaller model for routine tasks, larger for planning)

Language-Specific Formatters

"formatter": {
"prettier": {
"command": ["npx", "prettier", "--write", "$FILE"],
"extensions": [".ts", ".js", ".json", ".md", ".yaml", ".yml", ".html"]
},
"uv": {
"command": ["uv", "run", "ruff", "format", "$FILE"],
"extensions": [".py", ".pyi"]
}
}

I’ve configured Opencode to use:

  • Ruff for Python formatting (via uv run)
  • Prettier for other file types
  • This ensures consistent formatting across the entire project

Permission System

"permission": {
"read": {
"*": "allow",
"*.env": "deny",
// ... other sensitive file patterns
},
"edit": {
"*": "allow",
"*.env": "deny",
// ... other sensitive file patterns
},
"bash": {
"git *": "allow",
"uv run ruff*": "allow",
"uv run pytest*": "allow",
"uv run mypy*": "allow",
"ls *": "allow",
"wc *": "allow",
"grep *": "allow",
// ... other allowed commands
"*": "ask"
}
}

The permission system is crucial for security:

  • Allows read/edit access to most files
  • Blocks access to sensitive files (.env, keys, credentials)
  • Explicitly allows safe Python development commands (uv, ruff, pytest, mypy)
  • Requires approval for potentially dangerous commands (curl, wget, docker)

Python Style Rules: The Heart of the Setup

The python-style.md file contains my comprehensive Python development guidelines. Key aspects include:

Required Tool-chain

I standardized on these tools:

  • uv for environment management and dependencies
  • ruff for linting and formatting (replaces flake8, black, isort, etc.)
  • mypy for static type checking
  • pytest for testing
  • bandit for security linting
  • safety and uv-secure for dependency vulnerability scanning

Standard Workflow

The configuration enforces this workflow:

uv sync                        # Install dependencies
uv run ruff check --fix . # Lint and auto-fix
uv run ruff format . # Format code
uv run mypy src/ # Type check (strict)
uv run pytest # Run tests
uv run bandit -r src/ # Security analysis
uv run safety check # Dependency security
uv run uv-secure scan # Project security scanning

This creates a reliable, repeatable process that catches issues early.

Code Style Rules

The file details specific Python conventions:

  1. Google-Style Docstrings — Clear, consistent documentation
  2. Strict Type Hints — Full signatures with proper nullable types
  3. No Print in Production — Mandatory use of logging module
  4. Explicit Error Handling — Specific exception catching, no bare excepts
  5. PEP 8 Naming — snake_case for functions/variables, PascalCase for classes
  6. Import Organization — Standard library → third-party → local application
  7. Modern Python Features — f-strings, pathlib, dataclasses, match/case, etc.
  8. Async Patterns — Proper async/await usage, no asyncio.run() in libraries
  9. Security Practices — Environment variables for secrets, parameterized queries
  10. Performance Guidelines — Appropriate data structures and algorithms
  11. Dependency Management — Exclusive use of uv, regular updates

Testing Standards: python-testing.md

My testing configuration ensures high-quality, reliable tests:

Core Principles

  • Use pytest exclusively
  • Follow AAA pattern (Arrange → Act → Assert)
  • Tests must be fully independent
  • Coverage targets: business logic ≥95%, APIs ≥90%, models ≥85%

Test Patterns

The file provides examples of:

  • Basic unit tests
  • Parametrized tests
  • Property-based testing with hypothesis
  • Tests with fixtures
  • Error condition testing
  • Security testing patterns

Testing Commands

Standardized commands for running tests:

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-branch --cov-fail-under=85

# Show missing coverage lines
uv run pytest --cov=src --cov-report=term-missing

# Generate HTML coverage report
uv run pytest --cov=src --cov-report=html

MCP Servers: Extending Functionality

I’ve integrated several MCP (Model Context Protocol) servers to extend Opencode’s capabilities:

DuckDuckGo Search (ddg_search)

Enables real-time web searches for documentation and current information.

Get Syed Asif’s stories in your inbox

Join Medium for free to get updates from this writer.

link: https://github.com/sydasif/web-search-mcp

Nornir (nornir)

For network automation tasks when working with network-related Python projects.

link: https://github.com/sydasif/nornir-mcp-server

Repomix (repomix)

Packages codebases into AI-friendly formats for analysis and sharing.

link: https://github.com/yamadashy/repomix

Benefits of This Setup

After implementing this configuration, I’ve experienced several benefits:

Customizing Opencode for Python development has transformed my workflow. By integrating Python-specific tooling, enforcing quality standards, and automating routine tasks, I’ve created an environment where I can focus on solving problems rather than managing tooling.

The investment in setting up a proper development environment pays dividends in code quality and developer satisfaction.

Improved Code Quality

  • Consistent formatting eliminates style debates
  • Early bug detection through linting and type checking
  • Comprehensive test coverage reduces regressions
  • Security scanning catches vulnerabilities before they reach production

Increased Productivity

  • Automated workflows reduce manual steps
  • Clear guidelines decrease decision fatigue
  • Integrated tooling eliminates context switching
  • Pre-configured permissions improve safety

Better Collaboration

  • Standardized setup makes onboarding easier
  • Consistent code style improves readability
  • Shared quality standards reduce review friction
  • Clear documentation of expectations

How to Adapt This Setup

If you’d like to implement a similar configuration for any programming language, here are the steps:

Install Opencode if you haven’t already

Create the rules directory and add:

  • [language]-style.md (e.g., python-style.md, javascript-style.md, rust-style.md — based on my Python style guide above as a template)
  • [language]-testing.md (e.g., python-testing.md, go-testing.md — based on my Python testing standards above as a template)
  • Other rule files as needed (git.md, templates.md)

Configure opencode.json with:

  • Your preferred models
  • Formatters for your language (e.g., ruff for Python, prettier for JavaScript, rustfmt for Rust)
  • Appropriate permission settings
  • MCP servers you want to use

Install the required tools for your language:

  • Package manager (uv for Python, npm for JS, cargo for Rust)
  • Linter/formatter (ruff, eslint, clippy)
  • Type checker (mypy for Python, tsc for TypeScript, rust-analyzer for Rust)
  • Test runner (pytest, vitest, cargo test)
  • Security scanner (bandit, eslint-plugin-security, cargo-audit)
  • Any MCP servers you want to use

Test the setup on a project to ensure everything works correctly

You can also fork the GitHub repository at https://github.com/sydasif/open-code.git and amend or add files according to your specific needs. This gives you a ready-to-use starting point that you can customize further for your particular workflow.

I encourage you to experiment with this template in your own projects. Start with the basics — formatters and linters — and gradually add more sophisticated features like type checking, testing integration, and security scanning. Fork the repository, swap the language-specific pieces, and make it your own.

Conclusion

Have you customized Opencode for your development workflow? I’d love to hear about your setup and any tips you’ve discovered along the way!

Before you go:

Press enter or click to view image in full size

👉 Be sure to clap and follow the writer ️👏️️

👉 Follow us: Linkedin| Medium

👉 CodeToDeploy Tech Community is live on Discord — Join now!

Disclosure: This post includes affiliate and partnership links.

--

--

Syed Asif
Syed Asif

Written by Syed Asif

Associate Electronics Engineer in Radio Technology