OpenCode plugin - custom agents (librarian) and enhanced features
npm install polaris-opencode
- OpenCode plugin for AI agent orchestration. Stripped down, no bloat.
- Polaris orchestrator (Good & Smart) with background agents. Minimal and aggressive.
- Not Certified, Not Verified, Not Tested. Just works (probably).
- Just BYOK or SUBSCRIPTIONS to opencode itself bruh. I don't cover anything.
- For Those Who Want to Read
- Installation
- Step 1: Configure Your Models
- Step 2: Add the Plugin
- Uninstallation
- Features
- Agents: Your Colleagues
- Background Agents: Work Like a Team
- The Tools: Your Colleagues Deserve Better
- Context Is All You Need
- Goodbye Claude Code. Hello Polaris OpenCode.
- Configuration
- Agents
- Permission Options
- Orchestrator Agents
- Hooks
- Session Notification
- Dynamic Context Pruning (DCP)
Polaris is the orchestrator. Everything is enabled by default because I'm too lazy to make it opt-in. Bruh.
- build: Primary high-intelligence orchestrator (Elite software engineer mode)
- plan: Read-only architect mode for analysis and design
- librarian: Docs and GitHub search (opencode/big-pickle)
- explore: Codebase patterns (opencode/grok-code)
- Background Agents: background_task, background_output, background_cancel tools (explore/librarian only)
- Hooks
- dcp: Dynamic Context Pruning (Automatic token saving)
- rules-injector: Conditional rules from .claude/rules/
- directory-agents-injector: Auto-injects AGENTS.md
- directory-readme-injector: Auto-injects README.md
- todo-continuation-enforcer: Prompts agent to continue incomplete todos
- session-notification: Session lifecycle notifications (Discord + Native)
- system-prompt-logger: Logs full system prompts to file
- update-checker: Checks for plugin updates
Look, I'm tired and I won't find your right model. Just go to models.dev, find your provider/model_name, and paste it in the config.
Create and paste this ~/.config/opencode/polaris-opencode.jsonc:
``json`
{
"agents": {
"build": { "model": "anthropic/claude-3-7-sonnet" },
"plan": { "model": "google/gemini-2.0-flash" },
"librarian": { "model": "opencode/big-pickle" },
"explore": { "model": "opencode/big-pickle" }
}
}
Add polaris-opencode to your plugin array in ~/.config/opencode/opencode.jsonc:
`jsonc`
{
"plugin": ["polaris-opencode"],
}
You're done. Type opencode and stop bothering me.
To remove polaris-opencode:
1. Remove the plugin from your OpenCode config
- Remove "polaris-opencode" from the plugin array:
2. Remove configuration files (optional)
`bash
# Remove user config
rm -f ~/.config/opencode/polaris-opencode.json
# Remove project config (if exists)
rm -f .opencode/polaris-opencode.json
`
- build (anthropic/claude-3-7-sonnet): Primary high-intelligence orchestrator. Elite software engineer mode. Analyzes, plans, and executes immediately.google/gemini-2.0-flash
- plan (): Read-only architect. Designs and proposes changes without modifying code.opencode/big-pickle
- librarian (): Multi-repo analysis, doc lookup, implementation examples.opencode/big-pickle
- explore (): Fast codebase exploration and pattern matching.
The main agent invokes these automatically, but you can call them explicitly:
``
Ask @librarian how this is implemented—why does the behavior keep changing?
Ask @explore for the policy on this feature
Stop letting your agents idle.
- Have GPT debug while Claude tries different approaches.
- One agent writes the frontend while another handles the backend.
- Kick off parallel searches, then finish using the results.
Run subagents in the background. The main agent gets notified on completion.
Make your agents work like your team works.
#### Context Is All You Need
- Directory AGENTS.md / README.md Injector: Auto-injects AGENTS.md and README.md when reading files. Walks from file directory to project root, collecting all AGENTS.md files along the path..claude/rules/
- Conditional Rules Injector: Not all rules apply all the time. Injects rules from when conditions match.~/.claude/rules/
- Walks upward from file directory to project root, plus (user)..md
- Supports and .mdc files.
- Online: Project rules aren't everything. Use external tools and web search as needed for extended capabilities.
Polaris OpenCode has partial Claude Code compatibility.
The Conditional Rules Injector loads rules from .claude/rules/ - see Context Is All You Need for details.
Highly opinionated, but adjustable to taste.
Config file locations (priority order):
1. .opencode/polaris-opencode.json (project)~/.config/opencode/polaris-opencode.json
2. (user)
Schema autocomplete supported:
`json`
{
"$schema": "./assets/polaris-opencode.schema.json"
}
Override built-in agent settings:
`json`
{
"agents": {
"explore": {
"model": "anthropic/claude-haiku-4-5",
"temperature": 0.5
},
"Polaris-Good": {
"disable": true
}
}
}
Each agent supports: model, temperature, top_p, prompt, tools, disable, description, mode, color, permission.
You can also override settings for build and plan using the same options.
#### Permission Options
Fine-grained control over what agents can do:
`json`
{
"agents": {
"explore": {
"permission": {
"edit": "deny",
"bash": "ask",
"webfetch": "allow"
}
}
}
}
| Permission | Description | Values |
| -------------------- | -------------------------------------- | --------------------------------------------------------------------------- |
| edit | File editing permission | ask / allow / deny |bash
| | Bash command execution | ask / allow / deny or per-command: { "git": "allow", "rm": "deny" } |webfetch
| | Web request permission | ask / allow / deny |doom_loop
| | Allow infinite loop detection override | ask / allow / deny |external_directory
| | Access files outside project root | ask / allow / deny |
Or disable via disabled_agents in ~/.config/opencode/polaris-opencode.json or .opencode/polaris-opencode.json:
`json`
{
"disabled_agents": ["Polaris-Good"]
}
Available agents: librarian, explore, build, plan
When enabled (default), polaris-opencode adds two primary orchestrators:
- build: High-intelligence developer mode.
- plan: Read-only design and exploration mode.
They both operate in "Elite Mode" - they analyze, plan, and execute efficiently.
| Feature | build | plan |
| ---------------- | --------------------- | -------------------- |
| Core Prompt | Developer logic | Architect logic |
| Optimization | Execution & Quality | Design & Analysis |
| Best For | Implementing features | Unfamiliar codebases |
| Permission | Direct edits | Read-only by default |
You can customize them like other agents:
`json`
{
"agents": {
"build": {
"model": "anthropic/claude-3-7-sonnet",
"temperature": 0.3
},
"plan": {
"model": "google/gemini-2.0-flash"
}
}
}
Disable specific built-in hooks via disabled_hooks in ~/.config/opencode/polaris-opencode.json or .opencode/polaris-opencode.json:
`json`
{
"disabled_hooks": ["agent-usage-reminder"]
}
#### Session Notification
Get notified when your agent finishes working. Supports native OS notifications and Discord webhooks.
`json`
{
"hooks": {
"session-notification": {
"showNativeNotification": true,
"playSound": false,
"idleConfirmationDelay": 1500,
"skipIfIncompleteTodos": true,
"discord": {
"enabled": true,
"webhookUrl": "https://discord.com/api/webhooks/...",
"color": 65280
}
}
}
}
| Option | Default | Description |
| ------------------------ | --------------------- | ---------------------------------------------------------- |
| showNativeNotification | true | Show OS toast notification |playSound
| | false | Play sound on completion |soundPath
| | Platform default | Custom sound file path |idleConfirmationDelay
| | 1500 | Ms to wait before confirming idle state |skipIfIncompleteTodos
| | true | Skip notification if todos remain |discord.enabled
| | false | Enable Discord webhook notifications |discord.webhookUrl
| | - | Discord webhook URL (or set DISCORD_WEBHOOK_URL env var) |discord.envVar
| | DISCORD_WEBHOOK_URL | Custom env var name for webhook URL |discord.color
| | 0x00ff00 | Embed color (green) |
Smart behavior:
- Skips notification if user aborts the response mid-stream
- Uses your latest question as the notification title (filters out plugin injections like DCP)
- Falls back to session title if no human message found
- Waits for idle confirmation to avoid spam during rapid interactions
#### Dynamic Context Pruning (DCP)
Automatically reduces token usage by pruning obsolete tool outputs. Enabled by default with discard and extract` tools for manual context management.