Customizing Opencode for Professional Python Development
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!
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 templatesThis 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:
- Enforces consistent code style and formatting
- Automates testing and quality checks
- Integrates seamlessly with Python tooling (uv, ruff, mypy, pytest)
- Provides security scanning out of the box
- 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:
uvfor environment management and dependenciesrufffor linting and formatting (replaces flake8, black, isort, etc.)mypyfor static type checkingpytestfor testingbanditfor security lintingsafetyanduv-securefor 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 scanningThis creates a reliable, repeatable process that catches issues early.
Code Style Rules
The file details specific Python conventions:
- Google-Style Docstrings — Clear, consistent documentation
- Strict Type Hints — Full signatures with proper nullable types
- No Print in Production — Mandatory use of logging module
- Explicit Error Handling — Specific exception catching, no bare excepts
- PEP 8 Naming — snake_case for functions/variables, PascalCase for classes
- Import Organization — Standard library → third-party → local application
- Modern Python Features — f-strings, pathlib, dataclasses, match/case, etc.
- Async Patterns — Proper async/await usage, no asyncio.run() in libraries
- Security Practices — Environment variables for secrets, parameterized queries
- Performance Guidelines — Appropriate data structures and algorithms
- 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=htmlMCP 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!
Thank you for being a part of the community
Before you go:
👉 Be sure to clap and follow the writer ️👏️️
👉 CodeToDeploy Tech Community is live on Discord — Join now!
Disclosure: This post includes affiliate and partnership links.









