> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opencode-ai/opencode/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart guide

> Get up and running with OpenCode in minutes. Learn the basics of starting a session, chatting with AI, and using keyboard shortcuts.

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](/installation) if you haven't already
2. **Configured an API key** - Set up at least one AI provider (see [installation](/installation#setup-api-keys))

## Start your first session

<Steps>
  <Step title="Navigate to your project">
    Open your terminal and navigate to any project directory where you want coding assistance:

    ```bash theme={null}
    cd ~/projects/my-app
    ```
  </Step>

  <Step title="Launch OpenCode">
    Start OpenCode by running:

    ```bash theme={null}
    opencode
    ```

    OpenCode will launch in full-screen mode with a beautiful TUI interface.
  </Step>

  <Step title="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.

    <Info>
      OpenCode automatically selects the best available model based on your configured providers.
    </Info>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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**

    <Warning>
      Always review commands before approving, especially bash commands that modify your system.
    </Warning>
  </Step>
</Steps>

## Example conversations

Here are some example prompts to try:

<AccordionGroup>
  <Accordion title="Understanding code">
    ```
    What does the main.go file do?

    Can you explain how the session management works?

    Show me where errors are handled in the codebase
    ```
  </Accordion>

  <Accordion title="Making changes">
    ```
    Add error handling to the processUser function

    Refactor the database connection to use a connection pool

    Create a new REST endpoint for user authentication
    ```
  </Accordion>

  <Accordion title="Debugging">
    ```
    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?
    ```
  </Accordion>

  <Accordion title="Git operations">
    ```
    Create a git commit for these changes

    Show me the git diff and explain what changed

    Create a pull request for this feature
    ```
  </Accordion>
</AccordionGroup>

## Essential keyboard shortcuts

<Note>
  OpenCode uses vim-like keybindings for navigation. Press `Ctrl+?` anytime to see all shortcuts.
</Note>

### Global shortcuts

| Shortcut | Action                      |
| -------- | --------------------------- |
| `Ctrl+C` | Quit application            |
| `Ctrl+?` | Toggle help dialog          |
| `Ctrl+O` | Select AI model             |
| `Ctrl+K` | Open command dialog         |
| `Ctrl+A` | Switch session              |
| `Ctrl+N` | Create new session          |
| `Ctrl+X` | Cancel current AI operation |
| `Esc`    | Close dialog or exit mode   |

### Editor shortcuts

| Shortcut            | Action                                |
| ------------------- | ------------------------------------- |
| `i`                 | Focus editor (from message view)      |
| `Ctrl+S` or `Enter` | Send message                          |
| `Ctrl+E`            | Open external editor (e.g., \$EDITOR) |
| `Esc`               | Blur editor and return to messages    |

### Navigation

| Shortcut   | Action     |
| ---------- | ---------- |
| `↑` or `k` | Move up    |
| `↓` or `j` | Move down  |
| `←` or `h` | Move left  |
| `→` or `l` | Move 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:

```json theme={null}
{
  "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

<Steps>
  <Step title="Create commands directory">
    ```bash theme={null}
    mkdir -p ~/.config/opencode/commands
    ```
  </Step>

  <Step title="Create a command file">
    Create `~/.config/opencode/commands/review-pr.md`:

    ```markdown theme={null}
    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
    ```
  </Step>

  <Step title="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
  </Step>
</Steps>

## Non-interactive mode

For scripting and automation, use OpenCode in non-interactive mode:

```bash theme={null}
# 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:

```bash theme={null}
opencode -c /path/to/project
```

### Debug mode

Enable debug logging to troubleshoot issues:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Be specific with requests">
    Instead of "fix this", say "fix the nil pointer error in processRequest on line 45"
  </Accordion>

  <Accordion title="Let AI explore first">
    For new codebases, start with "explore this codebase and tell me what it does" before making changes
  </Accordion>

  <Accordion title="Review tool usage">
    Pay attention to which tools the AI uses - this helps you understand what it's doing
  </Accordion>

  <Accordion title="Use sessions effectively">
    Create a new session (`Ctrl+N`) for unrelated tasks to maintain clear context
  </Accordion>

  <Accordion title="Leverage git integration">
    Ask AI to "create a commit" or "create a PR" - it follows best practices automatically
  </Accordion>
</AccordionGroup>

## Troubleshooting

### "No API key found"

Make sure you've set an environment variable or config file with your API key:

```bash theme={null}
echo $ANTHROPIC_API_KEY  # Should print your key
```

### "Command not found: opencode"

Ensure OpenCode's install directory is in your PATH:

```bash theme={null}
echo $PATH | grep opencode
```

Restart your shell after installation.

### Permission denied errors

Check file permissions if you see permission errors:

```bash theme={null}
ls -la ~/.opencode/bin/opencode
chmod +x ~/.opencode/bin/opencode
```

## Next steps

Now that you're familiar with the basics:

<CardGroup cols={2}>
  <Card title="Configuration guide" icon="gear" href="/configuration">
    Learn about LSP integration, MCP servers, shell config, and more
  </Card>

  <Card title="Custom commands" icon="code" href="/custom-commands">
    Create powerful custom commands with named arguments
  </Card>

  <Card title="AI tools reference" icon="wrench" href="/tools">
    Understand all tools available to the AI assistant
  </Card>

  <Card title="Keyboard shortcuts" icon="keyboard" href="/shortcuts">
    Master all keyboard shortcuts for maximum efficiency
  </Card>
</CardGroup>