OpenCode setup: Beginner’s Crash course

One Sentence Summary

Open Code introduces an AI coding agent with multiple interfaces, guiding quick setup, planning, building, and custom agents globally today.

Main Points

• Open Code is an AI coding agent with terminal, desktop, and IDE extension interfaces.
• Install via brew to get started quickly in your terminal.
• Two default agents: Plan first, then Build to execute the plan.
• You can switch models/providers in models and customize credentials.
• Start by creating a simple task, use plan to discover a structure, then build.
• Custom agents can be defined with a main agent and sub agents.
• Organize agents in folders and use templates to bootstrap new ones.
• You can observe sub-agent actions in real time when delegating tasks.
• Skills enable lazy loading of context and specialized capabilities.
• The “Open Agents Control” repo offers a fast-install path for beginners.

Takeaways

• Quick start: install with brew and run open code to begin.
• Use the Plan → Build workflow to scaffold functional pages fast.
• Build custom agent workflows by defining a main agent and sub agents.
• Leverage skills and permissions to tailor AI capabilities and safety.
• Check the Open Agents Control repo for a streamlined, repeatable setup.

---

Summary

The transcript explains how to install, configure, and use Open Code, an AI-powered coding agent that operates via terminal, desktop app, or IDE extension. The tutorial focuses on the terminal interface, demonstrating how to:

• Install Open Code using Homebrew
• Launch and interact with default agents (plan and build)
• Configure models (including OpenAI, Codex, and free models)
• Create custom agents (primary + sub-agents)
• Implement multi-agent workflows (build → review → test → iterate)
• Use skills for contextual task execution and automation

The main problem addressed: how to quickly set up and effectively use an AI coding agent with structured workflows and extensibility (agents + skills).

---

Detailed Step-by-Step Breakdown

1. Install Open Code

Command:

brew install opencode

Steps:

1. Open terminal (Terminal / PowerShell / Bash)
2. Paste the install command
3. Wait for installation + dependencies

Assumption: Standard/Typical Setup

• macOS with Homebrew
• Alternative shells (PowerShell/Bash) supported but not explicitly detailed

---

2. Launch Open Code

Navigate to your project directory:

cd /path/to/project

Run:

opencode

This launches the interactive agent interface

---

3. Understand Default Agents

Two built-in agents:

• plan → analyzes repo + creates execution plan
• build → executes implementation

Workflow:

1. Start with plan
2. Review generated plan
3. Press TAB
4. Switch to build
5. Execute implementation

---

4. Model Configuration

View models:

opencode
/models

Available:

• MiniMax M2
• Grok Code Fast
• OpenAI / Codex

Authenticate with OpenAI:

opencode auth login

Steps:

1. Select OpenAI
2. Choose account (e.g., ChatGPT Plus)
3. Complete OAuth in browser
4. Return → "Login successful"

Switch providers:

Ctrl + A

Favorite models:

Press:

F

---

5. Change Theme (Optional)

/themes

Examples:

• Open Code (default)
• One Dark
• Nord

---

6. Run First Example (HTML Page)

Prompt (Plan Agent):

Create a simple dashboard for a pizza shop landing page

Steps:

1. Run plan
2. Approve scan
3. Switch to build
4. Generate HTML

Result: Basic static HTML page

---

7. Create Custom Agents

Directory Structure:

/opencode/
  /agents/
    main-agent.md

Example Agent Config:

mode: primary
permissions:
  write: true
  edit: true
  bash: true

Run with specific agent:

opencode --agent main-agent

---

8. Create Sub-Agents

Structure:

/opencode/agents/sub-agents/master-planner.md

Key Concepts:

• Primary agent = user-facing
• Sub-agent = invoked internally
• Must match exact name for delegation

⚠️ Critical:

Agent name mismatch → delegation fails

---

9. Multi-Agent Workflow Design

Example pipeline:

1. Main Agent

   • Implements task

2. Delegates to:

   • Reviewer Agent
   • Tester Agent

3. Feedback loop:

   • Fix → rebuild → retest

Example Flow:

Implement → Review → Test → Iterate

---

10. Permissions Configuration

Example:

Reviewer Agent

edit: false
write: false
bash: false

Tester Agent

bash: true
write: false

---

11. Skills System (Advanced)

Purpose:

• Provide lazy-loaded context
• Enable script execution instructions

Structure:

/opencode/skills/frontend-design/skill.md

Example Skill Use Cases:

• UI design rules
• Build scripts
• Testing commands

Enable Skill:

permissions:
  skill_frontend_design: allow

Key Insight:

• Skills are global by default
• Can be selectively enabled/disabled

---

12. Use Prebuilt Agent System

Repo mentioned:

• Open Agents Control

Install:

<copy provided install command>

Then:

opencode

Select:

open-coder agent

---

Key Technical Details

Core Tools & Technologies

• Open Code (AI coding agent)
• Homebrew (installation)
• OpenAI / Codex
• MiniMax M2
• Grok Code Fast
• Next.js (example project)
• Markdown (.md) for agent configs

---

Important Commands

brew install opencode
opencode
opencode auth login
opencode --agent <agent-name>
Ctrl + A (switch providers)
F (favorite model)

---

File Structure Summary

/opencode
  /agents
    main-agent.md
    /sub-agents
  /skills
    /frontend-design
      skill.md

---

Agent Configuration Fields

• mode: primary | sub

• permissions:

  • write
  • edit
  • bash
  • skills

• model (optional)

---

Pro Tips

• Always start with plan → build workflow

• Use Ctrl + A to quickly switch providers

• Keep agent names exactly matching for delegation

• Use skills for:

  • reusable scripts
  • domain-specific knowledge

• Create multi-agent loops for better output quality

• Use:

opencode --agent <name>

to skip manual selection

• Keep permissions minimal for sub-agents (security + control)

---

Potential Limitations/Warnings

• ❌ Agent delegation fails if names mismatch
• ❌ Outputs vary due to non-deterministic AI behavior
• ❌ Basic agent setups may produce inconsistent results
• ❌ Skills require strong descriptions to be auto-selected
• ❌ Sub-agents without permissions cannot execute tasks
• ❌ OAuth setup required for OpenAI integration
• ❌ Default builds (e.g., HTML) are very basic

---

Recommended Follow-Up Resources

• Official Open Code Documentation

• Explore:

  • Agent configuration patterns
  • Multi-agent orchestration design
  • Prompt engineering for agents

• Study:

  • Next.js scaffolding workflows
  • CLI automation strategies

• Experiment:

  • Custom skills with bash scripts
  • Advanced permission control systems

---

Suggested Books (5)

1. Designing Data-Intensive Applications – Martin Kleppmann A deep dive into scalable system design, data flows, and architecture. Helps understand how agent-based systems can coordinate tasks and manage state across complex workflows.

2. Clean Code – Robert C. Martin Teaches principles of maintainable and readable code, directly useful when configuring AI agents to enforce code quality standards in automated builds.

3. The Pragmatic Programmer – Andrew Hunt & David Thomas Focuses on practical development workflows and automation—aligns well with building AI-driven coding pipelines and iterative agent loops.

4. Building Microservices – Sam Newman Provides insights into distributed system design, helpful for understanding multi-agent architectures and delegation patterns used in Open Code.

5. Automate the Boring Stuff with Python – Al Sweigart Great for learning automation techniques that parallel the use of skills and scripting within Open Code agents for task execution.