Skip to main content
This guide will help you run your first OpenCode session and understand the basics of using the terminal AI assistant.

​
Prerequisites

Before starting, make sure you have:
  1. Installed OpenCode - Follow the installation guide if you haven’t already
  2. Configured an API key - Set up at least one AI provider (see installation)

​
Start your first session

1

Navigate to your project

Open your terminal and navigate to any project directory where you want coding assistance:
cd ~/projects/my-app
2

Launch OpenCode

Start OpenCode by running:
opencode
OpenCode will launch in full-screen mode with a beautiful TUI interface.
3

Select your AI model (optional)

Press Ctrl+O to open the model selection dialog. You can choose from:
  • Anthropic: Claude 4 Sonnet, Claude 3.7 Sonnet, Claude 3.5 Haiku
  • OpenAI: GPT-4.1, GPT-4o, O1, O3-mini, O4-mini
  • Google: Gemini 2.5, Gemini 2.5 Flash
  • GitHub Copilot: Multiple models including Claude and GPT
  • Other providers: Groq, OpenRouter, Azure, Bedrock, VertexAI
Navigate with arrow keys and press Enter to select.
OpenCode automatically selects the best available model based on your configured providers.
4

Start chatting

Press i to focus the editor at the bottom of the screen. Type your question or request:
Can you explain what this codebase does and show me the main entry point?
Press Ctrl+S or Enter to send your message.
5

Review AI actions

OpenCode’s AI will analyze your request and use tools to help:
  • Read files with the view tool
  • Search code with the grep and glob tools
  • Execute commands with the bash tool
  • Modify files with the edit and write tools
For non-read-only operations, you’ll see a permission dialog:
  • Press a to allow once
  • Press A to allow for session (all future requests)
  • Press d to deny
Always review commands before approving, especially bash commands that modify your system.

​
Example conversations

Here are some example prompts to try: 
What does the main.go file do?

Can you explain how the session management works?

Show me where errors are handled in the codebase

Add error handling to the processUser function

Refactor the database connection to use a connection pool

Create a new REST endpoint for user authentication

Why is this test failing? Run the test and show me what's wrong

Fix the nil pointer error in server.go:127

The app crashes on startup, can you investigate?

Create a git commit for these changes

Show me the git diff and explain what changed

Create a pull request for this feature

​
Essential keyboard shortcuts

OpenCode uses vim-like keybindings for navigation. Press Ctrl+? anytime to see all shortcuts.

​
Global shortcuts

ShortcutAction
Ctrl+CQuit application
Ctrl+?Toggle help dialog
Ctrl+OSelect AI model
Ctrl+KOpen command dialog
Ctrl+ASwitch session
Ctrl+NCreate new session
Ctrl+XCancel current AI operation
EscClose dialog or exit mode

​
Editor shortcuts

ShortcutAction
iFocus editor (from message view)
Ctrl+S or EnterSend message
Ctrl+EOpen external editor (e.g., $EDITOR)
EscBlur editor and return to messages
ShortcutAction
↑ or kMove up
↓ or jMove down
← or hMove left
→ or lMove right

​
Working with sessions

OpenCode automatically saves your conversations in sessions stored in a SQLite database at ~/.opencode/db.sqlite.

​
Switch sessions

  1. Press Ctrl+A to open the session switcher
  2. Navigate with ↑/↓ or j/k
  3. Press Enter to load a session

​
Auto-compact feature

When your conversation gets long (approaching the model’s context limit), OpenCode can automatically summarize it:
  • Enabled by default
  • Triggers at 95% of context window
  • Creates a new session with the summary
  • Prevents “out of context” errors
To disable: 
{
  "autoCompact": false
}

​
Using custom commands

Custom commands let you create reusable prompts. Press Ctrl+K to open the command dialog and explore:
  • Initialize Project: Creates/updates project memory file
  • Compact Session: Manually trigger conversation summarization
  • User commands: Your custom commands from ~/.config/opencode/commands/
  • Project commands: Project-specific commands from .opencode/commands/

​
Create your first custom command

1

Create commands directory

mkdir -p ~/.config/opencode/commands
2

Create a command file

Create ~/.config/opencode/commands/review-pr.md:
RUN gh pr view $PR_NUMBER --json title,body,commits,files
RUN gh pr diff $PR_NUMBER

Please review this pull request and:
1. Summarize the changes
2. Identify potential issues
3. Suggest improvements
3

Use the command

  1. Press Ctrl+K
  2. Select user:review-pr
  3. Enter the PR number when prompted
  4. The AI will fetch PR data and provide a review

​
Non-interactive mode

For scripting and automation, use OpenCode in non-interactive mode: 
# Get a quick answer
opencode -p "What's the difference between defer and panic in Go?"

# Output as JSON for parsing
opencode -p "List all exported functions in main.go" -f json

# Quiet mode (no spinner)
opencode -p "Generate a README" -q > README.md

​
Advanced options

​
Working directory

Start OpenCode in a specific directory: 
opencode -c /path/to/project

​
Debug mode

Enable debug logging to troubleshoot issues: 
opencode -d
Logs will be visible when you press Ctrl+L.

​
Configuration file locations

OpenCode looks for configuration in these locations (in order):
  1. ./.opencode.json - Project-specific config (highest priority)
  2. $XDG_CONFIG_HOME/opencode/.opencode.json - User config
  3. $HOME/.opencode.json - User config (fallback)
Local project configs override global configs.

​
Tips for effective use

Instead of “fix this”, say “fix the nil pointer error in processRequest on line 45”
For new codebases, start with “explore this codebase and tell me what it does” before making changes
Pay attention to which tools the AI uses - this helps you understand what it’s doing
Create a new session (Ctrl+N) for unrelated tasks to maintain clear context
Ask AI to “create a commit” or “create a PR” - it follows best practices automatically

​
Troubleshooting

​
”No API key found”

Make sure you’ve set an environment variable or config file with your API key: 
echo $ANTHROPIC_API_KEY  # Should print your key

​
“Command not found: opencode”

Ensure OpenCode’s install directory is in your PATH: 
echo $PATH | grep opencode
Restart your shell after installation.

​
Permission denied errors

Check file permissions if you see permission errors: 
ls -la ~/.opencode/bin/opencode
chmod +x ~/.opencode/bin/opencode

​
Next steps

Now that you’re familiar with the basics:

Configuration guide

Learn about LSP integration, MCP servers, shell config, and more

Custom commands

Create powerful custom commands with named arguments

AI tools reference

Understand all tools available to the AI assistant

Keyboard shortcuts

Master all keyboard shortcuts for maximum efficiency

Build docs developers (and LLMs) love

Get started for freeTalk to us