AI-powered dynamic Zellij session naming for OpenCode
npm install opencode-zellij-namerAI-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.
!Screenshot showing Zellij session renamed to basicsetup-feat-namer
The plugin automatically renamed this session to basicsetup-feat-namer — project directory (basicsetup), intent (feat), and contextual tag (namer).
- 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
``bashInstall globally
npm install -g opencode-zellij-namer
Add to your
~/.config/opencode/opencode.json:`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 |$3
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.mdExtracted sections (by priority):
1.
## Naming or ## Session Naming — entire section content
2. ## Guidelines — lines containing "naming", "session", "tag", or "intent"Example AGENTS.md:
`markdown
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$3
You can provide custom instructions to guide the AI naming:
`bash
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
$3
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.
$3
`bash
export GEMINI_API_KEY="your-api-key"
export OPENCODE_ZELLIJ_DEBUG=1
export OPENCODE_ZELLIJ_COOLDOWN_MS=600000 # 10 minutes
`How It Works
$3
`
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)$3
| 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 |$3
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$3
- Debounce: 5-second minimum between checks
- Cooldown: 5-minute minimum between actual renames
- Signal accumulation: Builds context over time for better naming
$3
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
$3
Check OpenCode logs for errors. Enable debug mode:
`bash
export OPENCODE_ZELLIJ_DEBUG=1
`$3
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)$3
1. Verify API key:
echo $GEMINI_API_KEY
2. Check network connectivity
3. Enable debug logging to see AI responsesDevelopment
$3
1. Fork this repo on GitHub
2. Clone your fork:
`bash
git clone https://github.com/YOUR_USERNAME/opencode-zellij-namer
cd opencode-zellij-namer
`3. Update
package.json with your fork's URL:`bash
Replace YOUR_USERNAME with your GitHub username
sed -i 's/24601/YOUR_USERNAME/g' package.json
`$3
`bash
npm install
npm run build
npm test
`$3
To test your changes with OpenCode, update your config to point to your local build:
`json
{
"plugin": ["/path/to/your/opencode-zellij-namer"]
}
``MIT — see LICENSE
See CONTRIBUTING.md