polaris-opencode

Ah yeah my Polaris pls guide me

- 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.

Contents

- 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)

$3

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

Installation

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.

$3

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" }
}
}
`

$3

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.

Uninstallation

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
`

Features

$3

- build (anthropic/claude-3-7-sonnet): Primary high-intelligence orchestrator. Elite software engineer mode. Analyzes, plans, and executes immediately.
- plan (google/gemini-2.0-flash): Read-only architect. Designs and proposes changes without modifying code.
- librarian (opencode/big-pickle): Multi-repo analysis, doc lookup, implementation examples.
- explore (opencode/big-pickle): 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
`

$3

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.

$3

#### 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.
- Conditional Rules Injector: Not all rules apply all the time. Injects rules from .claude/rules/ when conditions match.
- Walks upward from file directory to project root, plus ~/.claude/rules/ (user).
- Supports .md and .mdc files.
- Online: Project rules aren't everything. Use external tools and web search as needed for extended capabilities.

$3

Polaris OpenCode has partial Claude Code compatibility.

The Conditional Rules Injector loads rules from .claude/rules/ - see Context Is All You Need for details.

Configuration

Highly opinionated, but adjustable to taste.

Config file locations (priority order):

1. .opencode/polaris-opencode.json (project)
2. ~/.config/opencode/polaris-opencode.json (user)

Schema autocomplete supported:

`json
{
"$schema": "./assets/polaris-opencode.schema.json"
}
`

$3

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

$3

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"
}
}
}
`

$3

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.