Auto Title Plugin

The Auto Title plugin gives each conversation a meaningful, LLM-generated title
automatically — and, optionally, watches for the discussion drifting away from
that title and suggests a fresh one.

Topic-shift retitling is experimental. Defaults are conservative: first-turn
naming on, topic-shift retitling off.

Overview

1. First-turn naming (on by default). When a conversation that has no title finishes its first turn, the plugin names it from the user's message and the assistant's reply. The title is generated in the same language the user wrote in.
2. Topic-shift retitling (opt-in). After later turns it can ask whether the topic has shifted. Short conversations (below min_context_chars_for_shift, default 10 000 characters) skip this check. On a shift, it renames the conversation and posts a transcript card suggesting that a new conversation for the new topic usually works better.

The sidebar (and other open tabs) updates live — no refresh needed. Titling
runs in the background, so the title may appear a moment after the reply.

It only runs in the web/API UI (where conversations have titles). In the
CLI/TUI it does nothing.

Configuration

plugins:
  - module: codumentor.plugins.auto_title
    class: AutoTitlePlugin
    args:
      enabled: true
      name_after_first_turn: true
      max_title_chars: 60
      extra_instruction: ""
      rename_on_topic_shift: false
      topic_shift_turns: 2
      min_context_chars_for_shift: 10000
      model_role: auto_title
      temperature: 0.3
      max_tokens: 200
      request_timeout_seconds: 60.0

Parameters

• enabled (optional): Master switch (default: true)
• name_after_first_turn (optional): Generate an initial title once an untitled conversation finishes its first turn (default: true)
• max_title_chars (optional): Hard cap on generated title length, in characters. Values below 10 are raised to 10 (default: 60)
• extra_instruction (optional): Extra guidance appended to the prompts — style, or a language ("Always answer in Hungarian.") (default: "")
• rename_on_topic_shift (optional): After each turn, detect topic drift; if so, retitle and show a card (default: false)
• topic_shift_turns (optional): How many recent (user, assistant) exchanges to show when judging a shift. Values below 1 are raised to 1 (default: 2)
• min_context_chars_for_shift (optional): Minimum conversation length (characters) before topic-shift detection runs. 0 always checks (default: 10000)
• model_role (optional): Model-profile role for the title calls. Falls back to the global agent model when the role is not configured (default: "auto_title")
• temperature (optional): Sampling temperature (default: 0.3)
• max_tokens (optional): Max tokens for the title calls (default: 200)
• request_timeout_seconds (optional): Timeout for the background title call. Values below 1 are raised to 1 (default: 60.0)

The topic-shift card

When a shift is detected, a transcript card appears:

• Collapsed: a short hint plus the new title, e.g. "Database migration — New topic: “Postgres → SQLite migration”".
• Expanded: the previous title, the updated title, and a tip that starting a fresh conversation for a new topic tends to give sharper results.

Notes

• If the title call fails, times out, or returns an empty/identical title, nothing changes — failures never affect the turn.
• A title the user set manually is never overwritten. First-turn naming only runs on an untitled conversation, and topic-shift retitling backs off after a manual rename. Automatic titles can still be replaced by a later topic-shift retitle.
• Scheduled / goal-worker conversations are titled "<schedule name> — <YYYY-MM-DD>" (UTC date) without an LLM call.