> ## 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.

# Interactive mode

> Using OpenCode's terminal user interface for interactive AI-assisted coding

OpenCode's interactive mode provides a full-featured terminal user interface (TUI) for conversing with AI, managing sessions, and editing code directly in your terminal.

## Starting interactive mode

Launch OpenCode in interactive mode by running the command without any flags:

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

You can customize the startup with additional flags:

```bash theme={null}
# Start with debug logging
opencode -d

# Start in a specific directory
opencode -c /path/to/project
```

<Note>
  The TUI launches in an alternate screen buffer, preserving your terminal history when you exit.
</Note>

## Chat interface

The main chat interface consists of three key areas:

### Message area

The message area displays the conversation history between you and the AI assistant. Messages are rendered with:

* **Markdown formatting** for rich text display
* **Syntax highlighting** for code blocks
* **Tool call visualization** showing AI actions (file edits, command execution)
* **Timing information** for assistant responses
* **Session summaries** when auto-compact is enabled

<Tip>
  Use `Ctrl+U` and `Ctrl+D` to scroll up and down by half-page increments through long conversations.
</Tip>

### Editor area

The editor at the bottom of the screen is where you compose messages:

* Type your message directly in the editor
* Press `Enter` or `Ctrl+S` to send
* Use `\` followed by `Enter` to add a newline without sending
* Press `Ctrl+E` to open your external editor (set via `$EDITOR` environment variable)
* Attach files using `Ctrl+F` to open the file picker

#### Managing attachments

When you attach files, they appear above the editor with document icons:

* Press `Ctrl+R` followed by a number (0-9) to delete a specific attachment
* Press `Ctrl+R` followed by `R` to delete all attachments
* Press `Esc` to cancel delete mode

<Note>
  You can attach up to 5 files per message. Attachments are sent with your message to provide context to the AI.
</Note>

### Sidebar (session info)

When a session is active, the right sidebar displays:

* Current session title
* File change history for the session
* List of files modified during the conversation

## Session management

OpenCode organizes conversations into sessions that are persisted to a SQLite database.

### Creating sessions

Press `Ctrl+N` to create a new session. This clears the current conversation and starts fresh.

<Tip>
  The first message you send automatically creates a new session if one isn't active.
</Tip>

### Switching sessions

Press `Ctrl+S` to open the session switcher dialog:

* Use `↑`/`↓` or `j`/`k` to navigate sessions
* Press `Enter` to select a session
* Press `Esc` to close without switching

The dialog shows all your previous sessions with their titles, allowing you to resume any conversation.

### Auto-compact feature

When a conversation approaches the model's context window limit (95% of tokens), OpenCode can automatically summarize the session:

* The AI creates a summary of the conversation
* A new session is created with the summary
* You can continue working without losing context

This feature is enabled by default. Configure it in your `.opencode.json`:

```json theme={null}
{
  "autoCompact": true
}
```

<Note>
  You can also manually trigger session compaction using the "Compact Session" command via `Ctrl+K`.
</Note>

## Model selection

Press `Ctrl+O` to open the model selection dialog:

* Use `↑`/`↓` or `j`/`k` to navigate models
* Use `←`/`→` or `h`/`l` to switch between providers (OpenAI, Anthropic, etc.)
* Press `Enter` to select a model
* Press `Esc` to close without changing

The currently selected model is highlighted, and the dialog shows all available models from configured providers.

## Commands

Press `Ctrl+K` to open the command palette, which provides quick access to:

### Built-in commands

<CardGroup cols={2}>
  <Card title="Initialize Project" icon="rocket">
    Creates or updates an `OpenCode.md` file with project-specific context including build commands, style guidelines, and coding conventions.
  </Card>

  <Card title="Compact Session" icon="compress">
    Manually triggers session summarization, creating a new session with a summary of the current conversation.
  </Card>
</CardGroup>

### Custom commands

You can create custom commands by adding Markdown files to:

* `~/.config/opencode/commands/` for user commands (prefixed with `user:`)
* `.opencode/commands/` in your project for project-specific commands (prefixed with `project:`)

Custom commands support named arguments using the `$NAME` placeholder format:

```markdown theme={null}
# Fetch Context for Issue $ISSUE_NUMBER

RUN gh issue view $ISSUE_NUMBER --json title,body,comments
RUN git grep --author="$AUTHOR_NAME" -n .
```

When executed, OpenCode prompts you to enter values for each placeholder.

<Tip>
  Organize commands in subdirectories like `commands/git/commit.md` to create hierarchical command IDs like `user:git:commit`.
</Tip>

## File picker

Press `Ctrl+F` to open the file picker dialog:

* Navigate directories using arrow keys
* Select files to attach to your message
* Press `Enter` to confirm selection
* Press `Esc` to close without attaching

Attached files provide context to the AI about specific code or documentation.

## Theme customization

Press `Ctrl+T` to open the theme switcher:

* Browse available themes (OpenCode, Catppuccin, Dracula, Gruvbox, etc.)
* Press `Enter` to apply a theme
* Press `Esc` to close without changing

You can also set a default theme in your configuration:

```json theme={null}
{
  "tui": {
    "theme": "catppuccin"
  }
}
```

## Canceling operations

When the AI is processing (indicated by a spinner):

* Press `Ctrl+X` to cancel the current operation
* The agent stops generating and waits for your next input

<Warning>
  Canceling interrupts the AI mid-stream. Use this when the assistant is heading in the wrong direction or taking too long.
</Warning>

## Viewing logs

Press `Ctrl+L` to view application logs:

* See debug information, errors, and warnings
* Navigate using standard viewport controls
* Press `Esc`, `Backspace`, or `q` to return to chat

<Note>
  Enable debug logging with the `-d` flag when starting OpenCode to see more detailed log messages.
</Note>

## Permission system

When the AI attempts to perform actions (run commands, edit files, fetch URLs), OpenCode displays a permission dialog:

* **Allow (a)**: Grant permission for this single action
* **Allow for session (s)**: Grant permission for all similar actions in this session
* **Deny (d)**: Reject the action

Use `←`/`→` or `Tab` to switch between options, then press `Enter` to confirm.

<Tip>
  The permission dialog shows a preview of the action (command to run, diff to apply, etc.) so you can review before approving.
</Tip>

## Help dialog

Press `Ctrl+?` or `?` (when not editing) to view all available keyboard shortcuts organized by context.

## Exiting OpenCode

Press `Ctrl+C` to show the quit confirmation dialog:

* Press `Ctrl+C` again to confirm and exit
* Press any other key to cancel and continue

Your session is automatically saved when you exit.