Distillation

Date: Sep 15, 2026

• 🔴 [enforced-workflow] (01:36) User directive: never run package tests from the repo root. Run tests from package directories such as packages/opencode; root package.json intentionally defines "test": "echo 'do not run tests from root' && exit 1.
• 🔴 (01:36) User directive for local standalone builds: run ./packages/opencode/script/build.ts --single, then ./packages/opencode/dist/opencode-<platform>/bin/opencode; replace <platform> with the actual platform, e.g. darwin-arm64 or linux-x64.
• 🔴 (01:36) User supplied the effect skill rules for this codebase: use current Effect v4 / effect-smol, not remembered Effect v2/v3 APIs; if .opencode/references/effect-smol is absent, clone https://github.com/Effect-TS/effect-smol there in the project; search that source and existing repository code for exact APIs, tests, naming patterns, and house style before answering or implementing Effect-specific code.
• 🔴 (01:36) Effect implementation conventions: use Effect.gen(function* () { ... }) for multi-step workflows; use Effect.fn("Name") or Effect.fnUntraced(...) for reusable service methods or important workflows; prefer Effect Schema, branded ID schemas, and Schema.TaggedErrorClass for typed domain errors; keep HTTP handlers thin and business rules in services; prefer Effect-aware platform abstractions; keep layer composition and missing dependencies explicit; do not introduce any, non-null assertions, unchecked casts, or obsolete Effect APIs.
• 🔴 (01:36) Effect testing conventions: use testEffect(...) from packages/opencode/test/lib/effect.ts for Effect services, layers, runtime context, scoped resources, and platform integrations; use it.live(...) for filesystem, git, HTTP servers, sockets, child processes, locks, real time, and other live behavior; prefer explicit test layers over ad hoc managed runtimes; use scoped fixtures/finalizers for temporary directories, flags, databases, fibers, servers, and global state.
• 🟡 (01:36) Initial file search returned No files found.
• 🟡 (01:36) Repository snapshot reported current commit dc661f30cb2055ad6248fdc59b14998d834497be; /tmp/opencode/session-recovery-full.patch SHA-256 was f051a53df476dd924bda0a14c4cd91a63c9e7eafff53bbe71f0460571335fcbd; packages/opencode/dist/server/opencode-server SHA-256 was 1ecc9afe36c12b31a8892cdbfb8a1560ceec97255c3537c073b795351233be40.
• 🟡 (01:36) Working tree had 20 changed tracked files totaling 454 insertions and 240 deletions: .lore.md, AGENTS.md, packages/core/schema.json, packages/core/src/database/migration.gen.ts, packages/core/src/database/schema.gen.ts, packages/core/src/session/compaction.ts, packages/core/src/session/execution/local.ts, packages/core/src/session/message-updater.ts, packages/core/src/session/projector.ts, packages/core/src/session/recovery.ts, packages/core/src/session/runner/index.ts, packages/core/src/session/runner/llm.ts, packages/core/src/session/runner/publish-llm-event.ts, packages/core/src/session/sql.ts, packages/core/test/session-execution-local.test.ts, packages/core/test/session-projector.test.ts, packages/core/test/session-runner-recorded.test.ts, packages/core/test/session-runner-tool-events.test.ts, packages/core/test/session-runner.test.ts, and packages/schema/src/session-event.ts.
• 🟡 (01:36) Untracked files were packages/core/src/database/migration/20260914235657_session-execution-lease.ts, perf.data, and perf.data.old.
• 🟡 (01:36) Largest reported diff changes included packages/core/src/session/runner/llm.ts with 132 changed lines, .lore.md with 137, packages/core/test/session-execution-local.test.ts with 81 new lines, packages/core/src/session/execution/local.ts with 77 changed lines, and packages/core/test/session-projector.test.ts with 65 changed lines.
• 🔴 (01:36) Repository is opencode, an AI-powered development tool at https://github.com/anomalyco/opencode, using Bun 1.3.14, TypeScript modules, workspaces, and Effect 4.0.0-beta.83; development requires Bun 1.3+.
• 🔴 (01:36) Development commands documented in CONTRIBUTING.md: from repository root run bun install and bun dev; bun dev <directory> starts the TUI against another directory; bun dev . targets the repository root; bun dev serve starts the headless API server on default port 4096; bun dev serve --port 8080 uses port 8080; bun dev web starts the server and web interface; bun run --cwd packages/app dev starts the web app, typically at http://localhost:5173; desktop commands are bun run --cwd packages/desktop dev, bun run --cwd packages/desktop build, and bun run --cwd packages/desktop package.
• 🔴 (01:36) If API or SDK code such as packages/opencode/src/server/server.ts changes, run ./script/generate.ts to regenerate SDK-related files.
• 🔴 (01:36) Repository architecture documented in CONTRIBUTING.md: packages/opencode contains core business logic and server; packages/opencode/src/cli/cmd/tui/ contains the SolidJS/opentui TUI; packages/app contains shared SolidJS web UI components; packages/desktop is an Electron wrapper around packages/app; packages/plugin contains @opencode-ai/plugin.
• 🔴 (01:36) Contribution requirements: UI or core product features require prior core-team design review; every PR must reference an existing issue using forms such as Fixes #123 or Closes #123; PRs should be small and focused and explain the issue, fix, and verification; UI changes need before/after screenshots or video; non-UI logic changes must explain testing and reviewer reproduction; long AI-generated PR descriptions/issues are unacceptable.
• 🔴 (01:36) PR titles follow conventional commits: feat:, fix:, docs:, chore:, refactor:, or test:, optionally scoped such as feat(app):, fix(desktop):, or chore(opencode):.
• 🔴 (01:36) Repository style preferences from CONTRIBUTING.md: keep logic in one function unless extraction clearly improves reuse/composition; avoid unnecessary destructuring and else; prefer .catch(...) over try/catch where possible; use precise types and avoid any; favor immutable patterns and avoid let; use concise single-word names when still descriptive; prefer Bun helpers such as Bun.file() when suitable.
• 🔴 (01:36) Issue policy: use one of the required templates—Bug report, Feature request, or Question; blank issues are disallowed; automated validation can flag missing templates, empty/placeholder fields, AI-generated walls of text, or missing meaningful content, after which the author has 2 hours to edit before automatic closure.
• 🟡 (01:36) Debugging guidance: prefer manually running bun run --inspect=<url> dev ... and attaching a debugger; use bun dev spawn when TUI server-code breakpoints fail because ordinary bun dev uses a worker thread; separate-server debugging command is bun run --inspect=ws://localhost:6499/ --cwd packages/opencode ./src/index.ts serve --port 4096, followed by opencode attach http://localhost:4096; TUI debugging command is bun run --inspect=ws://localhost:6499/ --cwd packages/opencode ./src/index.ts; alternatives include --inspect-wait, --inspect-brk, or export BUN_OPTIONS=--inspect=ws://localhost:6499/.
• 🟡 (01:36) Root package.json scripts include "dev": "bun run --cwd packages/opencode src/index.ts", "dev:desktop": "bun --cwd packages/desktop dev", "dev:web": "bun --cwd packages/app dev", "lint": "oxlint", "typecheck": "bun turbo typecheck", "postinstall": "bun run --cwd packages/core fix-node-pty", and "prepare": "husky"; Prettier configuration is "semi": false and "printWidth": 120.