Dynamic, compact terminal tab titling that follows what your AI agents are actively working on.

Works locally with Antigravity, Claude Code, Codex, and OpenCode — zero external API keys needed.

---

🤖 One-Shot Agent Install Prompt

Give this prompt to Claude Code, Antigravity CLI, Cursor, or Codex:

Set up Herdr Agent Titler for me. Read https://github.com/killerz3/herdr-agent-titler/blob/main/AGENTS.md and follow its instructions to guide me through setup.

---

⚡ Quick Start

# 1. Install the plugin from GitHub
herdr plugin install killerz3/herdr-agent-titler

# 2. Start the background titler service
herdr plugin action invoke start --plugin herdr.agent-titler

# 3. Verify active harness detection and status
herdr plugin action invoke status --plugin herdr.agent-titler

---

🎯 Why This Exists

Most tab titlers suffer from three flaws:

1. Require Paid API Keys: Force users to configure and pay for OpenAI/Anthropic HTTP API keys.
2. Frozen Day-1 Titles: Only inspect the initial prompt from days ago, never updating when an agent moves to new PRs or tasks.
3. Rigid Formatting: Other titlers lock you into long sentence titles that truncate in narrow sidebars, with no option to customize.

Agent Titler solves all three:

• Zero API Keys: Runs locally through your host's authenticated CLI harnesses using free/lightweight models (gemini-3.8-flash-low, claude-3-5-haiku, etc.).
• Follows Active Work: Reads live terminal screen buffers (herdr pane read) and transcript tails so titles adapt to recent recaps, PR pushes, and task changes.
• Configurable Styles: Choose between ultra-compact titles (compact, ≤18 chars entity-first) that never truncate, or full natural action phrases (descriptive).
• Smart Delta Caching: Tracks file byte offsets, mtimes, and pane revisions. Skips LLM calls entirely for idle or unchanged tabs.

---

🗂️ Configurable Title Styles

Choose the title format that fits your workflow via style = "compact" | "descriptive" | "slug" in your config (or let your agent prompt you during setup):

Active Agent Task	compact (Default, ≤18 Chars)	descriptive (Action Phrase)	slug (Hyphenated)
Fixing auth session expiration	auth service fix	fix auth session expiry	auth-session-expiry
Syncing search index cluster	search index sync	sync search index cluster	search-index-sync
Debugging payment retry failures	payment retry bug	debug payment retry logic	payment-retry-bug
Profiling marketing landing page	landing page perf	optimize landing page perf	landing-page-perf
Caching API gateway endpoints	api cache layer	cache api gateway endpoints	api-cache-layer

• compact (Small): 2–3 words, entity-first, capped at 18 characters. Recommended for narrow sidebars so titles never get cut off with ....
• descriptive (Detailed): 3–5 word natural action phrase describing the active task.
• slug (Branch style): Hyphenated lowercase format.

---

🔌 Supported Harnesses

Agent Titler detects and leverages whatever CLI harness you already have installed:

Harness	Headless Command	Default Lightweight Model
Antigravity (agy)	agy -p "<prompt>" --model <model>	gemini-3.8-flash-low
Claude Code (claude)	claude -p "<prompt>"	claude-3-5-haiku
Codex (codex)	codex exec "<prompt>"	gpt-4o-mini
OpenCode (opencode)	opencode run "<prompt>"	provider/small

Setting harness = "auto" automatically picks the first available CLI on your machine.

---

⚙️ Configuration & Customization

Settings live in config.toml inside the plugin directory or ~/.config/herdr/agent-titler.toml (see AGENTS.md for automated agent setup):

# Harness to use: "auto", "agy", "claude", "codex", "opencode"
harness = "auto"

# Automatic tab renaming toggle:
# - true: (default) automatically updates tab titles as work changes
# - false: disables tab renaming completely (read-only monitoring)
auto_rename = true

# Sync Claude Code internal session title:
# - false: (default) only renames the Herdr tab
# - true: also writes Claude's custom-title.json so `claude -r` reflects the new title
sync_claude_session = false

# Title style:
# - "compact": (default) ultra-compact 2-3 words, entity-first (e.g. "auth service fix")
# - "descriptive": 3-5 word natural action phrase (e.g. "fix auth session expiry")
# - "slug": hyphenated format (e.g. "auth-service-fix")
style = "compact"

# Max title length in characters (default: 18, fits Herdr sidebar without truncation)
max_length = 18

# Workspace prefix toggle:
# - false: (default) leaves title clean (Herdr sidebar already displays workspace name)
# - true: prefixes title with workspace, e.g. "[API]-auth service fix"
include_workspace = false

# Poll interval in seconds (default: 120)
interval_seconds = 120

# Default lightweight models
agy_model = "gemini-3.8-flash-low"
claude_model = "claude-3-5-haiku"
codex_model = "gpt-4o-mini"
opencode_model = "provider/small"

---

🛡️ Manual Rename Protection

• Herdr UI renames: If you rename a tab yourself in Herdr, Agent Titler locks it and will never overwrite your custom title.
• Claude Code /rename: If you run /rename <name> in Claude Code, Agent Titler adopts that custom session name and locks it against LLM overwrite.
• Releasing a lock: Simply clear the tab title in Herdr (or set it back to its position number), and Agent Titler will resume auto-titling it.

---

🛠️ Plugin Actions

Control the titler directly through the Herdr CLI:

# Check status and active harness detection
herdr plugin action invoke status --plugin herdr.agent-titler

# Run a single one-shot scan pass
herdr plugin action invoke once --plugin herdr.agent-titler

# Start background daemon
herdr plugin action invoke start --plugin herdr.agent-titler

# Stop background daemon
herdr plugin action invoke stop --plugin herdr.agent-titler

---

📄 License

MIT © Shubhveer Singh Chaudhary