Usage

This guide walks you through the typical OpenCode workflow — from initialization to sharing your sessions.

Getting Started

Navigate to Your Project

cd /path/to/project

Launch OpenCode

opencode

Initialize the Project

Run the /init command inside the TUI:

/init

This analyzes your project and creates an AGENTS.md file in the project root. Commit this file to Git — it helps OpenCode understand your project structure and coding patterns.

Modes

OpenCode has two primary modes. Press Tab to switch between them:

Mode	Purpose	Can Modify Files?
Build	Make changes to your codebase	✅
Plan	Suggest and discuss without making changes	❌

TIP

Always start with Plan mode for complex features. Review the plan, give feedback, then switch to Build mode to implement.

Core Workflows

Asking Questions

Ask OpenCode to explain parts of your codebase. Use @ to fuzzy search for files:

How is authentication handled in @packages/functions/src/api/index.ts

This is especially useful for understanding code you didn't write.

Adding Features (Plan → Build)

Step 1: Plan — Switch to Plan mode with Tab:

<TAB>

Describe what you want in detail:

When a user deletes a note, we'd like to flag it as deleted in the database.
Then create a screen that shows all the recently deleted notes.
From this screen, the user can undelete a note or permanently delete it.

TIP

Talk to OpenCode like you would a junior developer on your team. Give plenty of context and examples.

Step 2: Iterate — Review the plan and provide feedback:

We'd like to design this new screen using a design I've used before.
[Image #1] Take a look at this image and use it as a reference.

You can drag and drop images into the terminal to add visual context.

Step 3: Build — Switch back to Build mode with Tab, then:

Sounds good! Go ahead and make the changes.

Making Direct Changes

For straightforward changes, skip the planning step:

We need to add authentication to the /settings route. Take a look at how this
is handled in the /notes route in @packages/functions/src/notes.ts and implement
the same logic in @packages/functions/src/settings.ts

Provide enough detail so OpenCode makes the right changes.

Undo / Redo

If the changes aren't what you wanted, undo them:

/undo

This reverts the changes and shows your original message again, so you can tweak the prompt and retry.

Run /undo multiple times to undo multiple changes. To redo:

/redo

Slash Commands

Command	Description
/init	Initialize OpenCode for the current project
/connect	Add or manage LLM provider credentials
/models	Select which model to use
/share	Create a shareable link to the current session
/undo	Undo the last set of changes
/redo	Redo previously undone changes

File References

Use @ followed by a filename to reference files in your prompt. OpenCode provides fuzzy search to help you find the right file:

@src/components/Header.tsx

This includes the file content in the context sent to the LLM, giving it precise knowledge about the code you're discussing.

Image Support

Drag and drop images directly into the terminal to include visual references. This is useful for:

• UI mockups and design references
• Screenshots of bugs or expected behavior
• Architecture diagrams

Sharing Sessions

Share your conversation with the /share command:

/share

This creates a link and copies it to your clipboard. Conversations are not shared by default — you must explicitly share them.

Here's an example conversation shared from OpenCode.

CLI Usage

Besides the interactive TUI, OpenCode also supports CLI commands:

# Run a one-off prompt without entering the TUI
opencode run "Explain the auth flow in this project"

# Start the server
opencode serve

# Start the web interface
opencode web

# List auth credentials
opencode auth list

Next Steps

• Tools — Learn about the tools OpenCode can use
• Configuration — Customize OpenCode for your workflow
• Tips & Tricks — Get the most out of OpenCode