Smart Title Plugin

Auto-generates meaningful session titles for your OpenCode conversations using AI. Published as @frankhommers/opencode-smart-title.

Highlights

• Custom title formatting with placeholders like {cwdTip} and {cwdTip:git}
• Custom prompt support for title style or language
• Directory exclusion for background or noisy automation sessions
• Safer config parsing and merging
• Better model-selection diagnostics when generation fails or slows down

Install

Add to your OpenCode config (~/.config/opencode/opencode.json for global, or .opencode/opencode.json for per-project):

{
  "plugin": ["@frankhommers/opencode-smart-title"]
}

OpenCode installs the plugin automatically on next startup. Updates are picked up automatically too.

To pin a specific version: "@frankhommers/opencode-smart-title@0.3.0"

Quick Start

Configure it globally in ~/.config/opencode/smart-title.jsonc:

{
  "enabled": true,
  "debug": false,
  "prompt": "Generate short Dutch titles for this conversation.",
  "updateThreshold": 1,
  "excludeDirectories": ["/Users/frankhommers/.heartbeat"],
  "titleFormat": "[{cwdTip}] {title}"
}

The plugin also supports project-level overrides in .opencode/smart-title.jsonc.

How It Works

• Listens for OpenCode session.status events
• Waits until the session becomes idle
• Skips subagent sessions and excluded directories
• Builds a compact conversation summary
• Selects a configured model or falls back to authenticated providers
• Generates a title and applies your titleFormat

Configuration Reference

Global config: ~/.config/opencode/smart-title.jsonc

Project config: .opencode/smart-title.jsonc

Project config overrides global config.

{
  "enabled": true,
  "debug": false,
  // Optional: specific model in provider/model format
  // "model": "anthropic/claude-haiku-4-5",
  // Optional: custom prompt for title generation
  // "prompt": "Generate a short descriptive title for this conversation.",
  // Update title every N idle events
  "updateThreshold": 1,
  // Optional: skip title generation in these directories
  // "excludeDirectories": ["/home/user/.heartbeat"],
  // Format the final title
  "titleFormat": "{title}"
}

Options

• enabled: turns the plugin on or off
• debug: writes detailed logs to the Smart Title log directory
• model: forces a specific provider/model choice before fallbacks are tried
• prompt: changes the generation instruction, useful for language or tone
• updateThreshold: controls how many idle events must happen before a title update runs
• excludeDirectories: skips sessions whose directory matches one of the configured prefixes
• titleFormat: formats the final title after AI generation

Title Format Examples

Available placeholders:

• {title} - AI-generated title
• {cwd} - full working directory path
• {cwdTip} - last folder name
• {cwdTip:N} - last N path segments
• {cwdTip:N:sep} - last N path segments joined with a custom separator
• {cwdTip:git} - path segments from git root to the current working directory
• {cwdTip:git:sep} - same as above with a custom separator

Format	Example Output
{title}	Debugging API errors
[{cwdTip}] {title}	[my-project] Debugging API errors
[{cwdTip:2}] {title}	[github/my-project] Debugging API errors
[{cwdTip:2: - }] {title}	[github - my-project] Debugging API errors
[{cwdTip:git}] {title}	[my-project] Debugging API errors
[{cwdTip:git: - }] {title}	[src - components] Debugging API errors
{title} ({cwdTip})	Debugging API errors (my-project)

How updateThreshold Works

The plugin counts idle events per session.

• 1 - update on every idle pause
• 2 - update on every second idle pause
• 3 - update on every third idle pause

Example with updateThreshold: 3:

• idle #1 -> no update
• idle #2 -> no update
• idle #3 -> update
• idle #4 -> no update
• idle #5 -> no update
• idle #6 -> update

Use lower values for faster title updates and higher values to reduce churn or model usage.

Local Development

For local testing, you can point OpenCode directly at the built file instead of the npm package:

{
  "plugin": [
    "file:///absolute/path/to/opencode-smart-title/dist/index.js"
  ]
}

Useful commands:

npm install
npm run typecheck
npm run build

Publishing

Publish a new version with:

npm version patch
npm publish --access public

You can also bump versions manually in package.json if you prefer.

Origins and Acknowledgements

This project is based on Tarquinen/opencode-smart-title by Dan Mindru.

It incorporates ideas and code from the following upstream contributions:

• PR #5 - titleFormat config with placeholder support ({title}, {cwd}, {cwdTip}, {cwdTip:N}, {cwdTip:git})
• PR #8 - Custom prompt, excludeDirectories, and robust config parsing (by @the3asic)
• PR #9 - Enhanced model-selection error logging and timing diagnostics (by @the3asic)

License

MIT