<!-- <CENTERED SECTION FOR GITHUB DISPLAY> -->

## Ah yeah my Polaris pls guide me

<div align="center">

  [![Preview](./.github/assets/polaris.png)](https://github.com/nielpattin/oh-my-opencode#oh-my-opencode)
  
</div>

- It's a minimal fork from oh-my-opencode. Stripped down, no bloat.
- Polaris orchestrator (Fast & 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.

<!-- </CENTERED SECTION FOR GITHUB DISPLAY> -->

## Contents

- [For Those Who Want to Read](#for-those-who-want-to-read)
- [Installation](#installation)
  - [Step 1: Configure Your Models](#step-1-configure-your-models)
  - [Step 2: Add the Plugin](#step-2-add-the-plugin)
- [Uninstallation](#uninstallation)
- [Features](#features)
  - [Agents: Your Colleagues](#agents-your-colleagues)
  - [Background Agents: Work Like a Team](#background-agents-work-like-a-team)
  - [The Tools: Your Colleagues Deserve Better](#the-tools-your-colleagues-deserve-better)
    - [Context Is All You Need](#context-is-all-you-need)
  - [Goodbye Claude Code. Hello Oh My OpenCode.](#goodbye-claude-code-hello-oh-my-opencode)
- [Configuration](#configuration)
  - [Agents](#agents)
    - [Permission Options](#permission-options)
  - [Polaris Agent](#polaris-agent)
  - [Hooks](#hooks)

### For Those Who Want to Read

Polaris is the orchestrator. Everything is enabled by default because I'm too lazy to make it opt-in. Bruh.

- **Agents**
  - Polaris-Smart: Primary orchestrator (Opus 4.5, extended thinking)
  - Polaris-Fast: Speed-optimized orchestrator (Gemini 3 Flash)
  - 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**
  - rules-injector: Conditional rules from `.claude/rules/`
  - directory-agents-injector: Auto-injects `AGENTS.md`
  - directory-readme-injector: Auto-injects `README.md`
  - keyword-detector: Injects context based on keywords
  - background-notification: Notifies on background task completion
  - agent-usage-reminder: Reminds about available agents
  - update-checker: Checks for plugin updates
  - session-notification: Session lifecycle notifications
  - non-interactive-env: Handles non-interactive environments


## Installation

Look, I'm tired and I won't find your right model. Just go to [models.dev](https://models.dev), find your `provider/model_name`, and paste it in the config.

### Step 1: Configure Your Models

Create and paste this `~/.config/opencode/oh-my-opencode.jsonc`:

```json
{
  "agents": {
    "Polaris-Smart": { "model": "anthropic/claude-opus-4-5" },
    "Polaris-Fast": { "model": "google/gemini-3-flash" },
    "librarian": { "model": "opencode/big-pickle" },
    "explore": { "model": "opencode/big-pickle" }
  }
}
```

### Step 2: Add the Plugin

Add `oh-my-opencode` to your plugin array in `~/.config/opencode/opencode.jsonc`:

```jsonc
{
  "plugin": ["@nielpattin/oh-my-opencode@1.0.15"]
}
```

You're done. Type `opencode` and stop bothering me.

## Uninstallation

To remove oh-my-opencode:

1. **Remove the plugin from your OpenCode config**

   - Remove `"@nielpattin/oh-my-opencode"` from the `plugin` array:

2. **Remove configuration files (optional)**

   ```bash
   # Remove user config
   rm -f ~/.config/opencode/oh-my-opencode.json

   # Remove project config (if exists)
   rm -f .opencode/oh-my-opencode.json
   ```

## Features

### Agents: Your Colleagues

- **Polaris-Smart** (`anthropic/claude-opus-4-5`): **Primary high-intelligence orchestrator.** Uses extended thinking for complex architectural decisions, deep implementation, and multi-subsystem refactors. Executes immediately without a separate planning phase.
- **Polaris-Fast** (`google/gemini-3-flash`): **Speed-optimized orchestrator.** Blazing fast execution for straightforward tasks, single-file changes, and well-defined bug fixes. Focuses on rapid iteration.
- **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
```

### Background Agents: Work Like a Team

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

### The Tools: Your Colleagues Deserve Better

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

### Goodbye Claude Code. Hello Oh My OpenCode.

Oh My OpenCode has partial Claude Code compatibility.

The **Conditional Rules Injector** loads rules from `.claude/rules/` - see [Context Is All You Need](#context-is-all-you-need) for details.

## Configuration

Highly opinionated, but adjustable to taste.

Config file locations (priority order):
1. `.opencode/oh-my-opencode.json` (project)
2. `~/.config/opencode/oh-my-opencode.json` (user)

Schema autocomplete supported:

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

### Agents

Override built-in agent settings:

```json
{
  "agents": {
    "explore": {
      "model": "anthropic/claude-haiku-4-5",
      "temperature": 0.5
    },
    "Polaris-Fast": {
      "disable": true
    }
  }
}
```

Each agent supports: `model`, `temperature`, `top_p`, `prompt`, `tools`, `disable`, `description`, `mode`, `color`, `permission`.

You can also override settings for `Polaris-Smart` and `Polaris-Fast` 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/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:

```json
{
  "disabled_agents": ["Polaris-Fast"]
}
```

Available agents: `librarian`, `explore`, `Polaris-Smart`, `Polaris-Fast`

### Polaris Agents

When enabled (default), oh-my-opencode adds two primary orchestrators:

- **Polaris-Smart**: Primary high-intelligence orchestrator (Claude Opus 4.5)
- **Polaris-Fast**: Speed-optimized orchestrator (Gemini 3 Flash)

They both operate in "YOLO Build Mode" - they analyze, plan, and execute immediately without stopping for permission. 

| Feature | Polaris-Smart | Polaris-Fast |
|---------|---------------|--------------|
| **Core Prompt** | Full orchestrator logic (Restored/Updated) | Speed-optimized orchestrator |
| **Optimization** | Intelligence & Extended Thinking | Speed & Efficiency |
| **Best For** | Complex refactors, architecture | Clear, focused tasks |
| **Parallelization** | Full assessment & batch spawns | Minimal (1-2 agents max) |

You can customize them like other agents:

```json
{
  "agents": {
    "Polaris-Smart": {
      "model": "anthropic/claude-sonnet-4.5",
      "temperature": 0.3
    },
    "Polaris-Fast": {
      "model": "google/gemini-3-flash"
    }
  }
}
```

### Hooks

Disable specific built-in hooks via `disabled_hooks` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-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 latest user message as notification title
- Waits for idle confirmation to avoid spam during rapid interactions
```