Session

What it is

A session is a single, continuous conversation with an OpenCode agent. It tracks every message, tool call, and file change from the moment you start talking until you close or switch away. Think of it as a chat thread with memory.

What it is in real OpenCode terms

When you launch OpenCode or start a new conversation, a session is created with a unique ID. That session accumulates the full history: your prompts, the agent's responses, every tool invocation (file reads, bash commands, searches), and all output.

Sessions are stored locally on disk. They are not uploaded anywhere. This is a privacy-by-design choice — your conversation data stays on your machine.

You can resume a specific session later using its ID, or let OpenCode continue the most recent one automatically.

Why it exists

• Continuity. The agent remembers what you discussed, what files you edited, and what decisions you made.
• Resumability. Close your terminal, come back tomorrow, pick up exactly where you left off.
• Isolation. Different tasks get different sessions, so context from one project does not leak into another.
• Compaction. When the conversation gets too long for the LLM's context window, OpenCode can summarize and compress it without losing the thread.

Anatomy / main elements

A session contains:

• Session ID - a unique identifier for resuming later
• Message history - alternating user prompts and assistant responses
• Tool calls and outputs - every file read, bash command, search result, etc.
• File change tracking - what files were modified during the session
• Compaction state - if the session was compacted, the summary replaces older messages

Sessions can also have child sessions created by subagents. These are nested conversations that a subagent runs independently, then reports results back to the parent.

Where it lives

Sessions are stored locally. The exact location depends on your OS and OpenCode configuration, but they persist in the OpenCode data directory.

Key commands for working with sessions:

# Continue the most recent session
opencode --continue

# Resume a specific session by ID
opencode --session <session-id>

# Share the current session (creates a shareable link)
/share

How to create one

You do not create sessions manually. They are created automatically:

1. Start OpenCode — a new session is created
2. Type a message — the session begins accumulating history
3. Exit and re-enter — use --continue to resume, or start fresh

If you want to explicitly start a new session while one is active, start a fresh OpenCode instance without the --continue flag.

Minimal example

A typical session lifecycle:

# Start a new session
opencode

# You and the agent discuss a bug fix, edit files, run tests.
# The session tracks everything.

# Exit OpenCode

# Come back later, resume the same session
opencode --continue

# The agent remembers your previous conversation and file changes.

Navigating child sessions (if subagents are used):

# Enter a child session
Leader + Down

# Cycle between child sessions
Right / Left

# Return to parent session
Up

Related concepts

Common confusion