{"id":34979178,"url":"https://github.com/24601/opencode-zellij-namer","last_synced_at":"2026-04-15T14:38:18.765Z","repository":{"id":329329531,"uuid":"1119140174","full_name":"24601/opencode-zellij-namer","owner":"24601","description":"AI-powered dynamic Zellij session naming plugin for OpenCode","archived":false,"fork":false,"pushed_at":"2025-12-20T01:58:22.000Z","size":91,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-21T21:53:24.972Z","etag":null,"topics":["ai","automation","cli","developer-tools","gemini","llm","opencode","plugin","productivity","session-management","terminal","terminal-multiplexer","typescript","zellij"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/24601.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-18T20:08:18.000Z","updated_at":"2025-12-20T01:58:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/24601/opencode-zellij-namer","commit_stats":null,"previous_names":["24601/opencode-zellij-namer"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/24601/opencode-zellij-namer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/24601%2Fopencode-zellij-namer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/24601%2Fopencode-zellij-namer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/24601%2Fopencode-zellij-namer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/24601%2Fopencode-zellij-namer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/24601","download_url":"https://codeload.github.com/24601/opencode-zellij-namer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/24601%2Fopencode-zellij-namer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31846416,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T13:28:40.153Z","status":"ssl_error","status_checked_at":"2026-04-15T13:28:29.396Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","cli","developer-tools","gemini","llm","opencode","plugin","productivity","session-management","terminal","terminal-multiplexer","typescript","zellij"],"created_at":"2025-12-27T00:51:39.600Z","updated_at":"2026-04-15T14:38:18.751Z","avatar_url":"https://github.com/24601.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# opencode-zellij-namer\n\nAI-powered dynamic Zellij session naming for [OpenCode](https://opencode.ai).\n\nAutomatically 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.\n\n![Screenshot showing Zellij session renamed to basicsetup-feat-namer](screenshot.png)\n\n*The plugin automatically renamed this session to `basicsetup-feat-namer` — project directory (basicsetup), intent (feat), and contextual tag (namer).*\n\n## Features\n\n- **Automatic naming**: Sessions named like `myproject-feat-auth` or `api-debug-cache`\n- **AI-powered**: Uses Gemini 3 Flash to generate contextual, meaningful names\n- **AGENTS.md aware**: Reads project-specific naming conventions from your repo's `AGENTS.md`\n- **Custom instructions**: Personal naming preferences via env var (override AGENTS.md)\n- **Non-blocking**: Fire-and-forget design never slows down your workflow\n- **Stability-first**: Debouncing and cooldowns prevent name thrashing\n- **Privacy-conscious**: Only sends minimal context to AI (see [Privacy](#privacy))\n- **Fallback heuristics**: Works without AI using pattern matching\n\n## Installation\n\n```bash\n# Install globally\nnpm install -g opencode-zellij-namer\n\n# Or add to your OpenCode config\n```\n\nAdd to your `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"plugin\": [\"opencode-zellij-namer\"]\n}\n```\n\n## Configuration\n\nAll configuration is via environment variables:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `GEMINI_API_KEY` | - | Google AI API key for smart naming |\n| `OPENCODE_ZELLIJ_DEBUG` | `0` | Set to `1` for debug logging |\n| `OPENCODE_ZELLIJ_COOLDOWN_MS` | `300000` | Minimum ms between renames (5 min) |\n| `OPENCODE_ZELLIJ_DEBOUNCE_MS` | `5000` | Debounce interval for checks (5 sec) |\n| `OPENCODE_ZELLIJ_MODEL` | `gemini-3-flash-preview` | Gemini model to use |\n| `OPENCODE_ZELLIJ_MAX_SIGNALS` | `25` | Max activity signals to retain |\n| `OPENCODE_ZELLIJ_TIMEOUT_MS` | `3000` | AI request timeout |\n| `OPENCODE_ZN_INSTRUCTIONS` | - | Custom naming instructions for AI |\n| `OPENCODE_ZN_USE_AGENTS_MD` | `1` | Set to `0` to disable AGENTS.md reading |\n\n### AGENTS.md Integration\n\nThe 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.\n\n**Supported locations** (checked in order):\n- `./AGENTS.md`\n- `./.github/AGENTS.md`\n- `./docs/AGENTS.md`\n\n**Extracted sections** (by priority):\n1. `## Naming` or `## Session Naming` — entire section content\n2. `## Guidelines` — lines containing \"naming\", \"session\", \"tag\", or \"intent\"\n\n**Example AGENTS.md:**\n\n```markdown\n# My Project\n\n## Session Naming\n\n- Use team prefix \"acme-\" for all sessions\n- Prefer ticket numbers as tags (e.g., acme-feat-jira123)\n- Use \"api\" instead of \"backend\" for backend work\n```\n\nThe plugin extracts this guidance and includes it in the AI prompt.\n\n**To disable:** Set `OPENCODE_ZN_USE_AGENTS_MD=0`\n\n### Custom Instructions\n\nYou can provide custom instructions to guide the AI naming:\n\n```bash\nexport OPENCODE_ZN_INSTRUCTIONS=\"Use short codenames. Prefer 'api' over 'backend'. Always include ticket numbers from todos.\"\n```\n\nThis is useful for:\n- Enforcing team naming conventions\n- Using project codenames instead of directory names\n- Prioritizing certain context (e.g., ticket numbers)\n- Adjusting tag preferences\n\n### Precedence\n\nWhen both AGENTS.md and custom instructions are present:\n\n1. **AGENTS.md** — Project-level guidance (shared with team)\n2. **Custom Instructions** — User-level overrides (personal preference)\n\nCustom 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.\n\n### Example\n\n```bash\nexport GEMINI_API_KEY=\"your-api-key\"\nexport OPENCODE_ZELLIJ_DEBUG=1\nexport OPENCODE_ZELLIJ_COOLDOWN_MS=600000  # 10 minutes\n```\n\n## How It Works\n\n### Naming Format\n\n```\nproject-intent[-tag]\n```\n\n- **project**: From package.json name, git repo, or directory (max 20 chars)\n- **intent**: One of `feat`, `fix`, `debug`, `refactor`, `test`, `doc`, `ops`, `review`, `spike`\n- **tag**: Optional context like `auth`, `api`, `cache` (max 15 chars)\n\n### Examples\n\n| Activity | Generated Name |\n|----------|---------------|\n| Working on new feature | `myapp-feat` |\n| Debugging auth issues | `myapp-debug-auth` |\n| Writing tests | `api-test` |\n| Refactoring database code | `backend-refactor-db` |\n| Reviewing PR | `frontend-review` |\n\n### Trigger Events\n\nThe plugin listens to these OpenCode events:\n- `session.idle` — After each AI turn completes\n- `file.edited` — When you edit files\n- `command.executed` — When you run commands\n- `todo.updated` — When todos change\n\n### Stability Mechanisms\n\n- **Debounce**: 5-second minimum between checks\n- **Cooldown**: 5-minute minimum between actual renames\n- **Signal accumulation**: Builds context over time for better naming\n\n### Uniqueness\n\nWhile Zellij allows duplicate session names, this plugin attempts to generate unique names to help you distinguish between multiple sessions working on the same project.\n\n**Disambiguation strategy:**\n\n1. **Branch name**: If on `feat/user-auth`, adds `-auth` tag\n2. **Directory context**: Working in `src/payments/` adds `-payments` tag  \n3. **Task keywords**: Todo mentioning \"caching\" adds `-cache` tag\n4. **Time-based**: Falls back to `-am`/`-pm`/`-eve` based on time of day\n5. **Numeric suffix**: Last resort adds `-2`, `-3`, etc.\n\n**Example scenario:**\n\n| Session | Context | Generated Name |\n|---------|---------|----------------|\n| Terminal 1 | Working on auth | `myapp-feat-auth` |\n| Terminal 2 | Same project, payments | `myapp-feat-payments` |\n| Terminal 3 | Same project, morning | `myapp-feat-am` |\n\nThis ensures you can identify which terminal is which at a glance, even with multiple sessions on the same project.\n\n## Privacy\n\nWhen AI naming is enabled, the following data is sent to Google's Gemini API:\n\n| Data | Example | Purpose |\n|------|---------|---------|\n| Project name | `myapp` | Anchor for session name |\n| Recent file paths | `src/auth/login.ts` | Infer working area |\n| Command names | `npm test` | Infer task type |\n| Todo summaries | `fix login bug` | Infer intent |\n| Conversation snippets | `debug the auth flow` | Contextual naming |\n\n**What is NOT sent:**\n- File contents\n- Command output\n- Full conversation history\n- Environment variables\n- System information\n\n**To disable AI**: Simply don't set `GEMINI_API_KEY`. The plugin falls back to heuristic naming.\n\n## Requirements\n\n- [OpenCode](https://opencode.ai) v0.1.0+\n- [Zellij](https://zellij.dev) terminal multiplexer\n- Node.js 18+\n- (Optional) Google AI API key for smart naming\n\n## Troubleshooting\n\n### Plugin not loading\n\nCheck OpenCode logs for errors. Enable debug mode:\n```bash\nexport OPENCODE_ZELLIJ_DEBUG=1\n```\n\n### Session not renaming\n\n1. Verify you're inside a Zellij session: `echo $ZELLIJ_SESSION_NAME`\n2. Check Zellij is in PATH: `which zellij`\n3. Wait for cooldown period (default 5 min)\n\n### AI naming not working\n\n1. Verify API key: `echo $GEMINI_API_KEY`\n2. Check network connectivity\n3. Enable debug logging to see AI responses\n\n## Development\n\n### Fork \u0026 Clone\n\n1. Fork this repo on GitHub\n2. Clone your fork:\n\n```bash\ngit clone https://github.com/YOUR_USERNAME/opencode-zellij-namer\ncd opencode-zellij-namer\n```\n\n3. Update `package.json` with your fork's URL:\n\n```bash\n# Replace YOUR_USERNAME with your GitHub username\nsed -i 's/24601/YOUR_USERNAME/g' package.json\n```\n\n### Build \u0026 Test\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\n### Local Development\n\nTo test your changes with OpenCode, update your config to point to your local build:\n\n```json\n{\n  \"plugin\": [\"/path/to/your/opencode-zellij-namer\"]\n}\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F24601%2Fopencode-zellij-namer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F24601%2Fopencode-zellij-namer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F24601%2Fopencode-zellij-namer/lists"}