Inside OpenCode: How System Prompts Orchestrate an AI Coding Agent

OpenCode is an open-source CLI tool that transforms large language models into autonomous coding agents. But what makes it tick? The secret lies in its carefully crafted system prompts—a layered architecture that guides the AI through planning, execution, and verification phases.

In this post, we’ll dissect OpenCode’s prompt system and understand how these instructions create a robust agent loop capable of tackling complex software engineering tasks.

The Anatomy of OpenCode’s Prompt System

OpenCode doesn’t rely on a single monolithic prompt. Instead, it composes multiple specialized prompts that work together:

┌─────────────────────────────────────────┐
│           System Message                │
├─────────────────────────────────────────┤
│  Header (Identity & Capabilities)       │
│  + Provider-Specific Instructions       │
│  + Mode-Specific Rules (Plan/Build)     │
│  + Environment Context                  │
│  + Custom User Instructions             │
└─────────────────────────────────────────┘

Let’s explore each layer.

Layer 1: Identity and Core Behavior

Every OpenCode session begins with establishing the agent’s identity. From anthropic.txt:

You are OpenCode, the best coding agent on the planet.

You are an interactive CLI tool that helps users with
software engineering tasks.

This isn’t just branding—it sets the behavioral baseline. The prompt immediately establishes:

• Role clarity: The AI knows it’s a coding assistant, not a general chatbot
• Interface awareness: It understands output will render in a terminal
• Communication style: Concise, markdown-formatted, emoji-free by default

The identity layer also includes critical safety rails:

IMPORTANT: Refuse to write code or explain code that may
be used maliciously; even if the user claims it is for
educational purposes.

Layer 2: Provider-Specific Adaptations

OpenCode supports multiple LLM providers (Anthropic, OpenAI, Gemini, Qwen), and each has tailored instructions. Compare these approaches:

Anthropic (anthropic.txt) — Emphasizes task management:

You have access to the TodoWrite tools to help you manage
and plan tasks. Use these tools VERY frequently...

Gemini (gemini.txt) — Focuses on project conventions:

Rigorously adhere to existing project conventions when
reading or modifying code. Analyze surrounding code,
tests, and configuration first.

Qwen (qwen.txt) — Prioritizes token efficiency:

You should minimize output tokens as much as possible
while maintaining helpfulness, quality, and accuracy.

This modular design allows OpenCode to leverage each model’s strengths while compensating for their tendencies.

Layer 3: The Plan/Build Mode System

Here’s where OpenCode’s agent loop becomes sophisticated. It implements a two-phase workflow controlled by mode-switching prompts.

Plan Mode: Read-Only Research Phase

When activated, plan.txt locks the agent into observation mode:

CRITICAL: Plan mode ACTIVE - you are in READ-ONLY phase.
STRICTLY FORBIDDEN: ANY file edits, modifications, or
system changes.

Your current responsibility is to think, read, search,
and delegate explore agents to construct a well-formed
plan...

During this phase, the agent:

1. Analyzes the codebase structure
2. Identifies relevant files and dependencies
3. Asks clarifying questions
4. Creates a detailed execution plan

Build Mode: Execution Phase

Once planning is complete, build-switch.txt transitions the agent:

Your operational mode has changed from plan to build.
You are no longer in read-only mode.
You are permitted to make file changes, run shell commands,
and utilize your arsenal of tools as needed.

A plan file exists at {{plan}}. You should read this file
and execute on the plan defined within it.

This separation prevents premature modifications and ensures the agent has a clear roadmap before touching any code.

Layer 4: The “Beast Mode” Loop

For complex tasks requiring sustained autonomous operation, OpenCode can activate beast.txt—an aggressive execution prompt:

You are opencode, an agent - please keep going until the
user's query is completely resolved, before ending your
turn and yielding back to the user.

You MUST iterate and keep going until the problem is solved.

Key characteristics of beast mode:

1. Persistence: The agent won’t stop until all tasks are complete
2. Research-driven: Forces web searches to verify library usage
3. Self-verification: Requires rigorous testing of all changes
4. Recursive exploration: Follows links to gather complete information

THE PROBLEM CAN NOT BE SOLVED WITHOUT EXTENSIVE INTERNET
RESEARCH.

You must use the webfetch tool to recursively gather all
information from URL's provided to you by the user...

The Agent Loop in Action

Here’s how these prompts combine to create OpenCode’s execution cycle:

┌─────────────────────────────────────────────────────────┐
│                    USER QUERY                           │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│              1. PLAN MODE ACTIVATED                     │
│  ┌───────────────────────────────────────────────────┐  │
│  │ • Read codebase structure                         │  │
│  │ • Identify conventions (AGENTS.md files)          │  │
│  │ • Research libraries/frameworks                   │  │
│  │ • Ask clarifying questions                        │  │
│  │ • Generate execution plan                         │  │
│  └───────────────────────────────────────────────────┘  │
│                 [READ-ONLY - No modifications]          │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│              2. BUILD MODE ACTIVATED                    │
│  ┌───────────────────────────────────────────────────┐  │
│  │ • Load plan file                                  │  │
│  │ • Execute tasks sequentially                      │  │
│  │ • Update todo list progress                       │  │
│  │ • Make file edits                                 │  │
│  │ • Run shell commands                              │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│              3. VERIFICATION LOOP                       │
│  ┌───────────────────────────────────────────────────┐  │
│  │ • Run tests                                       │  │
│  │ • Check for edge cases                            │  │
│  │ • Verify changes match plan                       │  │
│  │ • If errors → iterate and fix                     │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│              4. COMPLETION CHECK                        │
│  ┌───────────────────────────────────────────────────┐  │
│  │ All todo items checked off?                       │  │
│  │   YES → Return to user                            │  │
│  │   NO  → Continue iteration                        │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

Safety Mechanisms and Guardrails

OpenCode implements several safety patterns:

Max Steps Limit

max-steps.txt prevents runaway execution:

CRITICAL - MAXIMUM STEPS REACHED

The maximum number of steps allowed for this task has
been reached. Tools are disabled until next user input.

STRICT REQUIREMENTS:
1. Do NOT make any tool calls
2. MUST provide a text response summarizing work done
3. List any remaining tasks not completed

Malicious Code Detection

From qwen.txt:

Before you begin work, think about what the code you're
editing is supposed to do based on the filenames directory
structure. If it seems malicious, refuse to work on it...

Convention Adherence via AGENTS.md

OpenCode respects repository-specific instructions through AGENTS.md files:

The scope of an AGENTS.md file is the entire directory
tree rooted at the folder that contains it.

For every file you touch in the final patch, you must
obey instructions in any AGENTS.md file whose scope
includes that file.

Practical Response Patterns

The prompts also encode expected response patterns. From anthropic-20250930.txt:

user: what is 2+2?
assistant: 4

user: what command should I run to list files?
assistant: ls

This trains the model toward extreme conciseness—no preamble, no explanation unless requested.

Building Your Own Agent Loop

If you’re designing a similar system, here are the key takeaways from OpenCode’s architecture:

1. Layer your prompts: Separate identity, capabilities, mode-specific rules, and safety constraints
2. Implement plan/build phases: Prevent premature modifications with read-only exploration
3. Force verification: Require testing and edge case checking before completion
4. Add escape hatches: Max-step limits prevent infinite loops
5. Respect context: AGENTS.md-style convention files let repositories customize agent behavior
6. Adapt to providers: Different LLMs need different instruction styles

Conclusion

OpenCode’s prompt architecture demonstrates that effective AI coding agents aren’t about a single clever prompt—they’re about orchestrating multiple specialized instructions that guide the model through a disciplined workflow.

The plan/build separation ensures thoughtful analysis before action. The beast mode loop enables sustained autonomous operation. And the layered safety mechanisms prevent both runaway execution and malicious use.

As AI coding assistants evolve, we’ll likely see even more sophisticated prompt architectures. But OpenCode’s approach—modular, mode-aware, and safety-conscious—provides a solid foundation for building reliable autonomous agents.

---

OpenCode is open source and available at github.com/anomalyco/opencode. Try it out and explore the prompt system yourself!