opencode - Moses Yebei

The Problem

Developers need a locally‑run AI coding assistant that can read, edit, and run code across many languages and environments without sending proprietary source to a remote service. Maintaining such an agent in a single monolith quickly becomes brittle as the codebase grows.

What This Does

opencode ships a collection of seven self‑contained projects that together provide a desktop‑ready AI coding agent, a VS Code extension, a command‑line interface, and supporting SDKs.

The console UI lives in packages/console/app (Vite‑powered React, entry packages/console/app/src/app.tsx).
The web UI lives in packages/web (static assets, index.html).
Core runtime code resides in packages/opencode/src/… – modules such as project/instance.ts, config/config.ts, tool/tool.ts, and session/prompt.ts.
Docker images and CI pipelines are defined in packages/opencode/Dockerfile and .github/workflows/*.yml.
SDKs for external consumption sit under sdks/ and the Nix flakes under nix/.

All projects share a common TypeScript toolchain (tsconfig.json files) and are bundled with Cargo for the Rust‑based inference back‑end.

How It Is Wired

Execution starts at the CLI entry github/index.ts (invoked by the install script). It parses arguments, loads the configuration from packages/opencode/src/config/config.ts, and instantiates a ProjectInstance (packages/opencode/src/project/instance.ts).

ProjectInstance is the hub module: 73 other modules import it, giving it the largest blast radius. From there the flow diverges:

Agent selection – session/index.ts chooses the build or plan sub‑agent.
Prompt handling – session/prompt.ts builds the request sent to the LLM back‑end (Rust binary built via Cargo).
Tool execution – tool/registry.ts resolves built‑in tools (e.g., github-pr-search.ts), which invoke the server (server/server.ts) when remote APIs are needed.

The server module (server/server.ts) imports many utilities (34 outgoing edges) and sits inside a circular dependency with project/instance.ts and config/config.ts, inflating instability (0.83).

All UI projects import the shared logger (util/log.ts), which is imported by 46 modules, making it another hotspot.

Circular imports involve project/instance.ts, config/config.ts, and tool/tool.ts; breaking these cycles would reduce coupling and simplify testing.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/opencode
cd opencode

# Install the CLI globally (npm is the lockfile source)
npm i -g opencode-ai@latest

# Build the Docker image used by the agent
docker build -t opencode:dev -f packages/opencode/Dockerfile .

# Run the desktop UI (beta) – the binary is produced by the Cargo build
cargo build --release -p opencode-agent
./target/release/opencode-agent

Configuration files live in packages/opencode/src/config/config.ts; the default install script respects $OPENCODE_INSTALL_DIR, $XDG_BIN_DIR, $HOME/bin, and falls back to $HOME/.opencode/bin (see README.md for the path priority).

Real‑World Use

A team can run opencode locally, point it at a monorepo, and let the plan agent answer “What files will this change?” before the build agent actually writes edits. The CLI can be scripted in CI pipelines to auto‑resolve lint failures, using the tool/registry to invoke github-pr-search for cross‑repo context.

Code Health & Issues

Measured static analysis (217 findings)

High – Import cycles (33) – e.g., packages/opencode/src/project/instance.ts, config/config.ts, tool/tool.ts. Break cycles by extracting shared types.
High – Hub modules (9) – project/instance.ts, util/log.ts, config/config.ts each imported by >40 files; keep them stable.
High – Oversized files (12) – config/config.ts (≈1 k lines) and others; consider splitting.
High – Deep nesting (3) – max depth 7 in server/server.ts, session/prompt.ts, cli/cmd/tui/app.tsx. Refactor with early returns.
Medium – Empty catch blocks (2) – silent errors in config/config.ts, global/index.ts. Add logging or rethrow.
Medium – High branching density (1) – provider/provider.ts has 421 branches; simplify with strategy tables.

Code‑health audit (9 findings)

High – Pin GitHub Actions to commit SHAs (.github/workflows/*).
High – Upgrade vulnerable turbo@2.5.6 (CVE‑2026‑45773).
Medium – Declare least‑privilege GITHUB_TOKEN permissions (.github/workflows/deploy.yml).
Medium – Enable Dependabot (.github/dependabot.yml).
Medium – Pin Docker base image by digest (packages/opencode/Dockerfile).
Medium – Add a dependency‑vulnerability scan step in CI.
Medium – Move >5 MB binaries to Git LFS (packages/console/app/src/asset/lander/opencode-comparison-min.mp4).
Medium – Add non‑root USER to Docker image.
Low – Set timeout-minutes on workflow jobs.

The repo includes tests (75 test files), CI via GitHub Actions, a LICENSE, and lockfiles; no secrets were found.

The Bottom Line

opencode offers a functional, multi‑project AI coding agent with a clear installation path and Docker support, but its core TypeScript layer suffers from heavy coupling, large hub modules, and several import cycles that raise maintenance risk. Teams comfortable managing these refactors can benefit from the ready‑made UI and SDKs; otherwise, the codebase will need systematic modularization before long‑term production use.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

2,755 files

TypeScript485
TSX224
JSON157
CSS100
SQL53
Markdown41

ReactExpressRailsDockerTransformersCUDA

Module dependencies

The 10 most depended-upon modules of 718, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_pencode_src_project_instance["instance"] n1_ckages_opencode_src_util_log["log"] n2_s_opencode_src_config_config["config"] n3_ges_opencode_src_cli_cmd_cmd["cmd"] n4_kages_opencode_src_tool_tool["tool"] n5_s_opencode_src_session_index["index"] n6_es_opencode_src_global_index["index"] n7_ncode_src_session_message_v2["message-v2"] n8_pencode_test_fixture_fixture["fixture"] n9_packages_opencode_src_id_id["id"] n2_s_opencode_src_config_config --> n1_ckages_opencode_src_util_log n2_s_opencode_src_config_config --> n6_es_opencode_src_global_index n2_s_opencode_src_config_config --> n0_pencode_src_project_instance n5_s_opencode_src_session_index --> n2_s_opencode_src_config_config n5_s_opencode_src_session_index --> n9_packages_opencode_src_id_id n5_s_opencode_src_session_index --> n1_ckages_opencode_src_util_log n5_s_opencode_src_session_index --> n7_ncode_src_session_message_v2 n5_s_opencode_src_session_index --> n0_pencode_src_project_instance n7_ncode_src_session_message_v2 --> n9_packages_opencode_src_id_id n4_kages_opencode_src_tool_tool --> n7_ncode_src_session_message_v2 n1_ckages_opencode_src_util_log --> n6_es_opencode_src_global_index n8_pencode_test_fixture_fixture --> n2_s_opencode_src_config_config classDef cyc stroke:#ef4444,stroke-width:2px; class n0_pencode_src_project_instance,n2_s_opencode_src_config_config,n4_kages_opencode_src_tool_tool,n5_s_opencode_src_session_index,n7_ncode_src_session_message_v2 cyc;

Dependencies

6 of 52 declared dependencies are a major version behind. Resolved 51 of 52 against the registry.

Package	Declared	Latest	Behind
`@actions/github`	6.0.1	9.1.1	3 major
`@actions/core`	1.11.1	3.0.1	2 major
`typescript`	^5	7.0.2	2 major
`@actions/artifact`	5.0.1	6.2.1	1 major
`sst`	3.17.23	4.17.1	1 major
`@shikijs/transformers`	3.9.2	4.4.3	1 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium6

low1

Pin third-party GitHub Actions to a commit SHAhigh7 occurrences

.github/workflows

docker/login-action@v3, docker/setup-qemu-action@v3, docker/setup-buildx-action@v3, apple-actions/import-codesign-certs@v2

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Upgrade the pinned dependency carrying a published advisoryhigh2 occurrences

turbo@2.5.6 CVE-2026-45773 (medium) +1 more

The pinned version is the one that installs, so a published advisory against it describes this deployment rather than a hypothetical one, and the advisory is also a public description of how to exploit it.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/deploy.yml

1 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

21 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium2 occurrences

packages/opencode/Dockerfile

alpine, build-${TARGETARCH} (mutable tag)

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium2 occurrences

packages/console/app/src/asset/lander/opencode-comparison-min.mp4

2 blobs over 5MB: opencode-comparison-min.mp4 16.1MB, opencode-min.mp4 9.9MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Add a non-root USER to the imagemedium

packages/opencode/Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/deploy.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.