Correct CLI --continue --session syntax for persisting sessions is malfunctioning.

Description

Howdy OpenCoders. This is an easy one, and most likely either a corrupted opencode functionality or a badly configured configuration from my stupider days.

The question is how to persist a session across multiple prompts from my using the CLI.
The docs indicate that the proper syntax requires --continue and --session.

Caveats:

if the --session flag is not used the opencode platform will find the most recent session and continue that
the first message to opencode can force create any session as long as that session_id starts with "ses_"
-- this is particularly useful when driving new opencode sessions from external uuid constraints.

Anyway. The syntax is simple so that just needs double checking.
As you can see from the terminal logs below, the opencode run is definitely not persisting across calls.
What should we do?
Let's double check, and debug together.
PS these operations are being conducted from my LLC so I hope no spoliating factors are langoliering my logerinos!

.
.
.
.
You can see from this shorter exchange below that the session persistence is definitely malfunctioning.

Thanks.
Jazzed about testing out the new Code-Reviewer agent.

This issue might be a duplicate of existing issues. Please check:

--continue doesn't always continue the project's previous session #4378: --continue doesn't always continue the project's previous session
Bug: opencode --continue --prompt does not work #8850: opencode --continue --prompt does not work

Feel free to ignore if none of these address your specific case.

(I don't know if it believing I sent 4 message prior to the last one is because the model sucks at math or perhaps opencode injected a user message or it's counting the system prompt?.. anyhow!)

The above is with v1.1.48 - I wonder what version you're running.
Notice I was using one of -c (2nd and 3rd messages) or -s (4th message).

Also found this:

opencode/packages/opencode/src/cli/cmd/run.ts

Lines 356 to 361 in b39c1f1

    
           const sessionID = await (async () => { 
        
             if (args.continue) { 
        
               const result = await sdk.session.list() 
        
               return result.data?.find((s) => !s.parentID)?.id 
        
             } 
        
             if (args.session) return args.session

where if you pass -c, -s is ignored (regardless of the short or long form).

Perhaps they should be made mutually exclusive to avoid confusion.

Thanks for inspecting the code. I did as well, and I agree with you.
Using --continue will deploy the most recent session_id, regardless of whether the --session flag has been used with a different session_id. The --continue flag takes precedence with the most recent session_id.

I also read the logic to MessageV2.toModelMessages() which is responsible for constructing the "context" for the next request to the LLM. It is unfortunately much more nuanced with hard won adaptations than simply reconstructing linear parts of the individual logs from opencode run --format json.

opencode/packages/opencode/src/session/message-v2.ts

Line 438 in d35956f

    
           export function toModelMessages(input: WithParts[], model: Provider.Model): ModelMessage[] {

I read through to see how much I would want to replicate, and also had OpenCode inspect the OpenCode repository and as usual congratulations; when the software works it works. I do wish OpenCode offered a command line utility for reconstructing this information from the multitude of logs directly. It is more complicated than it is accessible to the average public, which makes me really wishful how best to offline manage the construction of contexts from the opencode run --format json outputs themselves.

For those who want more information:

Context Construction Process Flow

Step 1: Message Collection and Filtering

In SessionPrompt.loop() around Line 276:

let msgs = await MessageV2.filterCompacted(MessageV2.stream(sessionID))

Step 2: Last Message Analysis (Lines 278-293)

Finds the most recent user and assistant messages to understand conversation state.

Step 3: Reminder Injection (Lines 519-596)

The insertReminders() function adds system reminders and plan mode instructions.

Step 4: Tool Resolution (Lines 560-568)

The resolveTools() function determines which tools are available for the LLM.

Step 5: Message Processing (Lines 600-619)

CRITICAL CONTEXT BUILDING CODE:

const result = await processor.process({
  user: lastUser,
  agent,
  abort,
  sessionID,
  system: [...(await SystemPrompt.environment(model)), ...(await InstructionPrompt.system())],
  messages: [
    ...MessageV2.toModelMessages(sessionMessages, model),  // <- KEY CONVERSION
    ...(isLastStep ? [{ role: "assistant" as const, content: MAX_STEPS }] : []),
  ],
  tools,
  model,
})

Step 6: Message to Model Format Conversion

The most important context conversion happens in MessageV2.toModelMessages() (Lines 345-500 in message-v2.ts):

Processes each message part (text, file, tool, reasoning)
Converts internal message format to AI SDK's ModelMessage format
Handles tool calls, attachments, and content transformation
Filters out ignored parts and manages compaction state

Step 7: System Prompt Assembly (Lines 5-50 in system.ts)

Environment context includes:

Working directory
Git repository status
Platform information
Current date
File tree (limited to 200 files)

Step 8: Context Overflow Management

When context exceeds limits, SessionCompaction.isOverflow() triggers compaction:

Summarizes old messages
Prunes tool call outputs
Maintains conversation context within model limits

Key Plugin Hooks for Context Modification

experimental.chat.messages.transform (Line 598 in prompt.ts): Allows plugins to modify messages before LLM call
experimental.chat.system.transform (Line 358 in llm.ts): Allows plugins to modify system prompts
experimental.session.compacting (Line 134 in compaction.ts): Allows plugins to influence context compaction

Context Construction Logic Summary

The context construction process follows this sequence:

Message Collection → Gather conversation history with filtering
Message Analysis → Identify relevant user/assistant messages
Tool Resolution → Determine available tools based on permissions
System Prompt Building → Add environment context and provider instructions
Message Format Conversion → Convert internal MessageV2 format to ModelMessage format
Plugin Transformations → Apply plugin-based modifications
Context Assembly → Combine system prompts, conversation history, and tools
LLM Call → Send constructed context to the language model
Overflow Management → Compact context if it exceeds model limits

The MessageV2.toModelMessages() function is the most critical piece for understanding how message objects are converted into LLM context, as it handles all the complex logic for transforming internal message parts into the final format that language models can understand.

This ticket can be closed, yes?
The result of the analysis is:

--continue overrides --session when both are present. this should be made clear in the documentation
the internal logs => context function await MessageV2.filterCompacted is not well documented and not in the scope of this ticket

Thanks.

Related edge case: when using --continue and there is no prior session in the directory, opencode returns a non-fatal JSON error instead of gracefully starting a fresh session:

{
  "data": {
    "sessionID": "dummy"
  },
  "error": [
    {
      "origin": "string",
      "code": "invalid_format",
      "format": "starts_with",
      "prefix": "ses",
      "path": ["sessionID"],
      "message": "Invalid string: must start with \"ses\""
    }
  ],
  "success": false
}

The process does not exit with a non-zero code, so a shell fallback like opencode --continue || opencode never triggers the second branch. Expected behavior: --continue with no existing session should either silently start a new session, or exit non-zero so callers can handle it.

Reproducible with opencode --model <model> --continue in a directory with no prior opencode sessions. Running v1.14.29 on macOS.

To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.

Navigation Menu

Repository navigation

Correct CLI --continue --session syntax for persisting sessions is malfunctioning. #11680

Description

Context Construction Process Flow

Step 1: Message Collection and Filtering

Step 2: Last Message Analysis (Lines 278-293)

Step 3: Reminder Injection (Lines 519-596)

Step 4: Tool Resolution (Lines 560-568)

Step 5: Message Processing (Lines 600-619)

Step 6: Message to Model Format Conversion

Step 7: System Prompt Assembly (Lines 5-50 in system.ts)

Step 8: Context Overflow Management

Key Plugin Hooks for Context Modification

Context Construction Logic Summary

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	const sessionID = await (async () => {
	if (args.continue) {
	const result = await sdk.session.list()
	return result.data?.find((s) => !s.parentID)?.id
	}
	if (args.session) return args.session

Correct CLI --continue --session syntax for persisting sessions is malfunctioning. #11680

Description

Description

Activity

github-actions commented on Feb 1, 2026

justfortheloveof commented on Feb 1, 2026

davidbernat commented on Feb 2, 2026

Context Construction Process Flow

Step 1: Message Collection and Filtering

Step 2: Last Message Analysis (Lines 278-293)

Step 3: Reminder Injection (Lines 519-596)

Step 4: Tool Resolution (Lines 560-568)

Step 5: Message Processing (Lines 600-619)

Step 6: Message to Model Format Conversion

Step 7: System Prompt Assembly (Lines 5-50 in system.ts)

Step 8: Context Overflow Management

Key Plugin Hooks for Context Modification

Context Construction Logic Summary

davidbernat commented on Mar 13, 2026

gosuto-inzasheru commented on Apr 29, 2026

github-actions commented on Jul 3, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions