Onboarding: anomalyco/opencode

Generated by RepoPilot · 2026-05-04 · Source

Verdict

GO — Healthy across the board

• Last commit today
• 5 active contributors
• Distributed ownership (top contributor 48%)
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 5 top contributors

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

opencode is an open-source AI coding agent that runs in the terminal and as a desktop app, orchestrating LLM-powered code generation, editing, and tool use directly inside a developer's project. It provides a TUI (terminal user interface) built with TypeScript, exposes an SDK (@opencode-ai/sdk), and supports GitHub Actions integration via a published action. The agent can autonomously read, write, and reason about code files using configurable AI providers. Monorepo structure under packages/: packages/console holds the TUI/desktop app (with Astro/CSS assets), packages/web contains the marketing site (packages/web/src/assets/lander/screenshot.png), and a github/ package at root level handles GitHub Actions integration using @actions/core and @octokit/rest. Agent persona files and custom slash commands live under .opencode/agent/ and .opencode/command/ respectively.

Who it's for

Software engineers and polyglot developers who want a self-hostable, open-source alternative to Copilot Workspace or Cursor — particularly those who live in the terminal, want to wire up their own LLM backend, or need to embed AI coding automation into CI/CD pipelines via the GitHub Action.

Maturity & risk

The repo has a comprehensive CI setup with 20+ GitHub Actions workflows covering publishing, testing, typechecking, beta releases, Nix packaging, VS Code extension publishing, and Storybook. The presence of a desktop app (beta), npm package (opencode-ai), multiple package managers (brew, scoop, choco, pacman, nix), and an SDK indicates a project past the prototype stage and in active development. Verdict: actively developed and approaching production-ready, though the desktop app is explicitly labeled BETA.

The repo is a monorepo with a large TypeScript surface area (11.9MB) and heavy dependency on external LLM APIs, meaning upstream provider changes can break functionality without notice. The GitHub Actions package.json depends on @opencode-ai/sdk as a workspace dependency, tightly coupling the action to internal SDK changes. The .github/TEAM_MEMBERS file and CODEOWNERS suggest a small core team, creating single-maintainer-style bus factor risk for specific subsystems.

Active areas of work

Active work is visible in the .opencode/command/ directory with custom agent commands like changelog.md, commit.md, and rmslop.md — indicating ongoing refinement of the agent's built-in command vocabulary. The .github/workflows/beta.yml and publish-vscode.yml suggest a VS Code extension and beta release channel are being actively shipped. The docs-locale-sync.yml workflow and 20+ README language variants show internationalization is a current focus.

Get running

git clone https://github.com/anomalyco/opencode.git && cd opencode && bun install && bun run dev

Daily commands: bun install # install all workspace dependencies bun run dev # start the dev server / TUI in development mode bun run typecheck # run TypeScript checks across all packages

Map of the codebase

• README.md — Primary entry point documentation explaining what opencode is, how to install it, and how to contribute — essential reading for all new contributors.
• .opencode/opencode.jsonc — Core configuration file for the opencode agent itself, defining agent behavior, plugins, themes, and tooling used throughout the repo.
• CONTRIBUTING.md — Defines contribution conventions, branch strategy, and PR standards that every contributor must follow before submitting changes.
• AGENTS.md — Documents the agent architecture and agent-specific conventions, critical for understanding how AI agents are structured and extended in this codebase.
• .opencode/agent/triage.md — Defines the triage agent's behavior and prompts, a core agent workflow used in automated GitHub issue/PR management.
• .github/workflows/publish.yml — The primary CI/CD publish pipeline that builds and releases the opencode package — understanding this is essential for release management.
• .opencode/tool/github-triage.ts — Core tool implementation for GitHub triage automation, demonstrating how custom tools are built and integrated into the opencode agent.

Components & responsibilities

• OpenCode Agent Core (TypeScript, @opencode-ai/) — Orchestrates LLM calls, tool execution, and session management for the coding agent.

How to make changes

Add a new agent command

1. Create a new markdown file defining the command's system prompt, instructions, and expected behavior following the pattern of existing commands. (.opencode/command/your-command.md)
2. Register the new command in the opencode configuration file under the commands section so the agent can discover and invoke it. (.opencode/opencode.jsonc)
3. If the command should be triggered on GitHub events, add or update a workflow to call opencode with the new command. (.github/workflows/opencode.yml)

Add a new custom tool for the agent

1. Create a new TypeScript file in .opencode/tool/ implementing the tool using the @opencode-ai/sdk and @octokit/rest patterns established in existing tools. (.opencode/tool/your-tool.ts)
2. Register the tool in the opencode configuration so the agent can discover and call it during sessions. (.opencode/opencode.jsonc)
3. If the tool requires GitHub API access, ensure the workflow that triggers the agent passes the necessary GITHUB_TOKEN secret. (.github/workflows/opencode.yml)

Add a new GitHub Actions automation workflow

1. Create a new workflow YAML file in .github/workflows/ defining triggers (issues, pull_request, schedule, etc.) and jobs. (.github/workflows/your-workflow.yml)
2. If the workflow uses the opencode agent for AI tasks, reference the opencode action and pass a command from .opencode/command/. (.github/workflows/opencode.yml)
3. If the workflow needs Bun for TypeScript tool execution, include the setup-bun composite action as a step. (.github/actions/setup-bun/action.yml)

Add a new TUI theme or visual plugin

1. Create a JSON theme file defining color tokens and UI variables following the pattern of the existing smoke theme. (.opencode/themes/mytheme.json)
2. If adding an interactive plugin (animations, custom components), create a TSX plugin file using the TUI plugin API. (.opencode/plugins/tui-smoke.tsx)
3. Register the theme and/or plugin in the opencode configuration file so they are loaded at startup. (.opencode/opencode.jsonc)

Why these technologies

• Bun — Used as the TypeScript runtime and package manager for its speed in executing tool scripts and CI workflows without a separate build step.
• TypeScript — All custom tools and plugins are written in TypeScript for type safety when interacting with the @opencode-ai/sdk and @octokit/rest APIs.
• @octokit/rest + @actions/github — Standard GitHub API clients providing typed access to GitHub REST and GraphQL APIs for automation tools.
• Markdown-based agent prompts — Commands and agent definitions are stored as plain Markdown files making them version-controlled, diff-friendly, and editable without code changes.
• JSONC configuration — The opencode.jsonc config uses JSON with comments for human-readable, self-documenting agent configuration that supports inline explanations.

Trade-offs already made

• Agent prompts stored as Markdown files rather than code

  • Why: Allows non-engineers to edit agent behavior and enables easy diffing of prompt changes in PRs.
  • Consequence: Prompts lack type checking or validation — breaking changes to prompt format won't be caught at build time.

• Monorepo with workspace packages

  • Why: Allows the SDK, console, and tooling to share code and version together with consistent dependency management.
  • Consequence: Increases build complexity and requires careful workspace dependency management across packages.

• Using GitHub Actions as the agent execution environment

  • Why: Leverages existing CI infrastructure for agent runs without needing a separate server, simplifying deployment.
  • Consequence: Agent runs are limited by GitHub Actions concurrency, timeout limits, and cold start times.

Non-goals (don't propose these)

• Providing a general-purpose LLM API gateway or proxy
• Supporting non-GitHub version control systems (GitLab, Bitbucket) in the automation tooling
• Real-time collaborative editing features
• Long-term persistent memory across agent sessions beyond what is stored in GitHub issue/PR threads

Traps & gotchas

Bun is the required runtime (not Node.js) — scripts and workspace resolution use Bun-specific features, so npm/yarn/pnpm will likely fail. The github/ package uses workspace:* for @opencode-ai/sdk, meaning you must run bun install from the monorepo root before working on the Action. LLM provider API keys are almost certainly required via environment variables (not documented in visible files) to run the agent locally. The Rust components suggest a build step that may require a Rust toolchain installed separately.

Architecture

Concepts to learn

• AI Agent Tool Use (Function Calling) — opencode's core value is the agent autonomously calling tools (read file, write file, run shell) — understanding how LLMs invoke structured tool calls explains the agent's architecture.
• Monorepo with Workspace Protocol — The repo uses Bun workspaces with workspace:* dependencies (e.g., @opencode-ai/sdk) — changes to the SDK instantly reflect in the github/ package without publishing, but only within a correctly initialized monorepo.
• GitHub Actions Composite Actions — .github/actions/setup-bun/action.yml and setup-git-committer/action.yml are reusable composite actions shared across all workflows — modifying them affects every pipeline.
• Nix Flakes — The repo ships nix-eval.yml and nix-hashes.yml workflows plus a Nix file, enabling reproducible builds via nix run — contributors targeting NixOS or reproducible environments need to understand flake outputs.
• Terminal User Interface (TUI) Rendering — The packages/console app renders an interactive UI inside a terminal — this involves concepts like ANSI escape codes, virtual terminal rendering, and event loops that differ fundamentally from web DOM rendering.
• MDX (Markdown + JSX) — 7MB of the codebase is MDX, used for the Astro docs/web site — contributors adding documentation must understand how MDX components are imported and rendered differently from plain Markdown.
• Octokit GraphQL vs REST — The github/ Action uses both @octokit/rest (REST) and @octokit/graphql (GraphQL) — knowing when GitHub's API requires GraphQL (e.g., project boards, discussions) vs REST is non-obvious and critical for extending the Action.

Related repos

• anthropics/claude-code — Direct alternative: Anthropic's own terminal-based AI coding agent, the closest commercial equivalent to opencode.
• continuedev/continue — Alternative open-source AI coding assistant with VS Code/JetBrains integration, targets the same developer audience.
• octokit/octokit.js — The github/ package depends on @octokit/rest and @octokit/graphql for GitHub API calls in the Action.
• oven-sh/bun — Bun is the required runtime and package manager for the entire monorepo — understanding Bun's workspace protocol is essential.
• withastro/astro — The packages/web docs/marketing site is built with Astro and MDX, making this the upstream framework for the web package.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for .github/actions/setup-bun and setup-git-committer composite actions

The repo has two custom GitHub Actions composite actions (.github/actions/setup-bun/action.yml and .github/actions/setup-git-committer/action.yml) that are used across many workflows (beta.yml, publish.yml, deploy.yml, etc.) but there are no dedicated tests for them. A broken action silently breaks all downstream workflows. Adding a test workflow that exercises these actions with matrix scenarios (different OS, different Bun versions) would catch regressions early and document expected behavior.

• [ ] Create .github/workflows/test-actions.yml that triggers on changes to .github/actions/**
• [ ] Add a job that invokes ./.github/actions/setup-bun with a matrix of bun-version inputs and asserts the correct bun binary is on PATH
• [ ] Add a job that invokes ./.github/actions/setup-git-committer and asserts git config user.name and user.email are set to the expected bot values
• [ ] Run the workflow on ubuntu-latest, macos-latest, and windows-latest to catch OS-specific edge cases
• [ ] Document the expected inputs/outputs in each action.yml if they are currently undocumented

Add a missing glossary entry for Portuguese (Portugal) — currently only Brazilian Portuguese (br.md) exists

The .opencode/glossary directory has locale files for ar, br (Brazilian Portuguese), bs, da, de, es, fr, ja, ko, no, pl, ru, th, tr, zh-cn, and zh-tw. European Portuguese (pt.md or pt-pt.md) is absent even though it is a distinct locale used by contributors from Portugal, Angola, Mozambique, etc. The docs-locale-sync.yml workflow syncs documentation locales, so adding pt.md would integrate cleanly into the existing automation and make the project more accessible to a large community of speakers.

• [ ] Review .opencode/glossary/br.md as a structural reference for the new file
• [ ] Create .opencode/glossary/pt.md (European Portuguese) with translations that differ from Brazilian Portuguese (e.g. 'autocomplete' vs 'preenchimento automático', spelling conventions)
• [ ] Cross-reference .github/workflows/docs-locale-sync.yml to understand how locale files are picked up and ensure pt.md follows the same naming/format convention
• [ ] Open a discussion or issue first to confirm the maintainers want pt.md separate from br.md, then reference that issue in the PR description
• [ ] Update .opencode/glossary/README.md to list the new locale

Add a typecheck job for the github package's index.ts to the existing typecheck.yml workflow

The repo has a .github/workflows/typecheck.yml workflow and a standalone github package (dependency block shown in the config snippet) with its own index.ts entry point and TypeScript peer dependency. The github package uses @actions/core, @actions/github, @octokit/graphql, @octokit/rest, and the internal @opencode-ai/sdk — all of which have complex generics. If index.ts is not currently covered by the typecheck workflow, type regressions in GitHub Action scripts (used for triage, PR management, review, duplicate-issues, etc.) will go undetected until runtime inside a workflow run.

• [ ] Inspect .github/workflows/typecheck.yml to identify which packages/paths are currently checked
• [ ] Confirm whether the github package's index.ts (referenced as 'module' in the config snippet) is included in the tsc invocation or excluded
• [ ] If excluded, add a step or extend the matrix in typecheck.yml to run bun tsc --noEmit (or equivalent) inside the github package directory
• [ ] Ensure the github package has a tsconfig.json (create one if absent) that extends the root tsconfig and includes index.ts
• [ ] Verify the workflow passes cleanly by

Good first issues

1. Add unit tests for the github/index.ts GitHub Action entrypoint — no test files are visible in the github/ package directory. 2. The .opencode/command/ directory has commands like rmslop.md and spellcheck.md with no corresponding documentation in packages/web — write MDX docs explaining each custom command. 3. The Rust source (86KB) has no visible test workflow specifically for Rust — add a GitHub Actions workflow for cargo test similar to the existing test.yml.

Top contributors

• @kitlangton — 43 commits
• @opencode-agent[bot] — 27 commits
• @thdxr — 11 commits
• @Hona — 4 commits
• @nexxeln — 4 commits

Recent commits

• 007b57f — test(agent): skip InstanceBootstrap in plugin-agent regression test (#25737) (kitlangton)
• fb07c20 — fix(server): provide fresh ConfigProvider per HttpApi listener (#25726) (kitlangton)
• 25dc6f0 — fix(worktree): fork workspace worktree boot (#25723) (kitlangton)
• b70e270 — chore(docs): rename firmware provider to frogbot (#25453) (cgilly2fast)
• 1aed6b1 — sync (fwang)
• c1f607d — fix: ensure anthropic sdk properly resolves when using azure (#25721) (rekram1-node)
• 2c819f2 — chore: generate (opencode-agent[bot])
• 6e9f10a — test(server): regression reproducers for #25698 (#25714) (kitlangton)
• 1251a87 — fix(opencode): strip transfer-encoding in UI proxy and allow public manifest assets (#25698) (OpeOginni)
• 67047fa — chore: generate (opencode-agent[bot])

Security observations

• Critical · Unauthenticated Server Mode by Default — SECURITY.md / Server mode configuration. According to SECURITY.md, when server mode is enabled, it runs unauthenticated unless OPENCODE_SERVER_PASSWORD is explicitly set. This means any process or network peer that can reach the server endpoint can issue commands to the AI agent, which has shell execution, file I/O, and web access capabilities. There is no authentication enforced by default. Fix: Make authentication mandatory when server mode is enabled. Reject startup if OPENCODE_SERVER_PASSWORD is not set and server mode is requested. Consider mutual TLS or token-based auth instead of HTTP Basic Auth over plain HTTP.
• Critical · No Sandbox for Agent with Shell Execution Access — SECURITY.md / Agent tool system. The SECURITY.md explicitly states that OpenCode does not sandbox the agent. The AI agent has access to shell execution, file operations, and web access. The permission system is described solely as a UX feature, not a security boundary. A prompt injection attack or a malicious model response could instruct the agent to execute arbitrary commands on the host with full user privileges. Fix: Implement OS-level sandboxing (e.g., seccomp, AppArmor, namespaces, or mandatory Docker/VM isolation) as a default or strongly-warned-about requirement. At minimum, provide a hardened mode that restricts syscalls available to the agent subprocess.
• High · Prompt Injection Risk via Untrusted Content Processing — .opencode/tool/github-pr-search.ts, .opencode/tool/github-triage.ts, agent tool system. The agent system processes content from files, web access, and shell command outputs, all of which can be attacker-controlled. Without strict input sanitization or context separation between user instructions and tool output, malicious content in a file or webpage could inject instructions into the model context, causing the agent to perform unintended actions such as exfiltrating secrets or executing destructive commands. Fix: Implement prompt injection mitigations: clearly delimit tool output from instructions in the prompt, use system/user role separation rigorously, and consider a secondary validation layer before executing high-impact actions triggered by tool outputs.
• High · GitHub Token Exposure Risk in Custom Tool Scripts — .opencode/tool/github-pr-search.ts, .opencode/tool/github-triage.ts. The custom tool scripts (.opencode/tool/github-pr-search.ts and .opencode/tool/github-triage.ts) interact with the GitHub API using @actions/github and @octokit/rest. These tools likely consume GITHUB_TOKEN or a PAT from environment variables. If these scripts are executed by the agent in server mode with insufficient authentication, an attacker could trigger GitHub API calls or extract token values through crafted agent prompts. Fix: Restrict which tools are available in server mode. Ensure tokens are scoped to the minimum required permissions. Audit tool scripts to ensure they do not log or return token values in their output.
• High · Supply Chain Risk: workspace:* Dependency Pinning — package.json (github package). The package.json uses 'workspace:*' for @opencode-ai/sdk, meaning it references a local workspace package without a pinned version. If the monorepo workspace is compromised or the wrong package resolves at build time, malicious code could be introduced. Additionally, catalog: references for @types/bun and @octokit/rest indicate indirect version management that may not be strictly pinned. Fix: Pin all dependency versions explicitly, including workspace packages. Use lockfile integrity checks (bun.lockb) in CI and verify checksums. Audit catalog version management to ensure pinned, reviewed versions are used.
• High · CI/CD Workflow Injection Risk via Pull Request Triggers — .github/workflows/pr-management.yml, .github/workflows/review.yml, .github/workflows/triage.yml, .github/workflows/duplicate-issues.yml. The repository contains numerous GitHub Actions workflows (e.g., pr-management.yml, review.yml, triage.yml, duplicate-issues.yml). Workflows triggered by pull_request_target or issue_comment events that check out untrusted code or interpolate GitHub context values (github.event.pull_request.title, github.event.comment.body) into shell steps are vulnerable to command injection attacks from external contributors. Fix: Audit all workflows for pull_request_target usage and ensure untrusted code is never

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.