opencode-python

opencode-python is a local CLI coding assistant implemented in Python. The MVP uses a Planner -> Executor (ReAct-style) -> Reviewer flow orchestrated by LangGraph, backed by lightweight code retrieval, local tool execution, and SQLite session storage.

Status

This repository currently implements the MVP runtime described in:

• docs/plans/2026-03-11-opencode-python-prd.md
• docs/plans/2026-03-11-opencode-python-architecture.md
• docs/plans/2026-03-11-opencode-python-task-breakdown.md

Requirements

• Python 3.12+
• An OpenAI-compatible API key if you want to run against a real model provider

Install

python -m pip install -e ".[dev]"

Configuration

Settings are loaded with this precedence:

1. Environment variables
2. ~/.opencode/config.toml
3. CLI overrides

Copy .env.example and set at least OPENCODE_API_KEY when using a real provider.

Supported environment variables:

• OPENCODE_API_KEY
• OPENCODE_BASE_URL
• OPENCODE_MODEL
• OPENCODE_TIMEOUT_SECONDS
• OPENCODE_PERMISSION_MODE
• OPENCODE_DATA_DIR

Example ~/.opencode/config.toml:

[app]
data_dir = "C:/Users/you/.opencode"

[provider]
model = "gpt-4o-mini"
api_key = "sk-..."
base_url = "https://api.openai.com/v1"
timeout_seconds = 60

[security]
mode = "ask"

Commands

Show help:

opencode --help

Run a one-shot task:

opencode run "inspect the repository and summarize the entry points"

Run a chat-style task with explicit workspace and model overrides:

opencode chat "find the retrieval flow" --workspace-root . --model gpt-4o-mini

Inspect stored sessions:

opencode session list
opencode session show <session-id>
opencode session resume <session-id>

Permission Modes

• allow: execute supported tools without prompting
• ask: require confirmation for risky operations
• deny: block risky operations

Current tool set:

• shell
• fs_read
• fs_write
• search

Development

Run the test suite:

python -m pytest -v

Run a focused CLI test:

python -m pytest tests/cli/test_chat_command.py -v

Run the lightweight end-to-end CLI test:

python -m pytest tests/e2e/test_run_command_e2e.py -v

Known Limitations

• The MVP targets local single-user CLI usage only.
• Retrieval is lightweight keyword/BM25-style retrieval with reranking; it does not include symbol graphs.
• Provider support is currently OpenAI-compatible only.
• The CLI is command-oriented, not a full-screen TUI.