IntelliJ + OpenCode fails to interact with .iml files (for at least PythonPath) #6982
Description
Description
Hey folks. I have used IntelliJ for a decade, and do for now. OpenCode executes from its Terminal more-or-less as expected, with the various glitches and challenges of copy-paste that are mentioned in other tickets. My local repositories are often in active development, and often one project will source from the local sources of two or three other actively developed projects. Nothing particularly unusual there, and this information is saved in a local .iml file. Here is an example:
<?xml version="1.0" encoding="UTF-8"?>
<module type="PYTHON_MODULE" version="4">
<component name="NewModuleRootManager" inherit-compiler-output="true">
<exclude-output />
<content url="file://$USER_HOME$/gitlab/dev/CloudNode" />
<content url="file://$USER_HOME$/gitlab/dev/RemarkableOCR" />
<content url="file://$MODULE_DIR$" />
<orderEntry type="inheritedJdk" />
<orderEntry type="sourceFolder" forTests="false" />
</component>
</module>
These files are parsed at runtime when IntelliJ executes a Python file in run/debug so that the appropriate PYTHONPATH is included. Without knowledge of this .iml file and subsequent creation of the runtime PYTHONPATH variable, the project Python complier would have no knowledge of these other repositories.
OpenCode does not search for these .iml by default, as these are specific to IntelliJ, but there also seems to be no OpenCode configuration way to alert OpenCode that its agents are working within an IntelliJ environment. I do not know what the OpenCode IDE support plans are, but I suspect each IDE has its own problems like these. What do you want us to do?
In the meantime, I simply have an INTELLIJ_INTEGRATION.md file which is part of the overall AGENT.md notes.
# IntelliJ + OpenCode Integration Instructions
## Overview
OpenCode CLI tool needs to create a `.opencode/.env` file to ensure consistent development environments between IntelliJ IDE and command-line operations. All In IntelliJ configuration data can be sourced from the repository .iml file.
## Module Configuration Detection
When a `.idea/*.iml` file exists in project root, OpenCode automatically:
1. **Loads .opencode/.env**: Uses environment file referenced in `opencode.json` via `"env_file"` setting
2. **Parses PYTHONPATH**: Uses colon-separated list of all source paths from .iml file
3. **Resolves All Sources**: Includes all directory urls included in content XML fields
4. **Automatic Integration**: Applies PYTHONPATH to all Python command executions
## Implementation Requirements
- Create `.opencode/.env` file with PYTHONPATH containing all IntelliJ source paths
- Reference env file in `opencode.json` using `"env_file": ".opencode/.env"` setting
- Include ALL `<content url="file://$PATH$">` entries from .iml file
- Handle standard IntelliJ path variables ($USER_HOME$, $MODULE_DIR$) in .env file
- Maintain backward compatibility when .iml files don't exist
## Development Best Practices
- Standardize .opencode/.env structure across projects
- Document source path extraction from IntelliJ .iml files
- Ensure all local development sources are included in PYTHONPATH
- Use colon-separated paths matching system PYTHONPATH format
## Error Prevention
- Validate that all IntelliJ source paths exist and are reflected in .env
- Provide clear error messages when module resolution fails
- Fallback to installed packages only when local sources unavailable
## Configuration Pattern
# ```bash
# .opencode/.env example
PYTHONPATH=/path/to/cloudnode:/path/to/ocr:/path/to/current/project
# ```
## Critical Note for Teams
This integration is essential for organizations using IntelliJ IDEA with OpenCode. This is especially important in actively developed local frameworks where API differences between installed packages and source code cause development blocking errors and differing behavior, sometimes silently. The .opencode/.env approach provides automatic, project-specific environment configuration without requiring OpenCode core changes.
Pretty straightforward, but feels fragile and I am new here. Hope this helps anyone who finds their ways here too.
Comments?
(PS is there a way to instruct the agent to launch these python processes in the background, i.e., a running server which remains active as the agent begins executing tests through a second process of client calls.)
Plugins
None
OpenCode version
1.1.1
Operating System
MacOS Tahoe 26.2
IntelliJ IDEA 2025.3.1 (Build #IU-253.29346.138, built on December 18, 2025)