anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-23 02:36:57 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

[PR #12263] docs: Add comprehensive core loop architecture guide #14136

New Issue
Closed
opened 2026-02-16 18:18:56 -05:00 by yindo · 0 comments
yindo commented 2026-02-16 18:18:56 -05:00
Owner
Copy Link
Copy Source

Original Pull Request: https://github.com/anomalyco/opencode/pull/12263

State: closed
Merged: No

What does this PR do?

This PR adds a detailed architectural documentation file (CORE_LOOP_ARCHITECTURE.md) that explains how OpenCode orchestrates multi-turn LLM interactions, manages tool execution, assembles context, and handles state transitions.

The document is written at a level of detail sufficient for a developer to reimplement the core loop from scratch. It covers:

  • Data Model (Section 1): Session, message, and part schemas; the tool state machine
  • Outer Loop (Section 2): The main SessionPrompt.loop() orchestrator, concurrency guards, exit conditions, and step limits
  • Processor (Section 3): Single-turn LLM streaming, tool lifecycle, retry logic, and doom loop detection
  • LLM Call (Section 4): System prompt assembly, tool filtering, model parameters, and the final streamText() invocation
  • Context Assembly (Section 5): Message array structure, system prompt components, conversation conversion, mid-loop reminders, and compaction filtering
  • Tool System (Section 6): Registry, resolution, context, and permission flow
  • Agent System (Section 7): Agent definitions, built-in agents, and permission rulesets
  • Context Window Management (Section 8): Overflow detection, compaction flow, and pruning
  • Subtask Execution (Section 9): How subtasks spawn child sessions
  • Cancellation (Section 10): Abort signal propagation
  • Complete Flow Diagram (Section 11): Visual representation of the entire flow
  • Key Design Decisions (Section 12): Rationale for architectural choices

This documentation serves as a reference for understanding the codebase and will help new contributors and maintainers understand the system's design without having to reverse-engineer it from code.

How did you verify your code works?

This is documentation only. The content was derived from careful analysis of the actual source code in packages/opencode/src/session/ and related modules. The document references specific file locations, function names, and line numbers that can be cross-referenced with the actual implementation. The architectural descriptions, data structures, and flow diagrams accurately reflect the current codebase structure and behavior.

https://claude.ai/code/session_013Gf8B4tpe3d39cb6t9ELAf

**Original Pull Request:** https://github.com/anomalyco/opencode/pull/12263 **State:** closed **Merged:** No --- ### What does this PR do? This PR adds a detailed architectural documentation file (`CORE_LOOP_ARCHITECTURE.md`) that explains how OpenCode orchestrates multi-turn LLM interactions, manages tool execution, assembles context, and handles state transitions. The document is written at a level of detail sufficient for a developer to reimplement the core loop from scratch. It covers: - **Data Model** (Section 1): Session, message, and part schemas; the tool state machine - **Outer Loop** (Section 2): The main `SessionPrompt.loop()` orchestrator, concurrency guards, exit conditions, and step limits - **Processor** (Section 3): Single-turn LLM streaming, tool lifecycle, retry logic, and doom loop detection - **LLM Call** (Section 4): System prompt assembly, tool filtering, model parameters, and the final `streamText()` invocation - **Context Assembly** (Section 5): Message array structure, system prompt components, conversation conversion, mid-loop reminders, and compaction filtering - **Tool System** (Section 6): Registry, resolution, context, and permission flow - **Agent System** (Section 7): Agent definitions, built-in agents, and permission rulesets - **Context Window Management** (Section 8): Overflow detection, compaction flow, and pruning - **Subtask Execution** (Section 9): How subtasks spawn child sessions - **Cancellation** (Section 10): Abort signal propagation - **Complete Flow Diagram** (Section 11): Visual representation of the entire flow - **Key Design Decisions** (Section 12): Rationale for architectural choices This documentation serves as a reference for understanding the codebase and will help new contributors and maintainers understand the system's design without having to reverse-engineer it from code. ### How did you verify your code works? This is documentation only. The content was derived from careful analysis of the actual source code in `packages/opencode/src/session/` and related modules. The document references specific file locations, function names, and line numbers that can be cross-referenced with the actual implementation. The architectural descriptions, data structures, and flow diagrams accurately reflect the current codebase structure and behavior. https://claude.ai/code/session_013Gf8B4tpe3d39cb6t9ELAf
yindo added the pull-request label 2026-02-16 18:18:56 -05:00
yindo closed this issue 2026-02-16 18:18:57 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#14136
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?