opencode-autotitle

AI-powered automatic session naming for OpenCode.

Automatically generates descriptive titles for your OpenCode sessions based on conversation context, replacing generic timestamp-based names like "2024-01-15 14:30" with meaningful descriptions like "Setup React Auth Flow".

From Timestamp Chaos to Meaningful Titles

Before	After

Features

• Two-phase titling: Instant keyword title on user message, refined AI title after response
• AI-powered: Auto-selects cheapest available model (flash/haiku/fast) for title generation
• Instant feedback: Keyword-based title appears immediately, no waiting for AI
• Zero configuration: Works out of the box with sensible defaults
• Non-blocking: Runs in the background, never slows your workflow
• Respects custom titles: Won't overwrite manually set session names

Installation

Quick Install (Recommended)

Option 1: Let your AI agent install it

Paste this into OpenCode, Claude Code, Cursor, or any AI coding assistant:

Install opencode-autotitle by following the instructions here:
https://raw.githubusercontent.com/pawelma/opencode-autotitle/refs/heads/master/docs/install.md

Option 2: One-liner

curl -fsSL https://raw.githubusercontent.com/pawelma/opencode-autotitle/refs/heads/master/install.sh | bash

Manual Installation

OpenCode loads plugin files directly from ~/.config/opencode/plugins/.

# Clone, build, and copy the plugin file
tmp_dir=$(mktemp -d)
git clone --depth 1 https://github.com/pawelma/opencode-autotitle "$tmp_dir"
cd "$tmp_dir" && npm install && npm run build
mkdir -p ~/.config/opencode/plugins
cp dist/index.js ~/.config/opencode/plugins/opencode-autotitle.js
rm -rf "$tmp_dir"

How It Works

The plugin uses a two-phase approach for instant feedback with quality refinement:

┌─────────────────────────────────────────────────────────────────────────┐
│                         OPENCODE SESSION                                │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  PHASE 1: Quick Title (on message.part.updated)                         │
│  ───────────────────────────────────────────────────────────────────────│
│                                                                         │
│   User types message ──► Extract keywords ──► Set title immediately     │
│                                                                         │
│   "Help me set up JWT auth"  ──►  "🔍 Jwt Auth Express"                 │
│                                                                         │
│   • No API call needed                                                  │
│   • Instant title update                                                │
│   • Uses keyword extraction + stop word filtering                       │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  PHASE 2: AI Title (on session.idle)                                    │
│  ───────────────────────────────────────────────────────────────────────│
│                                                                         │
│   AI responds ──► Find cheap model ──► Generate title ──► Update        │
│                                                                         │
│   Context: user question + AI response                                  │
│                                                                         │
│   "🔍 Jwt Auth Express"  ──►  "✨ Setup JWT Auth Express"               │
│                                                                         │
│   • Uses cheapest available model (flash/haiku/fast)                    │
│   • Creates temp session for title generation                           │
│   • More specific title based on actual conversation                    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  RESULT                                                                 │
│  ───────────────────────────────────────────────────────────────────────│
│                                                                         │
│   🔍 = Keyword-based title (fast fallback)                              │
│   ✨ = AI-generated title (final quality)                               │
│                                                                         │
│   Custom user titles are never overwritten                              │
└─────────────────────────────────────────────────────────────────────────┘

State Management

┌──────────────────────────────────────────────────────────────┐
│                      Plugin State                            │
├──────────────────────────────────────────────────────────────┤
│  keywordTitledSessions: Set<string>   ← Has 🔍 title         │
│  aiTitledSessions: Set<string>        ← Has ✨ title (done)  │
│  pendingAISessions: Set<string>       ← Currently processing │
│  cheapestModel: cached model choice   ← Lazily discovered    │
└──────────────────────────────────────────────────────────────┘

Title Generation

Phase 1 sets a quick keyword title, Phase 2 refines it with AI:

Configuration

All configuration is optional. The plugin works out of the box.

Environment Variables

Model Selection

By default, the plugin auto-discovers the cheapest available model from your connected providers, preferring models with names like fast, flash, haiku, or mini. To use a specific model:

export OPENCODE_AUTOTITLE_MODEL="anthropic/claude-haiku-4-5"

Debugging

Enable debug mode to see what's happening:

export OPENCODE_AUTOTITLE_DEBUG=debug.log
opencode
# In another terminal: tail -f debug.log

Look for [autotitle] messages in the output.

Development

# Clone the repository
git clone https://github.com/pawelma/opencode-autotitle
cd opencode-autotitle

# Install dependencies
bun install

# Build
bun run build

# Watch mode
bun run dev

# Type check
bun run typecheck

Inspirations

This project was inspired by and builds upon ideas from:

• oh-my-opencode - The comprehensive OpenCode enhancement suite that pioneered the agent-assisted installation pattern and demonstrated what's possible with OpenCode plugins. The installation documentation approach used here is directly inspired by their excellent developer experience.

• opencode-zellij-namer - AI-powered Zellij session naming plugin that showed how to elegantly combine AI generation with fallback heuristics for naming. The signal collection and intent inference patterns in this plugin were influenced by their implementation.

Thank you to the maintainers and contributors of these projects for sharing their work with the community.

License

MIT - see LICENSE

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Note: Currently tested with the GitHub Copilot provider only.