opencode-auto-title-fallback

OpenCode plugin that patches default New session - ... titles when OpenCode's built-in title agent does not run.

This is a fallback plugin, not an official OpenCode fix. It only acts when a top-level session still has the default OpenCode title after the first assistant response completes.

Why

OpenCode normally creates titles through its hidden built-in title agent. In some lifecycle/config edge cases, the title agent may not launch and the session keeps a placeholder title.

This plugin detects that missed state and asks OpenCode itself to generate a title with a temporary scratch child session. It then patches the parent session title and deletes the scratch session. It can retry default-titled sessions after multiple turns, so a missed first pass does not leave the session stuck forever.

Features

• LLM-generated titles, not deterministic string truncation.
• Prompt-injection resistant title prompt: the user message is quoted as data.
• Default title language is English.
• Optional install-time choice to match the prompt language.
• No provider secrets handled by the plugin. It uses OpenCode's own local session API.
• Can repair default titles even after multiple real user messages.
• Strips common OpenCode/Magic Context scaffolding before title generation.

Install

From npm after the package is published:

npm install -g opencode-auto-title-fallback
opencode-auto-title-fallback-install

From GitHub source:

npm install -g github:nxxxsooo/opencode-auto-title-fallback
opencode-auto-title-fallback-install

The installer asks:

Title language? [Enter = English, a = match prompt language]:

• Press Enter for English titles. This is the default.
• Type a to generate titles in the same language as the first user prompt.

Restart OpenCode after installation.

Manual config

Add the plugin to ~/.config/opencode/opencode.jsonc or ~/.config/opencode/opencode.json:

{
  "plugin": [
    [
      "opencode-auto-title-fallback@latest",
      {
        "language": "english"
      }
    ]
  ]
}

To match the prompt language:

{
  "plugin": [
    [
      "opencode-auto-title-fallback@latest",
      {
        "language": "auto"
      }
    ]
  ]
}

Options

| Option | Default | Description | | --- | --- | --- | | providerID | qwen-coding-plan | OpenCode provider used by the scratch title session. | | modelID | qwen3-coder-next | Model used by the scratch title session. Prefer a cheap non-reasoning model. | | language | english | english or auto. English is default. | | maxLength | 50 | Maximum title length. | | delayMs | 250 | Delay after assistant text completes before checking title state. | | sourceCharLimit | 12000 | Maximum cleaned user-message characters sent to the title model. |

Example:

{
  "plugin": [
    [
      "opencode-auto-title-fallback@latest",
      {
        "providerID": "anthropic",
        "modelID": "claude-haiku-4-5",
        "language": "auto",
        "maxLength": 60
      }
    ]
  ]
}

How it works

1. Waits for assistant text completion or session.idle.
2. Checks whether the session title is still OpenCode's default placeholder.
3. Skips child sessions, but no longer requires exactly one real user message.
4. Builds a cleaned title source from real user messages and strips common scaffolding.
5. Creates a temporary child session with agent: "title".
6. Sends the cleaned message source as quoted <messages> data.
7. Reads the generated title.
8. Patches the parent session title.
9. Deletes the scratch child session.

Limitations

• It is a workaround for missed title generation, not a replacement for OpenCode's built-in title logic.
• It uses an extra LLM call only when the built-in title remains missing.
• It depends on OpenCode's local session API and plugin hook APIs.
• It intentionally does not retitle sessions that already have non-default titles.
• It repairs only top-level OpenCode sessions; scratch and subagent child sessions are ignored.

Development

npm install
npm run check
npm run build

License

MIT