opencode-zellij-namer

AI-powered dynamic Zellij session naming for OpenCode.

Automatically renames your Zellij terminal sessions based on what you're working on — project name, task type (feat, fix, debug, etc.), and contextual tags derived from your activity.

The plugin automatically renamed this session to basicsetup-feat-namer — project directory (basicsetup), intent (feat), and contextual tag (namer).

Features

• Automatic naming: Sessions named like myproject-feat-auth or api-debug-cache
• AI-powered: Uses Gemini 3 Flash to generate contextual, meaningful names
• AGENTS.md aware: Reads project-specific naming conventions from your repo's AGENTS.md
• Custom instructions: Personal naming preferences via env var (override AGENTS.md)
• Non-blocking: Fire-and-forget design never slows down your workflow
• Stability-first: Debouncing and cooldowns prevent name thrashing
• Privacy-conscious: Only sends minimal context to AI (see Privacy)
• Fallback heuristics: Works without AI using pattern matching

Installation

# Install globally
npm install -g opencode-zellij-namer

# Or add to your OpenCode config

Add to your ~/.config/opencode/opencode.json:

{
  "plugin": ["opencode-zellij-namer"]
}

Configuration

All configuration is via environment variables:

Variable	Default	Description
GEMINI_API_KEY	-	Google AI API key for smart naming
OPENCODE_ZELLIJ_DEBUG	0	Set to 1 for debug logging
OPENCODE_ZELLIJ_COOLDOWN_MS	300000	Minimum ms between renames (5 min)
OPENCODE_ZELLIJ_DEBOUNCE_MS	5000	Debounce interval for checks (5 sec)
OPENCODE_ZELLIJ_MODEL	gemini-3-flash-preview	Gemini model to use
OPENCODE_ZELLIJ_MAX_SIGNALS	25	Max activity signals to retain
OPENCODE_ZELLIJ_TIMEOUT_MS	3000	AI request timeout
OPENCODE_ZN_INSTRUCTIONS	-	Custom naming instructions for AI
OPENCODE_ZN_USE_AGENTS_MD	1	Set to 0 to disable AGENTS.md reading

AGENTS.md Integration

The plugin automatically reads naming guidance from your project's AGENTS.md file. This allows you to define project-specific naming conventions that all contributors will follow.

Supported locations (checked in order):

• ./AGENTS.md
• ./.github/AGENTS.md
• ./docs/AGENTS.md

Extracted sections (by priority):

1. ## Naming or ## Session Naming — entire section content
2. ## Guidelines — lines containing "naming", "session", "tag", or "intent"

Example AGENTS.md:

# My Project

## Session Naming

- Use team prefix "acme-" for all sessions
- Prefer ticket numbers as tags (e.g., acme-feat-jira123)
- Use "api" instead of "backend" for backend work

The plugin extracts this guidance and includes it in the AI prompt.

To disable: Set OPENCODE_ZN_USE_AGENTS_MD=0

Custom Instructions

You can provide custom instructions to guide the AI naming:

export OPENCODE_ZN_INSTRUCTIONS="Use short codenames. Prefer 'api' over 'backend'. Always include ticket numbers from todos."

This is useful for:

• Enforcing team naming conventions
• Using project codenames instead of directory names
• Prioritizing certain context (e.g., ticket numbers)
• Adjusting tag preferences

Precedence

When both AGENTS.md and custom instructions are present:

1. AGENTS.md — Project-level guidance (shared with team)
2. Custom Instructions — User-level overrides (personal preference)

Custom instructions take precedence over AGENTS.md when they conflict. This allows teams to define baseline conventions in AGENTS.md while individual developers can customize for their workflow.

Example

export GEMINI_API_KEY="your-api-key"
export OPENCODE_ZELLIJ_DEBUG=1
export OPENCODE_ZELLIJ_COOLDOWN_MS=600000  # 10 minutes

How It Works

Naming Format

project-intent[-tag]

• project: From package.json name, git repo, or directory (max 20 chars)
• intent: One of feat, fix, debug, refactor, test, doc, ops, review, spike
• tag: Optional context like auth, api, cache (max 15 chars)

Examples

Activity	Generated Name
Working on new feature	myapp-feat
Debugging auth issues	myapp-debug-auth
Writing tests	api-test
Refactoring database code	backend-refactor-db
Reviewing PR	frontend-review

Trigger Events

The plugin listens to these OpenCode events:

• session.idle — After each AI turn completes
• file.edited — When you edit files
• command.executed — When you run commands
• todo.updated — When todos change

Stability Mechanisms

• Debounce: 5-second minimum between checks
• Cooldown: 5-minute minimum between actual renames
• Signal accumulation: Builds context over time for better naming

Uniqueness

While Zellij allows duplicate session names, this plugin attempts to generate unique names to help you distinguish between multiple sessions working on the same project.

Disambiguation strategy:

1. Branch name: If on feat/user-auth, adds -auth tag
2. Directory context: Working in src/payments/ adds -payments tag
3. Task keywords: Todo mentioning "caching" adds -cache tag
4. Time-based: Falls back to -am/-pm/-eve based on time of day
5. Numeric suffix: Last resort adds -2, -3, etc.

Example scenario:

Session	Context	Generated Name
Terminal 1	Working on auth	myapp-feat-auth
Terminal 2	Same project, payments	myapp-feat-payments
Terminal 3	Same project, morning	myapp-feat-am

This ensures you can identify which terminal is which at a glance, even with multiple sessions on the same project.

Privacy

When AI naming is enabled, the following data is sent to Google's Gemini API:

Data	Example	Purpose
Project name	myapp	Anchor for session name
Recent file paths	src/auth/login.ts	Infer working area
Command names	npm test	Infer task type
Todo summaries	fix login bug	Infer intent
Conversation snippets	debug the auth flow	Contextual naming

What is NOT sent:

• File contents
• Command output
• Full conversation history
• Environment variables
• System information

To disable AI: Simply don't set GEMINI_API_KEY. The plugin falls back to heuristic naming.

Requirements

• OpenCode v0.1.0+
• Zellij terminal multiplexer
• Node.js 18+
• (Optional) Google AI API key for smart naming

Troubleshooting

Plugin not loading

Check OpenCode logs for errors. Enable debug mode:

export OPENCODE_ZELLIJ_DEBUG=1

Session not renaming

1. Verify you're inside a Zellij session: echo $ZELLIJ_SESSION_NAME
2. Check Zellij is in PATH: which zellij
3. Wait for cooldown period (default 5 min)

AI naming not working

1. Verify API key: echo $GEMINI_API_KEY
2. Check network connectivity
3. Enable debug logging to see AI responses

Development

Fork & Clone

1. Fork this repo on GitHub
2. Clone your fork:

git clone https://github.com/YOUR_USERNAME/opencode-zellij-namer
cd opencode-zellij-namer

3. Update package.json with your fork's URL:

# Replace YOUR_USERNAME with your GitHub username
sed -i 's/24601/YOUR_USERNAME/g' package.json

Build & Test

npm install
npm run build
npm test

Local Development

To test your changes with OpenCode, update your config to point to your local build:

{
  "plugin": ["/path/to/your/opencode-zellij-namer"]
}

License

MIT — see LICENSE

Contributing

See CONTRIBUTING.md