Busabase × OpenCodeKnowledge Base for OpenCode
OpenCode can merge organization, user, project, and managed configuration; load AGENTS.md and instruction files; delegate to primary agents and subagents; and call local or remote MCP tools. These layers explain execution. They do not make a session summary canonical.
Configuration precedence
Resolve the effective config before recording what an OpenCode Agent was allowed to do.
OpenCode merges remote organization defaults, global config, custom paths, project config, `.opencode` directories, inline content, and managed settings. Preserve the resolved inputs and repository revision rather than citing one file as the whole runtime.
Organization defaults from .well-known
User preferences and runtime defaults
Repository-specific config and files
Admin-enforced highest-priority policy
Rules and instructions
AGENTS.md controls behavior; instruction references do not become a fact database.
OpenCode loads project and global AGENTS.md, supports Claude-compatible fallbacks, and can add files or remote URLs through the instructions array. Commit team guidance with the repository, keep personal preferences global, and query changing facts from their owner.
Run focused tests after changing this package.
Customer approval is complete and production is green.
Agent topology
Primary agents, subagents, and hidden system agents create different evidence trails.
Build and Plan are primary agents; General, Explore, and Scout are subagents; compaction, title, and summary agents perform hidden support work. Record which agent acted, which agent delegated, and which tool permissions applied.
| Agent role | Typical authority | Evidence to retain |
|---|---|---|
| Build | Write and execute | Diffs, commands, tests |
| Plan | Analyze with restricted writes | Plan and cited repository context |
| General | Delegated multi-step work | Task boundary and returned artifacts |
| Explore / Scout | Read-only discovery | Files or external sources inspected |
| Hidden system agents | Context support | Summary provenance when material |
Permission resolution
Allow, ask, and deny decide whether a tool runs; they do not approve the resulting record.
Permissions can be global, pattern-based, and agent-specific. Last matching rules win, while auto mode changes ask decisions but preserves explicit deny. Capture the resolved rule for every material action.
Matching allow / ask / deny rule
Prompt accepted when required
Action and response captured
Diff, test, or external readback
Owner accepts shared state
Skills and MCP
Skills supply procedures; MCP supplies external tools; neither should silently own current business state.
Skills load on demand from project, global, and compatible agent directories. MCP servers may be local or remote, use OAuth, and be controlled globally or per agent. Pin Skill content and MCP identity separately.
Procedure, templates, scripts, checklists
Tools, resources, authorization, runtime response
Accepted outcome, owner, lifecycle
Sessions and sharing
A shared OpenCode conversation is collaboration context, not a durable system of record.
Session links expose a conversation and its outputs. Keep the session as provenance, but promote one concise outcome with source references, exact repository revision, verification, and an accountable decision.
Run evidence
Reconstruct the effective runtime without copying the entire conversation.
A compact evidence bundle should identify config layers, instructions, agent topology, permissions, Skills, MCP calls, repository state, and validation.
config_digestResolved config and precedenceinstruction_refsAGENTS.md and extra instructionsagent_tracePrimary and delegated agentspermission_traceRules resolved for material toolstool_evidenceBuilt-in and MCP responsesrepository_refCommit, worktree, and diffverificationTests and external checks
Reviewed outcome
Promote a decision-sized result, not config files or a session transcript.
The record should remain understandable after the OpenCode session is compacted, shared, or deleted.
outcome_keyStable identity for the resultsession_refOpenCode session and agent traceconfig_refResolved config digestsource_refsCode, docs, and external recordsproposed_stateConcise interpretationownerAcceptance responsibilitydecisionAccepted, conditional, rejected, supersedednext_review_atFreshness checkpointPractical questions
OpenCode knowledge base FAQ
Does Busabase replace AGENTS.md?
No. AGENTS.md guides OpenCode behavior. Busabase holds selected reviewed results.
Which config file should evidence cite?
The resolved config and relevant source layers, not only the project file.
Does auto mode bypass deny?
Current OpenCode docs state explicit deny rules remain enforced.
Can a subagent approve its own result?
Tool permissions may let it act, but record acceptance remains a separate owner decision.
Should shared session links be canonical evidence?
Use them as provenance, alongside repository and external verification that survives link or retention changes.
Start with one resolved runtime
Capture how OpenCode acted, then review only the state another team needs.
Choose one completed OpenCode session, resolve config and permissions, attach verification, and submit one outcome instead of the full transcript.