Use this as a “where do I start?” index. It is intentionally oriented around ownership, not exhaustive file enumeration.
AGENTS.md repository architecture contract
FORK.md fork/upstream ownership + merge policy
keep-manifest.json machine-readable keep/prune policy
package.json workspace composition
packages/ product/runtime packages
script/ repository automation + fork sync
patches/ dependency patches
extensions/ client extensions
benchmarks/ reusable benchmark harnesses
experiments/ prototypes / experimental evidence
docs/ documentation
.openfork/ repo-local OpenFork configuration/tools/agents
| Concern | Start here |
|---|---|
| Main GUI / session page / project explorer / settings | packages/app/src |
| Shared session/message rendering | packages/session-ui/src |
| Shared visual primitives | packages/ui/src |
| Electron windows/native integration/IPC | packages/desktop/src/main, src/preload |
| Desktop renderer host glue | packages/desktop/src/renderer |
| Built-in browser authority | packages/desktop/src/main/browser and fork browser surfaces in app |
| Browser visual capture support | packages/browser-visual/src |
| Mobile client | packages/mobile/src |
| Current durable session/domain behavior | packages/core/src/session |
| Cross-generation V1/V2 historical FTS ranking and read-only evidence fusion | packages/core/src/session/{search,recall}.ts, packages/core/test/session-search.test.ts, docs/perf/2026-10-09-oxp-memory-recall-fidelity.md |
| Current built-in tool contracts | packages/core/src/tool |
| Durable DB schema/migrations | packages/core/src/**/*.sql.ts, packages/core/src/database |
| V1 session/prompt execution | packages/opencode/src/session |
| V1/fork-rich tools | packages/opencode/src/tool |
| Background Dreamer and historical memory integrity | packages/opencode/src/tool/dream.ts, packages/opencode/src/special-agent/dreamer-runtime.ts, packages/opencode/src/agent/prompt/dreamer.txt, packages/opencode/src/session/subagent-delegation.ts, packages/schema/src/agent.ts, packages/core/src/memory/{index,store}.ts, docs/architecture/dreamer-background-agent.md |
| Fast scoped Memory reads, index repair and recall fidelity | packages/opencode/src/exchange/{memory,memory-query,memory-session,memory-read-runtime}.ts, packages/opencode/src/oxp/memory.ts, packages/core/src/memory/{index,store,projection,migrate-project}.ts, packages/opencode/script/{bench-memory-runtime,inspect-memory-session-index,repair-memory-session-index}.ts, packages/core/test/session-search-repair.test.ts, packages/opencode/test/exchange/{memory-fidelity,memory-repair-script}.test.ts, docs/perf/2026-10-09-oxp-memory-{latency,recall-fidelity}.md |
| Native Swarm creation, staged partial admission, retry receipts | packages/opencode/src/swarm/command.ts (shared host workflow), packages/opencode/src/swarm/task-batch.ts (staged tasks), packages/opencode/src/swarm/ax-projection.ts (bounded creation receipt), packages/opencode/src/tool/swarm-create.ts (eager flat creation), packages/opencode/src/tool/swarm.ts (lazy coordinator), packages/opencode/src/tool/swarm-member.ts (worker AX/continuations), packages/opencode/src/oxp/swarm.ts (approved-root connector adapter), packages/core/src/swarm/messaging.ts (durable inbox paging) |
| Repository-local custom tool scripts | .openfork/tool (see its AGENTS.md) |
| Plugin tool contracts and registration APIs | packages/plugin/src (see its AGENTS.md) |
| Cross-surface executable tool mapping / disposition (not proof of dispatch) | packages/opencode/src/exchange/tool-coverage.ts |
| Native + lazy tool exposure policy | packages/opencode/src/tool/registry.ts, packages/opencode/src/tool/exposure.ts |
| Code search/describe/run gateway | packages/opencode/src/tool/code.ts, packages/codemode |
| Full local HTTP API composition | packages/opencode/src/server/routes/instance/httpapi |
| OXP external-agent semantics / MCP endpoint / parent-tool continuity | packages/opencode/src/oxp |
| Swarm AX-focused OXP broker schemas / contract compression | packages/opencode/src/oxp/schema-projection.ts (reviewed flat action focus plus discriminated unions), packages/opencode/src/oxp/capability.ts (per-action Swarm field inventory and action-bound contract), docs/architecture/swarm-agent-experience-audit-2026-10-09.md (AX test ledger) |
| OFXP peer capability dispatcher | packages/opencode/src/ofxp, packages/core/src/ofxp-* |
| ACP agent/editor tool bridge | packages/opencode/src/acp |
| MCP tool importing/invocation and explicit export boundaries | packages/opencode/src/mcp |
| OXP OpenAI and Cloudflare transports, loopback relay, secure credentials, tray/autostart, standalone migration | packages/desktop/src/main/oxp, packages/desktop/scripts/fetch-cloudflared.ts, packages/desktop/src/main/sidecar.ts |
| Upstream-current API contract (donor/transitional, not OpenFork target) | packages/protocol/src |
| Shared server middleware/handlers | packages/server/src |
| Generated upstream-current Protocol client (retained only where needed) | packages/client |
| Generated unified local-host SDK (legacy OpenCode naming) | packages/sdk/js |
| Provider wire protocols | packages/llm/src |
| Shared browser-safe schemas/IDs | packages/schema/src |
| OpenFork plugin contracts (not generic OpenCode compatibility) | packages/plugin |
| Retained TUI/CLI coupling code | packages/tui/src, embedded CLI host under packages/opencode/src/cli |
| Fork sync/prune behavior | script/fork-sync.ts, script/fork-prune.ts, FORK.md, keep-manifest.json |
packages/core/src contains the current domain/runtime substrate. Important areas:
session/ session state, input, runner, execution, history, projectors
tool/ current built-in tools and registry
event/ durable/current event services
database/ database and migrations
goal/ Goal durable/runtime domain
scheduled-task/ scheduled-task domain
search/ fork search/index services
effect/ Effect runtime/service composition
filesystem/ filesystem services
project/ project domain
observability/ logging/metrics/runtime observation
v1/ centralized V1 internal-compatibility helpers
Many top-level Core modules also expose domain services such as Git, shell, PTY, snapshot, provider, project inventory, process environment, system projection, and tool-output retention/projection.
packages/opencode/src is the OpenFork local host. The package name is inherited;
it is not a generic OpenCode compatibility layer:
server/ full local HTTP server + route composition
session/ legacy/V1 execution + internal bridge seams
tool/ V1/fork-rich tool implementations
provider/ provider host/runtime integration
system-one/ typed non-generative semantic-inference host integration
project/ project/instance host integration
config/ host config resolution
plugin/ plugin activation
cli/ embedded legacy CLI/TUI host code
acp/ ACP integration
oxp/ ChatGPT/OpenAI external-agent adapter + MCP endpoint
background/ background execution support
browser/ browser-related runtime support
goal/ Goal host integration
quota/ fork quota behavior
scheduled-task/ scheduler host/execution integration
snapshot/ snapshot integration
worktree/ worktree host behavior
util/ host/runtime utilities
When adding new behavior, first decide whether it belongs in durable/shared Core or
only in the OpenFork host adapter. Do not default to packages/opencode merely
because that is where an HTTP route lives.
packages/app/src is organized primarily by:
components/ reusable app-level interaction surfaces
context/ server state, projections, settings, files, tabs, runtime state
pages/ route/page composition
hooks/ reusable reactive data hooks
utils/ browser/app utilities and internal migration adapters
i18n/ app strings/localization
wsl/ Windows/WSL client support
The app is hybrid. A v2 component or route directory describes UI generation, not
necessarily API/runtime generation. See v1-v2.md.
Universal tool parity is defined in
docs/architecture/tool-surface-parity.md.
The OXP-only regression entry point is
packages/opencode/script/verify-oxp-native-parity.ts: its success
does not certify OFXP, ACP, MCP, or Code-mode execution paths. Every
applicable dispatcher needs actual execution/authorization tests.
Tests generally live adjacent to their owning package:
packages/core/testpackages/opencode/testpackages/app/src/**/*.test.*packages/app/e2e- package-local test directories elsewhere.
Architecture/performance claims should be closed with the real triggering runtime where practical, not only a unit test or isolated microbenchmark.
- current repository map:
docs/map; - durable cross-cutting architecture:
docs/architecture; - normative specs:
docs/specs; - active work/research:
docs/plans; - audits/handoffs/closeouts:
docs/handoff.