release: v2.12.2

- Remove unused import OhMyOpenCodeConfig from src/index.ts
- Remove unused import dirname from src/features/opencode-skill-loader/loader.ts
- Remove unused import detectKeywords from src/hooks/keyword-detector/index.ts
- Remove unused import CliMatch from src/tools/ast-grep/utils.ts
- Prefix unused parameter _original in src/tools/ast-grep/utils.ts

🤖 GENERATED WITH ASSISTANCE OF [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: code-yeongyu
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/pull_request_template.md

@@ -0,0 +1,34 @@
+## Summary
+
+<!-- Brief description of what this PR does. 1-3 bullet points. -->
+
+- 
+
+## Changes
+
+<!-- What was changed and how. List specific modifications. -->
+
+- 
+
+## Screenshots
+
+<!-- If applicable, add screenshots or GIFs showing before/after. Delete this section if not needed. -->
+
+| Before | After |
+|:---:|:---:|
+|  |  |
+
+## Testing
+
+<!-- How to verify this PR works correctly. Delete if not applicable. -->
+
+```bash
+bun run typecheck
+bun test
+```
+
+## Related Issues
+
+<!-- Link related issues. Use "Closes #123" to auto-close on merge. -->
+
+<!-- Closes # -->

.github/workflows/ci.yml

@@ -0,0 +1,138 @@
+name: CI
+
+on:
+  push:
+    branches: [master, dev]
+  pull_request:
+    branches: [master]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+        env:
+          BUN_INSTALL_ALLOW_SCRIPTS: "@ast-grep/napi"
+
+      - name: Run tests
+        run: bun test
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+        env:
+          BUN_INSTALL_ALLOW_SCRIPTS: "@ast-grep/napi"
+
+      - name: Type check
+        run: bun run typecheck
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [test, typecheck]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+        env:
+          BUN_INSTALL_ALLOW_SCRIPTS: "@ast-grep/napi"
+
+      - name: Build
+        run: bun run build
+
+      - name: Verify build output
+        run: |
+          test -f dist/index.js || (echo "ERROR: dist/index.js not found!" && exit 1)
+          test -f dist/index.d.ts || (echo "ERROR: dist/index.d.ts not found!" && exit 1)
+
+      - name: Auto-commit schema changes
+        if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+        run: |
+          if git diff --quiet assets/oh-my-opencode.schema.json; then
+            echo "No schema changes to commit"
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git add assets/oh-my-opencode.schema.json
+            git commit -m "chore: auto-update schema.json"
+            git push
+          fi
+
+  draft-release:
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - run: git fetch --force --tags
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Generate release notes
+        id: notes
+        run: |
+          NOTES=$(bun run script/generate-changelog.ts)
+          echo "notes<<EOF" >> $GITHUB_OUTPUT
+          echo "$NOTES" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create or update draft release
+        run: |
+          EXISTING_DRAFT=$(gh release list --json tagName,isDraft --jq '.[] | select(.isDraft == true and .tagName == "next") | .tagName')
+          
+          if [ -n "$EXISTING_DRAFT" ]; then
+            echo "Updating existing draft release..."
+            gh release edit next \
+              --title "Upcoming Changes 🍿" \
+              --notes-file - \
+              --draft <<'EOF'
+          ${{ steps.notes.outputs.notes }}
+          EOF
+          else
+            echo "Creating new draft release..."
+            gh release create next \
+              --title "Upcoming Changes 🍿" \
+              --notes-file - \
+              --draft \
+              --target ${{ github.sha }} <<'EOF'
+          ${{ steps.notes.outputs.notes }}
+          EOF
+          fi
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/cla.yml

@@ -0,0 +1,41 @@
+name: CLA Assistant
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened, closed, synchronize]
+
+permissions:
+  actions: write
+  contents: write
+  pull-requests: write
+  statuses: write
+
+jobs:
+  cla:
+    runs-on: ubuntu-latest
+    steps:
+      - name: CLA Assistant
+        if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
+        uses: contributor-assistant/github-action@v2.6.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          path-to-signatures: 'signatures/cla.json'
+          path-to-document: 'https://github.com/code-yeongyu/oh-my-opencode/blob/master/CLA.md'
+          branch: 'dev'
+          allowlist: bot*,dependabot*,github-actions*,*[bot],sisyphus-dev-ai
+          custom-notsigned-prcomment: |
+            Thank you for your contribution! Before we can merge this PR, we need you to sign our [Contributor License Agreement (CLA)](https://github.com/code-yeongyu/oh-my-opencode/blob/master/CLA.md).
+            
+            **To sign the CLA**, please comment on this PR with:
+            ```
+            I have read the CLA Document and I hereby sign the CLA
+            ```
+            
+            This is a one-time requirement. Once signed, all your future contributions will be automatically accepted.
+          custom-pr-sign-comment: 'I have read the CLA Document and I hereby sign the CLA'
+          custom-allsigned-prcomment: |
+            All contributors have signed the CLA. Thank you! ✅
+          lock-pullrequest-aftermerge: false

.github/workflows/publish.yml

@@ -24,8 +24,44 @@ permissions:
   id-token: write
 
 jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+        env:
+          BUN_INSTALL_ALLOW_SCRIPTS: "@ast-grep/napi"
+
+      - name: Run tests
+        run: bun test
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+        env:
+          BUN_INSTALL_ALLOW_SCRIPTS: "@ast-grep/napi"
+
+      - name: Type check
+        run: bun run typecheck
+
   publish:
     runs-on: ubuntu-latest
+    needs: [test, typecheck]
+    if: github.repository == 'code-yeongyu/oh-my-opencode'
     steps:
       - uses: actions/checkout@v4
         with:
@@ -67,9 +103,10 @@ jobs:
 
       - name: Build
         run: |
-          echo "=== Running bun build ==="
-          bun build src/index.ts --outdir dist --target bun --format esm --external @ast-grep/napi
-          echo "=== bun build exit code: $? ==="
+          echo "=== Running bun build (main) ==="
+          bun build src/index.ts src/google-auth.ts --outdir dist --target bun --format esm --external @ast-grep/napi
+          echo "=== Running bun build (CLI) ==="
+          bun build src/cli/index.ts --outdir dist/cli --target bun --format esm
           echo "=== Running tsc ==="
           tsc --emitDeclarationOnly
           echo "=== Running build:schema ==="
@@ -77,8 +114,12 @@ jobs:
       
       - name: Verify build output
         run: |
+          echo "=== dist/ contents ==="
           ls -la dist/
+          echo "=== dist/cli/ contents ==="
+          ls -la dist/cli/
           test -f dist/index.js || (echo "ERROR: dist/index.js not found!" && exit 1)
+          test -f dist/cli/index.js || (echo "ERROR: dist/cli/index.js not found!" && exit 1)
 
       - name: Publish
         run: bun run script/publish.ts
@@ -88,3 +129,17 @@ jobs:
           CI: true
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_CONFIG_PROVENANCE: true
+
+      - name: Delete draft release
+        run: gh release delete next --yes 2>/dev/null || echo "No draft release to delete"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Merge to master
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          VERSION=$(jq -r '.version' package.json)
+          git checkout master
+          git reset --hard "v${VERSION}"
+          git push -f origin master

.github/workflows/sisyphus-agent.yml

@@ -0,0 +1,376 @@
+name: Sisyphus Agent
+
+on:
+  workflow_dispatch:
+    inputs:
+      prompt:
+        description: "Custom prompt"
+        required: false
+  # Only issue_comment works for fork PRs (secrets available)
+  # pull_request_review/pull_request_review_comment do NOT get secrets for fork PRs
+  issue_comment:
+    types: [created]
+
+jobs:
+  agent:
+    runs-on: ubuntu-latest
+    # @sisyphus-dev-ai mention only (maintainers, exclude self)
+    if: |
+      github.event_name == 'workflow_dispatch' ||
+      (contains(github.event.comment.body, '@sisyphus-dev-ai') &&
+       github.event.comment.user.login != 'sisyphus-dev-ai' &&
+       contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association))
+
+    # Minimal default GITHUB_TOKEN permissions
+    permissions:
+      contents: read
+
+    steps:
+      # Checkout with sisyphus-dev-ai's PAT
+      - uses: actions/checkout@v5
+        with:
+          token: ${{ secrets.GH_PAT }}
+          fetch-depth: 0
+
+      # Git config - commits as sisyphus-dev-ai
+      - name: Configure Git as sisyphus-dev-ai
+        run: |
+          git config user.name "sisyphus-dev-ai"
+          git config user.email "sisyphus-dev-ai@users.noreply.github.com"
+
+      # gh CLI auth as sisyphus-dev-ai
+      - name: Authenticate gh CLI as sisyphus-dev-ai
+        run: |
+          echo "${{ secrets.GH_PAT }}" | gh auth login --with-token
+          gh auth status
+
+      - name: Ensure tmux is available (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          set -euo pipefail
+          if ! command -v tmux >/dev/null 2>&1; then
+            sudo apt-get update
+            sudo apt-get install -y --no-install-recommends tmux
+          fi
+          tmux -V
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Cache Bun dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
+      # Build local oh-my-opencode
+      - name: Build oh-my-opencode
+        run: |
+          bun install
+          bun run build
+
+      # Install OpenCode + configure local plugin + auth in single step
+      - name: Setup OpenCode with oh-my-opencode
+        env:
+          OPENCODE_AUTH_JSON: ${{ secrets.OPENCODE_AUTH_JSON }}
+          ANTHROPIC_BASE_URL: ${{ secrets.ANTHROPIC_BASE_URL }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          export PATH="$HOME/.opencode/bin:$PATH"
+
+          # Install OpenCode (skip if cached)
+          if ! command -v opencode &>/dev/null; then
+            echo "Installing OpenCode..."
+            curl -fsSL https://opencode.ai/install -o /tmp/opencode-install.sh
+            
+            # Try default installer first, fallback to pinned version if it fails
+            if file /tmp/opencode-install.sh | grep -q "shell script\|text"; then
+              if ! bash /tmp/opencode-install.sh 2>&1; then
+                echo "Default installer failed, trying with pinned version..."
+                bash /tmp/opencode-install.sh --version 1.0.204
+              fi
+            else
+              echo "Download corrupted, trying direct install with pinned version..."
+              bash <(curl -fsSL https://opencode.ai/install) --version 1.0.204
+            fi
+          fi
+          opencode --version
+
+          # Run local oh-my-opencode install (uses built dist)
+          bun run dist/cli/index.js install --no-tui --claude=max20 --chatgpt=no --gemini=no
+
+          # Override plugin to use local file reference
+          OPENCODE_JSON=~/.config/opencode/opencode.json
+          REPO_PATH=$(pwd)
+          jq --arg path "file://$REPO_PATH/src/index.ts" '
+            .plugin = [.plugin[] | select(. != "oh-my-opencode")] + [$path]
+          ' "$OPENCODE_JSON" > /tmp/oc.json && mv /tmp/oc.json "$OPENCODE_JSON"
+
+          OPENCODE_JSON=~/.config/opencode/opencode.json
+          jq --arg baseURL "$ANTHROPIC_BASE_URL" --arg apiKey "$ANTHROPIC_API_KEY" '
+            .provider.anthropic = {
+              "name": "Anthropic",
+              "npm": "@ai-sdk/anthropic",
+              "options": {
+                "baseURL": $baseURL,
+                "apiKey": $apiKey
+              },
+              "models": {
+                "claude-opus-4-5": {
+                  "id": "claude-opus-4-5-20251101",
+                  "name": "Opus 4.5",
+                  "limit": { "context": 190000, "output": 64000 },
+                  "options": { "effort": "high" }
+                },
+                "claude-opus-4-5-high": {
+                  "id": "claude-opus-4-5-20251101",
+                  "name": "Opus 4.5 High",
+                  "limit": { "context": 190000, "output": 128000 },
+                  "options": { "effort": "high", "thinking": { "type": "enabled", "budgetTokens": 64000 } }
+                },
+                "claude-sonnet-4-5": {
+                  "id": "claude-sonnet-4-5-20250929",
+                  "name": "Sonnet 4.5",
+                  "limit": { "context": 200000, "output": 64000 }
+                },
+                "claude-sonnet-4-5-high": {
+                  "id": "claude-sonnet-4-5-20250929",
+                  "name": "Sonnet 4.5 High",
+                  "limit": { "context": 200000, "output": 128000 },
+                  "options": { "thinking": { "type": "enabled", "budgetTokens": 64000 } }
+                },
+                "claude-haiku-4-5": {
+                  "id": "claude-haiku-4-5-20251001",
+                  "name": "Haiku 4.5",
+                  "limit": { "context": 200000, "output": 64000 }
+                }
+              }
+            }
+          ' "$OPENCODE_JSON" > /tmp/oc.json && mv /tmp/oc.json "$OPENCODE_JSON"
+
+          OMO_JSON=~/.config/opencode/oh-my-opencode.json
+          PROMPT_APPEND=$(cat << 'PROMPT_EOF'
+
+          ## GitHub Actions Environment
+
+          You are `sisyphus-dev-ai` in GitHub Actions.
+
+          ### CRITICAL: GitHub Comments = Your ONLY Output
+
+          User CANNOT see console. Post everything via `gh issue comment` or `gh pr comment`.
+
+          ### Comment Formatting (CRITICAL)
+
+          **ALWAYS use heredoc syntax for comments containing code references, backticks, or multiline content:**
+
+          ```bash
+          gh issue comment <number> --body "$(cat <<'EOF'
+          Your comment with `backticks` and code references preserved here.
+          Multiple lines work perfectly.
+          EOF
+          )"
+          ```
+
+          **NEVER use direct quotes with backticks** (shell will interpret them as command substitution):
+          ```bash
+          # WRONG - backticks disappear:
+          gh issue comment 123 --body "text with `code`"
+          
+          # CORRECT - backticks preserved:
+          gh issue comment 123 --body "$(cat <<'EOF'
+          text with `code`
+          EOF
+          )"
+          ```
+
+          ### GitHub Markdown Rules (MUST FOLLOW)
+
+          **Code blocks MUST have EXACTLY 3 backticks and language identifier:**
+          - CORRECT: ` ```bash ` ... ` ``` `
+          - WRONG: ` ``` ` (no language), ` ```` ` (4 backticks), ` `` ` (2 backticks)
+          
+          **Every opening ` ``` ` MUST have a closing ` ``` ` on its own line:**
+          ```
+          ```bash
+          code here
+          ```
+          ```
+          
+          **NO trailing backticks or spaces after closing ` ``` `**
+          
+          **For inline code, use SINGLE backticks:** `code` not ```code```
+          
+          **Lists inside code blocks break rendering - avoid them or use plain text**
+
+          ### Rules
+          - EVERY response = GitHub comment (use heredoc for proper escaping)
+          - Code changes = PR (never push main/master)
+          - Setup: bun install first
+          - Acknowledge immediately, report when done
+
+          ### Git Config
+          - user.name: sisyphus-dev-ai
+          - user.email: sisyphus-dev-ai@users.noreply.github.com
+          PROMPT_EOF
+          )
+          jq --arg append "$PROMPT_APPEND" '.agents.Sisyphus.prompt_append = $append' "$OMO_JSON" > /tmp/omo.json && mv /tmp/omo.json "$OMO_JSON"
+
+          mkdir -p ~/.local/share/opencode
+          echo "$OPENCODE_AUTH_JSON" > ~/.local/share/opencode/auth.json
+          chmod 600 ~/.local/share/opencode/auth.json
+
+          cat "$OPENCODE_JSON"
+
+      # Collect context
+      - name: Collect Context
+        id: context
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_PAT }}
+          EVENT_NAME: ${{ github.event_name }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          COMMENT_BODY: ${{ github.event.comment.body }}
+          COMMENT_AUTHOR: ${{ github.event.comment.user.login }}
+          COMMENT_ID_VAL: ${{ github.event.comment.id }}
+          REPO: ${{ github.repository }}
+        run: |
+          if [[ "$EVENT_NAME" == "issue_comment" ]]; then
+            ISSUE_NUM="$ISSUE_NUMBER"
+            AUTHOR="$COMMENT_AUTHOR"
+            COMMENT_ID="$COMMENT_ID_VAL"
+
+            # Check if PR or Issue
+            if gh api "repos/$REPO/issues/${ISSUE_NUM}" | jq -e '.pull_request' > /dev/null; then
+              echo "type=pr" >> $GITHUB_OUTPUT
+              echo "number=${ISSUE_NUM}" >> $GITHUB_OUTPUT
+            else
+              echo "type=issue" >> $GITHUB_OUTPUT
+              echo "number=${ISSUE_NUM}" >> $GITHUB_OUTPUT
+            fi
+          fi
+
+          echo "comment<<EOF" >> $GITHUB_OUTPUT
+          echo "$COMMENT_BODY" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+          echo "author=$AUTHOR" >> $GITHUB_OUTPUT
+          echo "comment_id=$COMMENT_ID" >> $GITHUB_OUTPUT
+
+      # Add :eyes: reaction (as sisyphus-dev-ai)
+      - name: Add eyes reaction
+        if: steps.context.outputs.comment_id != ''
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_PAT }}
+        run: |
+          gh api "/repos/${{ github.repository }}/issues/comments/${{ steps.context.outputs.comment_id }}/reactions" \
+            -X POST -f content="eyes" || true
+
+      - name: Add working label
+        if: steps.context.outputs.number != ''
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_PAT }}
+        run: |
+          gh label create "sisyphus: working" \
+            --repo "${{ github.repository }}" \
+            --color "fcf2e1" \
+            --description "Sisyphus is currently working on this" \
+            --force || true
+          
+          if [[ "${{ steps.context.outputs.type }}" == "pr" ]]; then
+            gh pr edit "${{ steps.context.outputs.number }}" \
+              --repo "${{ github.repository }}" \
+              --add-label "sisyphus: working" || true
+          else
+            gh issue edit "${{ steps.context.outputs.number }}" \
+              --repo "${{ github.repository }}" \
+              --add-label "sisyphus: working" || true
+          fi
+
+      - name: Run oh-my-opencode
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_PAT }}
+          USER_COMMENT: ${{ steps.context.outputs.comment }}
+          COMMENT_AUTHOR: ${{ steps.context.outputs.author }}
+          CONTEXT_TYPE: ${{ steps.context.outputs.type }}
+          CONTEXT_NUMBER: ${{ steps.context.outputs.number }}
+          REPO_NAME: ${{ github.repository }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          export PATH="$HOME/.opencode/bin:$PATH"
+
+          PROMPT=$(cat <<'PROMPT_EOF'
+          Your username is @sisyphus-dev-ai, mentioned by @AUTHOR_PLACEHOLDER in REPO_PLACEHOLDER.
+
+          ## Context
+          - Type: TYPE_PLACEHOLDER
+          - Number: #NUMBER_PLACEHOLDER
+          - Repository: REPO_PLACEHOLDER
+          - Default Branch: BRANCH_PLACEHOLDER
+
+          ## User's Request
+          COMMENT_PLACEHOLDER
+
+          ---
+
+          Plan everything using todo tools.
+          Then investigate and satisfy the request. Only if user requested to you to work explicitly, then use plan agent to plan, todo obsessively then create a PR to `BRANCH_PLACEHOLDER` branch.
+          When done, report the result to the issue/PR with `gh issue comment NUMBER_PLACEHOLDER` or `gh pr comment NUMBER_PLACEHOLDER`.
+          PROMPT_EOF
+          )
+
+          PROMPT="${PROMPT//AUTHOR_PLACEHOLDER/$COMMENT_AUTHOR}"
+          PROMPT="${PROMPT//REPO_PLACEHOLDER/$REPO_NAME}"
+          PROMPT="${PROMPT//TYPE_PLACEHOLDER/$CONTEXT_TYPE}"
+          PROMPT="${PROMPT//NUMBER_PLACEHOLDER/$CONTEXT_NUMBER}"
+          PROMPT="${PROMPT//BRANCH_PLACEHOLDER/$DEFAULT_BRANCH}"
+          PROMPT="${PROMPT//COMMENT_PLACEHOLDER/$USER_COMMENT}"
+
+          stdbuf -oL -eL bun run dist/cli/index.js run "$PROMPT"
+
+      # Push changes (as sisyphus-dev-ai)
+      - name: Push changes
+        if: always()
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_PAT }}
+        run: |
+          if [[ -n "$(git status --porcelain)" ]]; then
+            git add -A
+            git commit -m "chore: changes by sisyphus-dev-ai" || true
+          fi
+
+          BRANCH=$(git branch --show-current)
+          if [[ "$BRANCH" != "main" && "$BRANCH" != "master" ]]; then
+            git push origin "$BRANCH" || true
+          fi
+
+      - name: Update reaction and remove label
+        if: always()
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_PAT }}
+        run: |
+          if [[ -n "${{ steps.context.outputs.comment_id }}" ]]; then
+            REACTION_ID=$(gh api "/repos/${{ github.repository }}/issues/comments/${{ steps.context.outputs.comment_id }}/reactions" \
+              --jq '.[] | select(.content == "eyes" and .user.login == "sisyphus-dev-ai") | .id' | head -1)
+            if [[ -n "$REACTION_ID" ]]; then
+              gh api -X DELETE "/repos/${{ github.repository }}/reactions/${REACTION_ID}" || true
+            fi
+
+            gh api "/repos/${{ github.repository }}/issues/comments/${{ steps.context.outputs.comment_id }}/reactions" \
+              -X POST -f content="+1" || true
+          fi
+
+          if [[ -n "${{ steps.context.outputs.number }}" ]]; then
+            if [[ "${{ steps.context.outputs.type }}" == "pr" ]]; then
+              gh pr edit "${{ steps.context.outputs.number }}" \
+                --repo "${{ github.repository }}" \
+                --remove-label "sisyphus: working" || true
+            else
+              gh issue edit "${{ steps.context.outputs.number }}" \
+                --repo "${{ github.repository }}" \
+                --remove-label "sisyphus: working" || true
+            fi
+          fi

.opencode/command/get-unpublished-changes.md

@@ -0,0 +1,84 @@
+---
+description: Compare HEAD with the latest published npm version and list all unpublished changes
+model: anthropic/claude-haiku-4-5
+---
+
+<command-instruction>
+IMMEDIATELY output the analysis. NO questions. NO preamble.
+
+## CRITICAL: DO NOT just copy commit messages!
+
+For each commit, you MUST:
+1. Read the actual diff to understand WHAT CHANGED
+2. Describe the REAL change in plain language
+3. Explain WHY it matters (if not obvious)
+
+## Steps:
+1. Run `git diff v{published-version}..HEAD` to see actual changes
+2. Group by type (feat/fix/refactor/docs) with REAL descriptions
+3. Note breaking changes if any
+4. Recommend version bump (major/minor/patch)
+
+## Output Format:
+- feat: "Added X that does Y" (not just "add X feature")
+- fix: "Fixed bug where X happened, now Y" (not just "fix X bug")
+- refactor: "Changed X from A to B, now supports C" (not just "rename X")
+</command-instruction>
+
+<version-context>
+<published-version>
+!`npm view oh-my-opencode version 2>/dev/null || echo "not published"`
+</published-version>
+<local-version>
+!`node -p "require('./package.json').version" 2>/dev/null || echo "unknown"`
+</local-version>
+<latest-tag>
+!`git tag --sort=-v:refname | head -1 2>/dev/null || echo "no tags"`
+</latest-tag>
+</version-context>
+
+<git-context>
+<commits-since-release>
+!`npm view oh-my-opencode version 2>/dev/null | xargs -I{} git log "v{}"..HEAD --oneline 2>/dev/null || echo "no commits since release"`
+</commits-since-release>
+<diff-stat>
+!`npm view oh-my-opencode version 2>/dev/null | xargs -I{} git diff "v{}"..HEAD --stat 2>/dev/null || echo "no diff available"`
+</diff-stat>
+<files-changed-summary>
+!`npm view oh-my-opencode version 2>/dev/null | xargs -I{} git diff "v{}"..HEAD --stat 2>/dev/null | tail -1 || echo ""`
+</files-changed-summary>
+</git-context>
+
+<output-format>
+## Unpublished Changes (v{published} → HEAD)
+
+### feat
+| Scope | What Changed |
+|-------|--------------|
+| X | 실제 변경 내용 설명 |
+
+### fix
+| Scope | What Changed |
+|-------|--------------|
+| X | 실제 변경 내용 설명 |
+
+### refactor
+| Scope | What Changed |
+|-------|--------------|
+| X | 실제 변경 내용 설명 |
+
+### docs
+| Scope | What Changed |
+|-------|--------------|
+| X | 실제 변경 내용 설명 |
+
+### Breaking Changes
+None 또는 목록
+
+### Files Changed
+{diff-stat}
+
+### Suggested Version Bump
+- **Recommendation**: patch|minor|major
+- **Reason**: 이유
+</output-format>

.opencode/command/omomomo.md

@@ -0,0 +1,37 @@
+---
+description: Easter egg command - about oh-my-opencode
+---
+
+<command-instruction>
+You found an easter egg! 🥚✨
+
+Print the following message to the user EXACTLY as written (in a friendly, celebratory tone):
+
+---
+
+# 🎉 oMoMoMoMoMo···
+
+**You found the easter egg!** 🥚✨
+
+## What is Oh My OpenCode?
+
+**Oh My OpenCode** is a powerful OpenCode plugin that transforms your AI agent into a full development team:
+
+- 🤖 **Multi-Agent Orchestration**: Oracle (GPT-5.2), Librarian (Claude), Explore (Grok), Frontend Engineer (Gemini), and more
+- 🔧 **LSP Tools**: Full IDE capabilities for your agents - hover, goto definition, find references, rename, code actions
+- 🔍 **AST-Grep**: Structural code search and replace across 25 languages
+- 📚 **Built-in MCPs**: Context7 for docs, Exa for web search, grep.app for GitHub code search
+- 🔄 **Background Agents**: Run multiple agents in parallel like a real dev team
+- 🎯 **Claude Code Compatibility**: Your existing Claude Code config just works
+
+## Who Made This?
+
+Created with ❤️ by **[code-yeongyu](https://github.com/code-yeongyu)**
+
+🔗 **GitHub**: https://github.com/code-yeongyu/oh-my-opencode
+
+---
+
+*Enjoy coding on steroids!* 🚀
+
+</command-instruction>

.opencode/command/publish.md

@@ -0,0 +1,257 @@
+---
+description: Publish oh-my-opencode to npm via GitHub Actions workflow
+argument-hint: <patch|minor|major>
+---
+
+<command-instruction>
+You are the release manager for oh-my-opencode. Execute the FULL publish workflow from start to finish.
+
+## CRITICAL: ARGUMENT REQUIREMENT
+
+**You MUST receive a version bump type from the user.** Valid options:
+- `patch`: Bug fixes, backward-compatible (1.1.7 → 1.1.8)
+- `minor`: New features, backward-compatible (1.1.7 → 1.2.0)
+- `major`: Breaking changes (1.1.7 → 2.0.0)
+
+**If the user did not provide a bump type argument, STOP IMMEDIATELY and ask:**
+> "배포를 진행하려면 버전 범프 타입을 지정해주세요: `patch`, `minor`, 또는 `major`"
+
+**DO NOT PROCEED without explicit user confirmation of bump type.**
+
+---
+
+## STEP 0: REGISTER TODO LIST (MANDATORY FIRST ACTION)
+
+**Before doing ANYTHING else**, create a detailed todo list using TodoWrite:
+
+```
+[
+  { "id": "confirm-bump", "content": "Confirm version bump type with user (patch/minor/major)", "status": "in_progress", "priority": "high" },
+  { "id": "check-uncommitted", "content": "Check for uncommitted changes and commit if needed", "status": "pending", "priority": "high" },
+  { "id": "sync-remote", "content": "Sync with remote (pull --rebase && push if unpushed commits)", "status": "pending", "priority": "high" },
+  { "id": "run-workflow", "content": "Trigger GitHub Actions publish workflow", "status": "pending", "priority": "high" },
+  { "id": "wait-workflow", "content": "Wait for workflow completion (poll every 30s)", "status": "pending", "priority": "high" },
+  { "id": "verify-release", "content": "Verify GitHub release was created", "status": "pending", "priority": "high" },
+  { "id": "draft-release-notes", "content": "Draft enhanced release notes content", "status": "pending", "priority": "high" },
+  { "id": "update-release-notes", "content": "Update GitHub release with enhanced notes", "status": "pending", "priority": "high" },
+  { "id": "verify-npm", "content": "Verify npm package published successfully", "status": "pending", "priority": "high" },
+  { "id": "final-confirmation", "content": "Final confirmation to user with links", "status": "pending", "priority": "low" }
+]
+```
+
+**Mark each todo as `in_progress` when starting, `completed` when done. ONE AT A TIME.**
+
+---
+
+## STEP 1: CONFIRM BUMP TYPE
+
+If bump type provided as argument, confirm with user:
+> "버전 범프 타입: `{bump}`. 진행할까요? (y/n)"
+
+Wait for user confirmation before proceeding.
+
+---
+
+## STEP 2: CHECK UNCOMMITTED CHANGES
+
+Run: `git status --porcelain`
+
+- If there are uncommitted changes, warn user and ask if they want to commit first
+- If clean, proceed
+
+---
+
+## STEP 2.5: SYNC WITH REMOTE (MANDATORY)
+
+Check if there are unpushed commits:
+```bash
+git log origin/master..HEAD --oneline
+```
+
+**If there are unpushed commits, you MUST sync before triggering workflow:**
+```bash
+git pull --rebase && git push
+```
+
+This ensures the GitHub Actions workflow runs on the latest code including all local commits.
+
+---
+
+## STEP 3: TRIGGER GITHUB ACTIONS WORKFLOW
+
+Run the publish workflow:
+```bash
+gh workflow run publish -f bump={bump_type}
+```
+
+Wait 3 seconds, then get the run ID:
+```bash
+gh run list --workflow=publish --limit=1 --json databaseId,status --jq '.[0]'
+```
+
+---
+
+## STEP 4: WAIT FOR WORKFLOW COMPLETION
+
+Poll workflow status every 30 seconds until completion:
+```bash
+gh run view {run_id} --json status,conclusion --jq '{status: .status, conclusion: .conclusion}'
+```
+
+Status flow: `queued` → `in_progress` → `completed`
+
+**IMPORTANT: Use polling loop, NOT sleep commands.**
+
+If conclusion is `failure`, show error and stop:
+```bash
+gh run view {run_id} --log-failed
+```
+
+---
+
+## STEP 5: VERIFY GITHUB RELEASE
+
+Get the new version and verify release exists:
+```bash
+# Get new version from package.json (workflow updates it)
+git pull --rebase
+NEW_VERSION=$(node -p "require('./package.json').version")
+gh release view "v${NEW_VERSION}"
+```
+
+---
+
+## STEP 6: DRAFT ENHANCED RELEASE NOTES
+
+Analyze commits since the previous version and draft release notes following project conventions:
+
+### For PATCH releases:
+Keep simple format - just list commits:
+```markdown
+- {hash} {conventional commit message}
+- ...
+```
+
+### For MINOR releases:
+Use feature-focused format:
+```markdown
+## New Features
+
+### Feature Name
+- Description of what it does
+- Why it matters
+
+## Bug Fixes
+- fix(scope): description
+
+## Improvements
+- refactor(scope): description
+```
+
+### For MAJOR releases:
+Full changelog format:
+```markdown
+# v{version}
+
+Brief description of the release.
+
+## What's New Since v{previous}
+
+### Breaking Changes
+- Description of breaking change
+
+### Features
+- **Feature Name**: Description
+
+### Bug Fixes
+- Description
+
+### Documentation
+- Description
+
+## Migration Guide (if applicable)
+...
+```
+
+**CRITICAL: The enhanced notes must ADD to existing workflow-generated notes, not replace them.**
+
+---
+
+## STEP 7: UPDATE GITHUB RELEASE
+
+**ZERO CONTENT LOSS POLICY:**
+- First, fetch the existing release body with `gh release view`
+- Your enhanced notes must be PREPENDED to the existing content
+- **NOT A SINGLE CHARACTER of existing content may be removed or modified**
+- The final release body = `{your_enhanced_notes}\n\n---\n\n{existing_body_exactly_as_is}`
+
+```bash
+# Get existing body
+EXISTING_BODY=$(gh release view "v${NEW_VERSION}" --json body --jq '.body')
+
+# Write enhanced notes to temp file (prepend to existing)
+cat > /tmp/release-notes-v${NEW_VERSION}.md << 'EOF'
+{your_enhanced_notes}
+
+---
+
+EOF
+
+# Append existing body EXACTLY as-is (zero modifications)
+echo "$EXISTING_BODY" >> /tmp/release-notes-v${NEW_VERSION}.md
+
+# Update release
+gh release edit "v${NEW_VERSION}" --notes-file /tmp/release-notes-v${NEW_VERSION}.md
+```
+
+**CRITICAL: This is ADDITIVE ONLY. You are adding your notes on top. The existing content remains 100% intact.**
+
+---
+
+## STEP 8: VERIFY NPM PUBLICATION
+
+Poll npm registry until the new version appears:
+```bash
+npm view oh-my-opencode version
+```
+
+Compare with expected version. If not matching after 2 minutes, warn user about npm propagation delay.
+
+---
+
+## STEP 9: FINAL CONFIRMATION
+
+Report success to user with:
+- New version number
+- GitHub release URL: https://github.com/code-yeongyu/oh-my-opencode/releases/tag/v{version}
+- npm package URL: https://www.npmjs.com/package/oh-my-opencode
+
+---
+
+## ERROR HANDLING
+
+- **Workflow fails**: Show failed logs, suggest checking Actions tab
+- **Release not found**: Wait and retry, may be propagation delay
+- **npm not updated**: npm can take 1-5 minutes to propagate, inform user
+- **Permission denied**: User may need to re-authenticate with `gh auth login`
+
+## LANGUAGE
+
+Respond to user in Korean (한국어).
+
+</command-instruction>
+
+<current-context>
+<published-version>
+!`npm view oh-my-opencode version 2>/dev/null || echo "not published"`
+</published-version>
+<local-version>
+!`node -p "require('./package.json').version" 2>/dev/null || echo "unknown"`
+</local-version>
+<git-status>
+!`git status --porcelain`
+</git-status>
+<recent-commits>
+!`npm view oh-my-opencode version 2>/dev/null | xargs -I{} git log "v{}"..HEAD --oneline 2>/dev/null | head -15 || echo "no commits"`
+</recent-commits>
+</current-context>

AGENTS.md

@@ -1,115 +1,112 @@
 # PROJECT KNOWLEDGE BASE
 
-**Generated:** 2025-12-05T01:16:20+09:00
-**Commit:** 6c9a2ee
-**Branch:** master
+**Generated:** 2026-01-02T22:41:22+09:00
+**Commit:** d0694e5
+**Branch:** dev
 
 ## OVERVIEW
 
-OpenCode plugin distribution implementing Claude Code/AmpCode features. Provides multi-model agent orchestration, LSP tools, AST-Grep search, and safe-grep utilities.
+OpenCode plugin: multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemini 3, Grok), 11 LSP tools, AST-Grep, Claude Code compatibility layer. "oh-my-zsh" for OpenCode.
 
 ## STRUCTURE
 
 ```
 oh-my-opencode/
 ├── src/
-│   ├── agents/        # AI agent definitions (oracle, librarian, explore, etc.)
-│   ├── hooks/         # Plugin lifecycle hooks
-│   ├── tools/         # LSP, AST-Grep, Safe-Grep tool implementations
-│   │   ├── lsp/       # 11 LSP tools (hover, definition, references, etc.)
-│   │   ├── ast-grep/  # AST-aware code search
-│   │   └── safe-grep/ # Safe grep with limits
-│   └── features/      # Terminal features
-├── dist/              # Build output (bun + tsc declarations)
-└── test-rule.yml      # AST-Grep test rules
+│   ├── agents/        # 7 AI agents - see src/agents/AGENTS.md
+│   ├── hooks/         # 22 lifecycle hooks - see src/hooks/AGENTS.md
+│   ├── tools/         # LSP, AST-Grep, session mgmt - see src/tools/AGENTS.md
+│   ├── features/      # Claude Code compat layer - see src/features/AGENTS.md
+│   ├── auth/          # Google Antigravity OAuth - see src/auth/AGENTS.md
+│   ├── shared/        # Cross-cutting utilities - see src/shared/AGENTS.md
+│   ├── cli/           # CLI installer, doctor - see src/cli/AGENTS.md
+│   ├── mcp/           # MCP configs: context7, websearch_exa, grep_app
+│   ├── config/        # Zod schema, TypeScript types
+│   └── index.ts       # Main plugin entry (464 lines)
+├── script/            # build-schema.ts, publish.ts, generate-changelog.ts
+└── dist/              # Build output (ESM + .d.ts)
 ```
 
 ## WHERE TO LOOK
 
 | Task | Location | Notes |
 |------|----------|-------|
-| Add new agent | `src/agents/` | Export from index.ts |
-| Add new hook | `src/hooks/` | Export from index.ts |
-| Add new tool | `src/tools/` | Follow lsp/ pattern: index, types, tools, utils |
-| Modify LSP behavior | `src/tools/lsp/` | client.ts for connection logic |
-| AST-Grep patterns | `src/tools/ast-grep/` | napi.ts for @ast-grep/napi |
-| Terminal features | `src/features/terminal/` | title.ts |
-| Google Antigravity auth | `src/auth/antigravity/` | OAuth plugin for Google models |
+| Add agent | `src/agents/` | Create .ts, add to builtinAgents, update types.ts |
+| Add hook | `src/hooks/` | Dir with createXXXHook(), export from index.ts |
+| Add tool | `src/tools/` | Dir with constants/types/tools.ts, add to builtinTools |
+| Add MCP | `src/mcp/` | Create config, add to index.ts |
+| Add skill | `src/features/builtin-skills/` | Dir with SKILL.md |
+| Config schema | `src/config/schema.ts` | Run `bun run build:schema` after |
+| Claude Code compat | `src/features/claude-code-*-loader/` | Command, skill, agent, mcp loaders |
 
 ## CONVENTIONS
 
-- **Package manager**: Bun only (not npm/yarn)
-- **Build**: Dual output - `bun build` + `tsc --emitDeclarationOnly`
+- **Bun only**: `bun run`, `bun test`, `bunx` (NEVER npm/npx)
 - **Types**: bun-types (not @types/node)
-- **Exports**: Barrel pattern - `export * from "./module"` in index.ts
-- **Module structure**: index.ts, types.ts, constants.ts, utils.ts, tools.ts per tool
+- **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly`
+- **Exports**: Barrel pattern in index.ts; explicit named exports for tools/hooks
+- **Naming**: kebab-case directories, createXXXHook/createXXXTool factories
+- **Testing**: BDD comments `#given`, `#when`, `#then` (same as AAA)
+- **Temperature**: 0.1 for code agents, max 0.3
 
-## ANTI-PATTERNS (THIS PROJECT)
+## ANTI-PATTERNS
 
-- **Bash file operations**: Never use mkdir/touch/rm/cp/mv for file creation
-- **npm/yarn**: Use bun exclusively
-- **@types/node**: Use bun-types instead
-- **Generic AI aesthetics**: No Space Grotesk, avoid typical AI-generated UI patterns
-- **Rush completion**: Never mark tasks complete without verification
-- **Interrupting work**: Complete tasks fully before stopping
-
-## UNIQUE STYLES
-
-- **Directory naming**: kebab-case (`ast-grep/`, `safe-grep/`)
-- **Tool organization**: Each tool has cli.ts, constants.ts, index.ts, napi.ts/tools.ts, types.ts, utils.ts
-- **Platform handling**: Union type `"darwin" | "linux" | "win32" | "unsupported"`
-- **Error handling**: Consistent try/catch with async/await
-- **Optional props**: Extensive use of `?` for optional interface properties
-- **Flexible objects**: `Record<string, unknown>` for dynamic configs
+| Category | Forbidden |
+|----------|-----------|
+| Type Safety | `as any`, `@ts-ignore`, `@ts-expect-error` |
+| Package Manager | npm, yarn, npx |
+| File Ops | Bash mkdir/touch/rm for code file creation |
+| Publishing | Direct `bun publish`, local version bump |
+| Agent Behavior | High temp (>0.3), broad tool access, sequential agent calls |
+| Hooks | Heavy PreToolUse logic, blocking without reason |
+| Year | 2024 in code/prompts (use current year) |
 
 ## AGENT MODELS
 
 | Agent | Model | Purpose |
 |-------|-------|---------|
-| oracle | GPT-5.2 | Code review, strategic planning |
-| librarian | Claude Haiku | Documentation, example lookup |
-| explore | Grok | File/codebase exploration |
-| frontend-ui-ux-engineer | Gemini | UI generation |
-| document-writer | Gemini | Documentation writing |
+| Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator |
+| oracle | openai/gpt-5.2 | Strategy, code review |
+| librarian | anthropic/claude-sonnet-4-5 | Docs, OSS research |
+| explore | opencode/grok-code | Fast codebase grep |
+| frontend-ui-ux-engineer | google/gemini-3-pro-preview | UI generation |
+| document-writer | google/gemini-3-pro-preview | Technical docs |
+| multimodal-looker | google/gemini-3-flash | PDF/image analysis |
 
 ## COMMANDS
 
 ```bash
-# Type check
-bun run typecheck
-
-# Build
-bun run build
-
-# Clean + Build
-bun run rebuild
+bun run typecheck      # Type check
+bun run build          # ESM + declarations + schema
+bun run rebuild        # Clean + Build
+bun test               # Run tests (380+)
 ```
 
 ## DEPLOYMENT
 
-**배포는 GitHub Actions workflow_dispatch로만 진행**
+**GitHub Actions workflow_dispatch only**
 
-1. package.json 버전은 수정하지 않음 (워크플로우에서 자동 bump)
-2. 변경사항 커밋 & 푸시
-3. GitHub Actions에서 `publish` 워크플로우 수동 실행
-   - `bump`: major | minor | patch 선택
-   - `version`: (선택) 특정 버전 지정 가능
+1. Never modify package.json version locally
+2. Commit & push to dev
+3. Trigger: `gh workflow run publish -f bump=patch|minor|major`
 
-```bash
-# 워크플로우 실행 (CLI)
-gh workflow run publish -f bump=patch
+CI auto-commits schema changes on master, maintains rolling `next` draft release on dev.
 
-# 워크플로우 상태 확인
-gh run list --workflow=publish
-```
+## COMPLEXITY HOTSPOTS
 
-**주의사항**:
-- `bun publish` 직접 실행 금지 (OIDC provenance 문제)
-- 로컬에서 버전 bump 하지 말 것
+| File | Lines | Description |
+|------|-------|-------------|
+| `src/index.ts` | 464 | Main plugin, all hook/tool init |
+| `src/cli/config-manager.ts` | 669 | JSONC parsing, env detection |
+| `src/auth/antigravity/fetch.ts` | 621 | Token refresh, URL rewriting |
+| `src/tools/lsp/client.ts` | 611 | LSP protocol, JSON-RPC |
+| `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 564 | Multi-stage recovery |
+| `src/agents/sisyphus.ts` | 504 | Orchestrator prompt |
 
 ## NOTES
 
-- **No tests**: Test framework not configured
-- **CI/CD**: GitHub Actions publish workflow 사용
-- **Version requirement**: OpenCode >= 1.0.132 (earlier versions have config bugs)
-- **Multi-language docs**: README.md, README.en.md, README.ko.md
+- **OpenCode**: Requires >= 1.0.150
+- **Config**: `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`
+- **JSONC**: Config files support comments and trailing commas
+- **Claude Code**: Full compat layer for settings.json hooks, commands, skills, agents, MCPs
+- **Skill MCP**: Skills can embed MCP server configs in YAML frontmatter

CLA.md

@@ -0,0 +1,58 @@
+# Contributor License Agreement
+
+Thank you for your interest in contributing to oh-my-opencode ("Project"), owned by YeonGyu Kim ("Owner").
+
+By signing this Contributor License Agreement ("Agreement"), you agree to the following terms:
+
+## 1. Definitions
+
+- **"Contribution"** means any original work of authorship, including any modifications or additions to existing work, that you submit to the Project.
+- **"Submit"** means any form of communication sent to the Project, including but not limited to pull requests, issues, commits, and documentation changes.
+
+## 2. Grant of Rights
+
+By submitting a Contribution, you grant the Owner:
+
+1. **Copyright License**: A perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute your Contributions and such derivative works.
+
+2. **Patent License**: A perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Contribution.
+
+3. **Relicensing Rights**: The right to relicense the Contribution under any license, including proprietary licenses, without requiring additional permission from you.
+
+## 3. Representations
+
+You represent that:
+
+1. You are legally entitled to grant the above licenses.
+2. Each Contribution is your original creation or you have sufficient rights to submit it.
+3. Your Contribution does not violate any third party's intellectual property rights.
+4. If your employer has rights to intellectual property that you create, you have received permission to make Contributions on behalf of that employer.
+
+## 4. No Obligation
+
+You understand that:
+
+1. The Owner is not obligated to use or include your Contribution.
+2. The decision to include any Contribution is at the sole discretion of the Owner.
+3. You are not entitled to any compensation for your Contributions.
+
+## 5. Future License Changes
+
+You acknowledge and agree that:
+
+1. The Project may change its license in the future.
+2. Your Contributions may be distributed under a different license than the one in effect at the time of your Contribution.
+3. This includes, but is not limited to, relicensing under source-available or proprietary licenses.
+
+## 6. Miscellaneous
+
+- This Agreement is governed by the laws of the Republic of Korea.
+- This Agreement represents the entire agreement between you and the Owner concerning Contributions.
+
+---
+
+## How to Sign
+
+By submitting a pull request to this repository, you agree to the terms of this Contributor License Agreement. The CLA Assistant bot will automatically track your agreement.
+
+If you have any questions, please open an issue or contact the Owner.

CONTRIBUTING.md

@@ -0,0 +1,245 @@
+# Contributing to Oh My OpenCode
+
+First off, thanks for taking the time to contribute! This document provides guidelines and instructions for contributing to oh-my-opencode.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+  - [Prerequisites](#prerequisites)
+  - [Development Setup](#development-setup)
+  - [Testing Your Changes Locally](#testing-your-changes-locally)
+- [Project Structure](#project-structure)
+- [Development Workflow](#development-workflow)
+  - [Build Commands](#build-commands)
+  - [Code Style & Conventions](#code-style--conventions)
+- [Making Changes](#making-changes)
+  - [Adding a New Agent](#adding-a-new-agent)
+  - [Adding a New Hook](#adding-a-new-hook)
+  - [Adding a New Tool](#adding-a-new-tool)
+  - [Adding a New MCP Server](#adding-a-new-mcp-server)
+- [Pull Request Process](#pull-request-process)
+- [Publishing](#publishing)
+- [Getting Help](#getting-help)
+
+## Code of Conduct
+
+Be respectful, inclusive, and constructive. We're all here to make better tools together.
+
+## Getting Started
+
+### Prerequisites
+
+- **Bun** (latest version) - The only supported package manager
+- **TypeScript 5.7.3+** - For type checking and declarations
+- **OpenCode 1.0.150+** - For testing the plugin
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/code-yeongyu/oh-my-opencode.git
+cd oh-my-opencode
+
+# Install dependencies (bun only - never use npm/yarn)
+bun install
+
+# Build the project
+bun run build
+```
+
+### Testing Your Changes Locally
+
+After making changes, you can test your local build in OpenCode:
+
+1. **Build the project**:
+   ```bash
+   bun run build
+   ```
+
+2. **Update your OpenCode config** (`~/.config/opencode/opencode.json` or `opencode.jsonc`):
+   ```json
+   {
+     "plugin": [
+       "file:///absolute/path/to/oh-my-opencode/dist/index.js"
+     ]
+   }
+   ```
+   
+   For example, if your project is at `/Users/yourname/projects/oh-my-opencode`:
+   ```json
+   {
+     "plugin": [
+       "file:///Users/yourname/projects/oh-my-opencode/dist/index.js"
+     ]
+   }
+   ```
+
+   > **Note**: Remove `"oh-my-opencode"` from the plugin array if it exists, to avoid conflicts with the npm version.
+
+3. **Restart OpenCode** to load the changes.
+
+4. **Verify** the plugin is loaded by checking for OmO agent availability or startup messages.
+
+## Project Structure
+
+```
+oh-my-opencode/
+├── src/
+│   ├── agents/        # AI agents (OmO, oracle, librarian, explore, etc.)
+│   ├── hooks/         # 21 lifecycle hooks
+│   ├── tools/         # LSP (11), AST-Grep, Grep, Glob, etc.
+│   ├── mcp/           # MCP server integrations (context7, websearch_exa, grep_app)
+│   ├── features/      # Claude Code compatibility layers
+│   ├── config/        # Zod schemas and TypeScript types
+│   ├── auth/          # Google Antigravity OAuth
+│   ├── shared/        # Common utilities
+│   └── index.ts       # Main plugin entry (OhMyOpenCodePlugin)
+├── script/            # Build utilities (build-schema.ts, publish.ts)
+├── assets/            # JSON schema
+└── dist/              # Build output (ESM + .d.ts)
+```
+
+## Development Workflow
+
+### Build Commands
+
+```bash
+# Type check only
+bun run typecheck
+
+# Full build (ESM + TypeScript declarations + JSON schema)
+bun run build
+
+# Clean build output and rebuild
+bun run rebuild
+
+# Build schema only (after modifying src/config/schema.ts)
+bun run build:schema
+```
+
+### Code Style & Conventions
+
+| Convention | Rule |
+|------------|------|
+| Package Manager | **Bun only** (`bun run`, `bun build`, `bunx`) |
+| Types | Use `bun-types`, not `@types/node` |
+| Directory Naming | kebab-case (`ast-grep/`, `claude-code-hooks/`) |
+| File Operations | Never use bash commands (mkdir/touch/rm) for file creation in code |
+| Tool Structure | Each tool: `index.ts`, `types.ts`, `constants.ts`, `tools.ts`, `utils.ts` |
+| Hook Pattern | `createXXXHook(input: PluginInput)` function naming |
+| Exports | Barrel pattern (`export * from "./module"` in index.ts) |
+
+**Anti-Patterns (Do Not Do)**:
+- Using npm/yarn instead of bun
+- Using `@types/node` instead of `bun-types`
+- Suppressing TypeScript errors with `as any`, `@ts-ignore`, `@ts-expect-error`
+- Generic AI-generated comment bloat
+- Direct `bun publish` (use GitHub Actions only)
+- Local version modifications in `package.json`
+
+## Making Changes
+
+### Adding a New Agent
+
+1. Create a new `.ts` file in `src/agents/`
+2. Define the agent configuration following existing patterns
+3. Add to `builtinAgents` in `src/agents/index.ts`
+4. Update `src/agents/types.ts` if needed
+5. Run `bun run build:schema` to update the JSON schema
+
+```typescript
+// src/agents/my-agent.ts
+import type { AgentConfig } from "./types";
+
+export const myAgent: AgentConfig = {
+  name: "my-agent",
+  model: "anthropic/claude-sonnet-4-5",
+  description: "Description of what this agent does",
+  prompt: `Your agent's system prompt here`,
+  temperature: 0.1,
+  // ... other config
+};
+```
+
+### Adding a New Hook
+
+1. Create a new directory in `src/hooks/` (kebab-case)
+2. Implement `createXXXHook()` function returning event handlers
+3. Export from `src/hooks/index.ts`
+
+```typescript
+// src/hooks/my-hook/index.ts
+import type { PluginInput } from "@opencode-ai/plugin";
+
+export function createMyHook(input: PluginInput) {
+  return {
+    onSessionStart: async () => {
+      // Hook logic here
+    },
+  };
+}
+```
+
+### Adding a New Tool
+
+1. Create a new directory in `src/tools/` with required files:
+   - `index.ts` - Main exports
+   - `types.ts` - TypeScript interfaces
+   - `constants.ts` - Constants and tool descriptions
+   - `tools.ts` - Tool implementations
+   - `utils.ts` - Helper functions
+2. Add to `builtinTools` in `src/tools/index.ts`
+
+### Adding a New MCP Server
+
+1. Create configuration in `src/mcp/`
+2. Add to `src/mcp/index.ts`
+3. Document in README if it requires external setup
+
+## Pull Request Process
+
+1. **Fork** the repository and create your branch from `master`
+2. **Make changes** following the conventions above
+3. **Build and test** locally:
+   ```bash
+   bun run typecheck  # Ensure no type errors
+   bun run build      # Ensure build succeeds
+   ```
+4. **Test in OpenCode** using the local build method described above
+5. **Commit** with clear, descriptive messages:
+   - Use present tense ("Add feature" not "Added feature")
+   - Reference issues if applicable ("Fix #123")
+6. **Push** to your fork and create a Pull Request
+7. **Describe** your changes clearly in the PR description
+
+### PR Checklist
+
+- [ ] Code follows project conventions
+- [ ] `bun run typecheck` passes
+- [ ] `bun run build` succeeds
+- [ ] Tested locally with OpenCode
+- [ ] Updated documentation if needed (README, AGENTS.md)
+- [ ] No version changes in `package.json`
+
+## Publishing
+
+**Important**: Publishing is handled exclusively through GitHub Actions.
+
+- **Never** run `bun publish` directly (OIDC provenance issues)
+- **Never** modify `package.json` version locally
+- Maintainers use GitHub Actions workflow_dispatch:
+  ```bash
+  gh workflow run publish -f bump=patch  # or minor/major
+  ```
+
+## Getting Help
+
+- **Project Knowledge**: Check `AGENTS.md` for detailed project documentation
+- **Code Patterns**: Review existing implementations in `src/`
+- **Issues**: Open an issue for bugs or feature requests
+- **Discussions**: Start a discussion for questions or ideas
+
+---
+
+Thank you for contributing to Oh My OpenCode! Your efforts help make AI-assisted coding better for everyone.

LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 YeonGyu Kim
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

LICENSE.md

@@ -0,0 +1,82 @@
+# License
+
+Portions of this software are licensed as follows:
+
+- All third party components incorporated into the oh-my-opencode Software are licensed under the original license
+  provided by the owner of the applicable component.
+- Content outside of the above mentioned files or restrictions is available under the "Sustainable Use
+  License" as defined below.
+
+## Sustainable Use License
+
+Version 1.0
+
+### Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+### Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license
+to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+### Limitations
+
+You may use or modify the software only for your own internal business purposes or for non-commercial or
+personal use. You may distribute the software or provide it to others only if you do so free of charge for
+non-commercial purposes. You may not alter, remove, or obscure any licensing, copyright, or other notices of
+the licensor in the software. Any use of the licensor's trademarks is subject to applicable law.
+
+### Patents
+
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to
+license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case
+subject to the limitations and conditions in this license. This license does not cover any patent claims that
+you cause to be infringed by modifications or additions to the software. If you or your company make any
+written claim that the software infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+### Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these
+terms. If you modify the software, you must include in any modified copies of the software a prominent notice
+stating that you have modified the software.
+
+### No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+### Termination
+
+If you use the software in violation of these terms, such use is not licensed, and your license will
+automatically terminate. If the licensor provides you with a notice of your violation, and you cease all
+violation of this license no later than 30 days after you receive that notice, your license will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any additional violation of these
+terms will cause your license to terminate automatically and permanently.
+
+### No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will
+not be liable to you for any damages arising out of these terms or the use or nature of the software, under
+any kind of legal claim.
+
+### Definitions
+
+The "licensor" is the entity offering these terms.
+
+The "software" is the software the licensor makes available under these terms, including any portion of it.
+
+"You" refers to the individual or entity agreeing to these terms.
+
+"Your company" is any legal entity, sole proprietorship, or other kind of organization that you work for, plus
+all organizations that have control over, are under the control of, or are under common control with that
+organization. Control means ownership of substantially all the assets of an entity, or the power to direct its
+management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+"Your license" is the license granted to you for the software under these terms.
+
+"Use" means anything you do with the software requiring your license.
+
+"Trademark" means trademarks, service marks, and similar rights.

bun.lock

@@ -7,23 +7,27 @@
       "dependencies": {
         "@ast-grep/cli": "^0.40.0",
         "@ast-grep/napi": "^0.40.0",
-        "@code-yeongyu/comment-checker": "^0.5.0",
+        "@clack/prompts": "^0.11.0",
+        "@code-yeongyu/comment-checker": "^0.6.1",
+        "@modelcontextprotocol/sdk": "^1.25.1",
         "@openauthjs/openauth": "^0.4.3",
-        "@opencode-ai/plugin": "^1.0.150",
+        "@opencode-ai/plugin": "^1.0.162",
+        "@opencode-ai/sdk": "^1.0.162",
+        "commander": "^14.0.2",
         "hono": "^4.10.4",
+        "js-yaml": "^4.1.1",
+        "jsonc-parser": "^3.3.1",
+        "picocolors": "^1.1.1",
         "picomatch": "^4.0.2",
         "xdg-basedir": "^5.1.0",
         "zod": "^4.1.8",
       },
       "devDependencies": {
+        "@types/js-yaml": "^4.0.9",
         "@types/picomatch": "^3.0.2",
         "bun-types": "latest",
-        "oh-my-opencode": "^0.1.30",
         "typescript": "^5.7.3",
       },
-      "peerDependencies": {
-        "bun": ">=1.0.0",
-      },
     },
   },
   "trustedDependencies": [
@@ -68,13 +72,21 @@
 
     "@ast-grep/napi-win32-x64-msvc": ["@ast-grep/napi-win32-x64-msvc@0.40.0", "", { "os": "win32", "cpu": "x64" }, "sha512-Hk2IwfPqMFGZt5SRxsoWmGLxBXxprow4LRp1eG6V8EEiJCNHxZ9ZiEaIc5bNvMDBjHVSnqZAXT22dROhrcSKQg=="],
 
-    "@code-yeongyu/comment-checker": ["@code-yeongyu/comment-checker@0.5.0", "", { "os": [ "linux", "win32", "darwin", ], "cpu": [ "x64", "arm64", ], "bin": { "comment-checker": "bin/comment-checker" } }, "sha512-rKD2qQnTVUacsVQtpu3I5Sxi09X/XpOwS9fcmbUv1yfUL6llraaPuLmmxMBMRcmm7Zu31yEPVKCeUkVODfRL1g=="],
+    "@clack/core": ["@clack/core@0.5.0", "", { "dependencies": { "picocolors": "^1.0.0", "sisteransi": "^1.0.5" } }, "sha512-p3y0FIOwaYRUPRcMO7+dlmLh8PSRcrjuTndsiA0WAFbWES0mLZlrjVoBRZ9DzkPFJZG6KGkJmoEAY0ZcVWTkow=="],
+
+    "@clack/prompts": ["@clack/prompts@0.11.0", "", { "dependencies": { "@clack/core": "0.5.0", "picocolors": "^1.0.0", "sisteransi": "^1.0.5" } }, "sha512-pMN5FcrEw9hUkZA4f+zLlzivQSeQf5dRGJjSUbvVYDLvpKCdQx5OaknvKzgbtXOizhP+SJJJjqEbOe55uKKfAw=="],
+
+    "@code-yeongyu/comment-checker": ["@code-yeongyu/comment-checker@0.6.1", "", { "os": [ "linux", "win32", "darwin", ], "cpu": [ "x64", "arm64", ], "bin": { "comment-checker": "bin/comment-checker" } }, "sha512-BBremX+Y5aW8sTzlhHrLsKParupYkPOVUYmq9STrlWvBvfAme6w5IWuZCLl6nHIQScRDdvGdrAjPycJC86EZFA=="],
+
+    "@hono/node-server": ["@hono/node-server@1.19.7", "", { "peerDependencies": { "hono": "^4" } }, "sha512-vUcD0uauS7EU2caukW8z5lJKtoGMokxNbJtBiwHgpqxEXokaHCBkQUmCHhjFB1VUTWdqj25QoMkMKzgjq+uhrw=="],
+
+    "@modelcontextprotocol/sdk": ["@modelcontextprotocol/sdk@1.25.1", "", { "dependencies": { "@hono/node-server": "^1.19.7", "ajv": "^8.17.1", "ajv-formats": "^3.0.1", "content-type": "^1.0.5", "cors": "^2.8.5", "cross-spawn": "^7.0.5", "eventsource": "^3.0.2", "eventsource-parser": "^3.0.0", "express": "^5.0.1", "express-rate-limit": "^7.5.0", "jose": "^6.1.1", "json-schema-typed": "^8.0.2", "pkce-challenge": "^5.0.0", "raw-body": "^3.0.0", "zod": "^3.25 || ^4.0", "zod-to-json-schema": "^3.25.0" }, "peerDependencies": { "@cfworker/json-schema": "^4.1.1" }, "optionalPeers": ["@cfworker/json-schema"] }, "sha512-yO28oVFFC7EBoiKdAn+VqRm+plcfv4v0xp6osG/VsCB0NlPZWi87ajbCZZ8f/RvOFLEu7//rSRmuZZ7lMoe3gQ=="],
 
     "@openauthjs/openauth": ["@openauthjs/openauth@0.4.3", "", { "dependencies": { "@standard-schema/spec": "1.0.0-beta.3", "aws4fetch": "1.0.20", "jose": "5.9.6" }, "peerDependencies": { "arctic": "^2.2.2", "hono": "^4.0.0" } }, "sha512-RlnjqvHzqcbFVymEwhlUEuac4utA5h4nhSK/i2szZuQmxTIqbGUxZ+nM+avM+VV4Ing+/ZaNLKILoXS3yrkOOw=="],
 
-    "@opencode-ai/plugin": ["@opencode-ai/plugin@1.0.150", "", { "dependencies": { "@opencode-ai/sdk": "1.0.150", "zod": "4.1.8" } }, "sha512-XmY3yydk120GBv2KeLxSZlElFx4Zx9TYLa3bS9X1TxXot42UeoMLEi3Xa46yboYnWwp4bC9Fu+Gd1E7hypG8Jw=="],
+    "@opencode-ai/plugin": ["@opencode-ai/plugin@1.0.162", "", { "dependencies": { "@opencode-ai/sdk": "1.0.162", "zod": "4.1.8" } }, "sha512-tiJw7SCfSlG/3tY2O0J2UT06OLuazOzsv1zYlFbLxLy/EVedtW0pzxYalO20a4e//vInvOXFkhd2jLyB5vNEVA=="],
 
-    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.0.150", "", {}, "sha512-Nz9Di8UD/GK01w3N+jpiGNB733pYkNY8RNLbuE/HUxEGSP5apbXBY0IdhbW7859sXZZK38kF1NqOx4UxwBf4Bw=="],
+    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.0.162", "", {}, "sha512-+XqRErBUt9eb1m3i/7WkZc/QCKCCjTaGV3MvhLhs/CUwbUn767D/ugzcG/i2ec8j/4nQmjJbjPDRmrQfvF1Qjw=="],
 
     "@oslojs/asn1": ["@oslojs/asn1@1.0.0", "", { "dependencies": { "@oslojs/binary": "1.0.0" } }, "sha512-zw/wn0sj0j0QKbIXfIlnEcTviaCzYOY3V5rAyjR6YtOByFtJiT574+8p9Wlach0lZH9fddD4yb9laEAIl4vXQA=="],
 
@@ -86,66 +98,220 @@
 
     "@oslojs/jwt": ["@oslojs/jwt@0.2.0", "", { "dependencies": { "@oslojs/encoding": "0.4.1" } }, "sha512-bLE7BtHrURedCn4Mco3ma9L4Y1GR2SMBuIvjWr7rmQ4/W/4Jy70TIAgZ+0nIlk0xHz1vNP8x8DCns45Sb2XRbg=="],
 
-    "@oven/bun-darwin-aarch64": ["@oven/bun-darwin-aarch64@1.3.3", "", { "os": "darwin", "cpu": "arm64" }, "sha512-eJopQrUk0WR7jViYDC29+Rp50xGvs4GtWOXBeqCoFMzutkkO3CZvHehA4JqnjfWMTSS8toqvRhCSOpOz62Wf9w=="],
-
-    "@oven/bun-darwin-x64": ["@oven/bun-darwin-x64@1.3.3", "", { "os": "darwin", "cpu": "x64" }, "sha512-xGDePueVFrNgkS+iN0QdEFeRrx2MQ5hQ9ipRFu7N73rgoSSJsFlOKKt2uGZzunczedViIfjYl0ii0K4E9aZ0Ow=="],
-
-    "@oven/bun-darwin-x64-baseline": ["@oven/bun-darwin-x64-baseline@1.3.3", "", { "os": "darwin", "cpu": "x64" }, "sha512-1ij4wQ9ECLFf1XFry+IFUN+28if40ozDqq6+QtuyOhIwraKzXOlAUbILhRMGvM3ED3yBex2mTwlKpA4Vja/V2g=="],
-
-    "@oven/bun-linux-aarch64": ["@oven/bun-linux-aarch64@1.3.3", "", { "os": "linux", "cpu": "arm64" }, "sha512-DabZ3Mt1XcJneWdEEug8l7bCPVvDBRBpjUIpNnRnMFWFnzr8KBEpMcaWTwYOghjXyJdhB4MPKb19MwqyQ+FHAw=="],
-
-    "@oven/bun-linux-aarch64-musl": ["@oven/bun-linux-aarch64-musl@1.3.3", "", { "os": "linux", "cpu": "arm64" }, "sha512-XWQ3tV/gtZj0wn2AdSUq/tEOKWT4OY+Uww70EbODgrrq00jxuTfq5nnYP6rkLD0M/T5BHJdQRSfQYdIni9vldw=="],
-
-    "@oven/bun-linux-x64": ["@oven/bun-linux-x64@1.3.3", "", { "os": "linux", "cpu": "x64" }, "sha512-7eIARtKZKZDtah1aCpQUj/1/zT/zHRR063J6oAxZP9AuA547j5B9OM2D/vi/F4En7Gjk9FPjgPGTSYeqpQDzJw=="],
-
-    "@oven/bun-linux-x64-baseline": ["@oven/bun-linux-x64-baseline@1.3.3", "", { "os": "linux", "cpu": "x64" }, "sha512-IU8pxhIf845psOv55LqJyL+tSUc6HHMfs6FGhuJcAnyi92j+B1HjOhnFQh9MW4vjoo7do5F8AerXlvk59RGH2w=="],
-
-    "@oven/bun-linux-x64-musl": ["@oven/bun-linux-x64-musl@1.3.3", "", { "os": "linux", "cpu": "x64" }, "sha512-xNSDRPn1yyObKteS8fyQogwsS4eCECswHHgaKM+/d4wy/omZQrXn8ZyGm/ZF9B73UfQytUfbhE7nEnrFq03f0w=="],
-
-    "@oven/bun-linux-x64-musl-baseline": ["@oven/bun-linux-x64-musl-baseline@1.3.3", "", { "os": "linux", "cpu": "x64" }, "sha512-JoRTPdAXRkNYouUlJqEncMWUKn/3DiWP03A7weBbtbsKr787gcdNna2YeyQKCb1lIXE4v1k18RM3gaOpQobGIQ=="],
-
-    "@oven/bun-windows-x64": ["@oven/bun-windows-x64@1.3.3", "", { "os": "win32", "cpu": "x64" }, "sha512-kWqa1LKvDdAIzyfHxo3zGz3HFWbFHDlrNK77hKjUN42ycikvZJ+SHSX76+1OW4G8wmLETX4Jj+4BM1y01DQRIQ=="],
-
-    "@oven/bun-windows-x64-baseline": ["@oven/bun-windows-x64-baseline@1.3.3", "", { "os": "win32", "cpu": "x64" }, "sha512-u5eZHKq6TPJSE282KyBOicGQ2trkFml0RoUfqkPOJVo7TXGrsGYYzdsugZRnVQY/WEmnxGtBy4T3PAaPqgQViA=="],
-
     "@standard-schema/spec": ["@standard-schema/spec@1.0.0-beta.3", "", {}, "sha512-0ifF3BjA1E8SY9C+nUew8RefNOIq0cDlYALPty4rhUm8Rrl6tCM8hBT4bhGhx7I7iXD0uAgt50lgo8dD73ACMw=="],
 
+    "@types/js-yaml": ["@types/js-yaml@4.0.9", "", {}, "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg=="],
+
     "@types/node": ["@types/node@24.10.1", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-GNWcUTRBgIRJD5zj+Tq0fKOJ5XZajIiBroOF0yvj2bSU1WvNdYS/dn9UxwsujGW4JX06dnHyjV2y9rRaybH0iQ=="],
 
     "@types/picomatch": ["@types/picomatch@3.0.2", "", {}, "sha512-n0i8TD3UDB7paoMMxA3Y65vUncFJXjcUf7lQY7YyKGl6031FNjfsLs6pdLFCy2GNFxItPJG8GvvpbZc2skH7WA=="],
 
+    "accepts": ["accepts@2.0.0", "", { "dependencies": { "mime-types": "^3.0.0", "negotiator": "^1.0.0" } }, "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng=="],
+
+    "ajv": ["ajv@8.17.1", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g=="],
+
+    "ajv-formats": ["ajv-formats@3.0.1", "", { "dependencies": { "ajv": "^8.0.0" } }, "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ=="],
+
     "arctic": ["arctic@2.3.4", "", { "dependencies": { "@oslojs/crypto": "1.0.1", "@oslojs/encoding": "1.1.0", "@oslojs/jwt": "0.2.0" } }, "sha512-+p30BOWsctZp+CVYCt7oAean/hWGW42sH5LAcRQX56ttEkFJWbzXBhmSpibbzwSJkRrotmsA+oAoJoVsU0f5xA=="],
 
+    "argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="],
+
     "aws4fetch": ["aws4fetch@1.0.20", "", {}, "sha512-/djoAN709iY65ETD6LKCtyyEI04XIBP5xVvfmNxsEP0uJB5tyaGBztSryRr4HqMStr9R06PisQE7m9zDTXKu6g=="],
 
-    "bun": ["bun@1.3.3", "", { "optionalDependencies": { "@oven/bun-darwin-aarch64": "1.3.3", "@oven/bun-darwin-x64": "1.3.3", "@oven/bun-darwin-x64-baseline": "1.3.3", "@oven/bun-linux-aarch64": "1.3.3", "@oven/bun-linux-aarch64-musl": "1.3.3", "@oven/bun-linux-x64": "1.3.3", "@oven/bun-linux-x64-baseline": "1.3.3", "@oven/bun-linux-x64-musl": "1.3.3", "@oven/bun-linux-x64-musl-baseline": "1.3.3", "@oven/bun-windows-x64": "1.3.3", "@oven/bun-windows-x64-baseline": "1.3.3" }, "os": [ "linux", "win32", "darwin", ], "cpu": [ "x64", "arm64", ], "bin": { "bun": "bin/bun.exe", "bunx": "bin/bunx.exe" } }, "sha512-2hJ4ocTZ634/Ptph4lysvO+LbbRZq8fzRvMwX0/CqaLBxrF2UB5D1LdMB8qGcdtCer4/VR9Bx5ORub0yn+yzmw=="],
+    "body-parser": ["body-parser@2.2.1", "", { "dependencies": { "bytes": "^3.1.2", "content-type": "^1.0.5", "debug": "^4.4.3", "http-errors": "^2.0.0", "iconv-lite": "^0.7.0", "on-finished": "^2.4.1", "qs": "^6.14.0", "raw-body": "^3.0.1", "type-is": "^2.0.1" } }, "sha512-nfDwkulwiZYQIGwxdy0RUmowMhKcFVcYXUU7m4QlKYim1rUtg83xm2yjZ40QjDuc291AJjjeSc9b++AWHSgSHw=="],
 
     "bun-types": ["bun-types@1.3.3", "", { "dependencies": { "@types/node": "*" } }, "sha512-z3Xwlg7j2l9JY27x5Qn3Wlyos8YAp0kKRlrePAOjgjMGS5IG6E7Jnlx736vH9UVI4wUICwwhC9anYL++XeOgTQ=="],
 
+    "bytes": ["bytes@3.1.2", "", {}, "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg=="],
+
+    "call-bind-apply-helpers": ["call-bind-apply-helpers@1.0.2", "", { "dependencies": { "es-errors": "^1.3.0", "function-bind": "^1.1.2" } }, "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ=="],
+
+    "call-bound": ["call-bound@1.0.4", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.2", "get-intrinsic": "^1.3.0" } }, "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg=="],
+
+    "commander": ["commander@14.0.2", "", {}, "sha512-TywoWNNRbhoD0BXs1P3ZEScW8W5iKrnbithIl0YH+uCmBd0QpPOA8yc82DS3BIE5Ma6FnBVUsJ7wVUDz4dvOWQ=="],
+
+    "content-disposition": ["content-disposition@1.0.1", "", {}, "sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q=="],
+
+    "content-type": ["content-type@1.0.5", "", {}, "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA=="],
+
+    "cookie": ["cookie@0.7.2", "", {}, "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w=="],
+
+    "cookie-signature": ["cookie-signature@1.2.2", "", {}, "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg=="],
+
+    "cors": ["cors@2.8.5", "", { "dependencies": { "object-assign": "^4", "vary": "^1" } }, "sha512-KIHbLJqu73RGr/hnbrO9uBeixNGuvSQjul/jdFvS/KFSIH1hWVd1ng7zOHx+YrEfInLG7q4n6GHQ9cDtxv/P6g=="],
+
+    "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
+
+    "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
+
+    "depd": ["depd@2.0.0", "", {}, "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw=="],
+
     "detect-libc": ["detect-libc@2.1.2", "", {}, "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ=="],
 
+    "dunder-proto": ["dunder-proto@1.0.1", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.1", "es-errors": "^1.3.0", "gopd": "^1.2.0" } }, "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A=="],
+
+    "ee-first": ["ee-first@1.1.1", "", {}, "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow=="],
+
+    "encodeurl": ["encodeurl@2.0.0", "", {}, "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg=="],
+
+    "es-define-property": ["es-define-property@1.0.1", "", {}, "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g=="],
+
+    "es-errors": ["es-errors@1.3.0", "", {}, "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw=="],
+
+    "es-object-atoms": ["es-object-atoms@1.1.1", "", { "dependencies": { "es-errors": "^1.3.0" } }, "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA=="],
+
+    "escape-html": ["escape-html@1.0.3", "", {}, "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow=="],
+
+    "etag": ["etag@1.8.1", "", {}, "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg=="],
+
+    "eventsource": ["eventsource@3.0.7", "", { "dependencies": { "eventsource-parser": "^3.0.1" } }, "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA=="],
+
+    "eventsource-parser": ["eventsource-parser@3.0.6", "", {}, "sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg=="],
+
+    "express": ["express@5.2.1", "", { "dependencies": { "accepts": "^2.0.0", "body-parser": "^2.2.1", "content-disposition": "^1.0.0", "content-type": "^1.0.5", "cookie": "^0.7.1", "cookie-signature": "^1.2.1", "debug": "^4.4.0", "depd": "^2.0.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "finalhandler": "^2.1.0", "fresh": "^2.0.0", "http-errors": "^2.0.0", "merge-descriptors": "^2.0.0", "mime-types": "^3.0.0", "on-finished": "^2.4.1", "once": "^1.4.0", "parseurl": "^1.3.3", "proxy-addr": "^2.0.7", "qs": "^6.14.0", "range-parser": "^1.2.1", "router": "^2.2.0", "send": "^1.1.0", "serve-static": "^2.2.0", "statuses": "^2.0.1", "type-is": "^2.0.1", "vary": "^1.1.2" } }, "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw=="],
+
+    "express-rate-limit": ["express-rate-limit@7.5.1", "", { "peerDependencies": { "express": ">= 4.11" } }, "sha512-7iN8iPMDzOMHPUYllBEsQdWVB6fPDMPqwjBaFrgr4Jgr/+okjvzAy+UHlYYL/Vs0OsOrMkwS6PJDkFlJwoxUnw=="],
+
+    "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
+
+    "fast-uri": ["fast-uri@3.1.0", "", {}, "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA=="],
+
+    "finalhandler": ["finalhandler@2.1.1", "", { "dependencies": { "debug": "^4.4.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "on-finished": "^2.4.1", "parseurl": "^1.3.3", "statuses": "^2.0.1" } }, "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA=="],
+
+    "forwarded": ["forwarded@0.2.0", "", {}, "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow=="],
+
+    "fresh": ["fresh@2.0.0", "", {}, "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A=="],
+
+    "function-bind": ["function-bind@1.1.2", "", {}, "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA=="],
+
+    "get-intrinsic": ["get-intrinsic@1.3.0", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.2", "es-define-property": "^1.0.1", "es-errors": "^1.3.0", "es-object-atoms": "^1.1.1", "function-bind": "^1.1.2", "get-proto": "^1.0.1", "gopd": "^1.2.0", "has-symbols": "^1.1.0", "hasown": "^2.0.2", "math-intrinsics": "^1.1.0" } }, "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ=="],
+
+    "get-proto": ["get-proto@1.0.1", "", { "dependencies": { "dunder-proto": "^1.0.1", "es-object-atoms": "^1.0.0" } }, "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g=="],
+
+    "gopd": ["gopd@1.2.0", "", {}, "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg=="],
+
+    "has-symbols": ["has-symbols@1.1.0", "", {}, "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ=="],
+
+    "hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
+
     "hono": ["hono@4.10.8", "", {}, "sha512-DDT0A0r6wzhe8zCGoYOmMeuGu3dyTAE40HHjwUsWFTEy5WxK1x2WDSsBPlEXgPbRIFY6miDualuUDbasPogIww=="],
 
-    "jose": ["jose@5.9.6", "", {}, "sha512-AMlnetc9+CV9asI19zHmrgS/WYsWUwCn2R7RzlbJWD7F9eWYUTGyBmU9o6PxngtLGOiDGPRu+Uc4fhKzbpteZQ=="],
+    "http-errors": ["http-errors@2.0.1", "", { "dependencies": { "depd": "~2.0.0", "inherits": "~2.0.4", "setprototypeof": "~1.2.0", "statuses": "~2.0.2", "toidentifier": "~1.0.1" } }, "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ=="],
 
-    "oh-my-opencode": ["oh-my-opencode@0.1.30", "", { "dependencies": { "@ast-grep/cli": "^0.40.0", "@ast-grep/napi": "^0.40.0", "@code-yeongyu/comment-checker": "^0.4.1", "@opencode-ai/plugin": "^1.0.7", "xdg-basedir": "^5.1.0", "zod": "^4.1.8" }, "peerDependencies": { "bun": ">=1.0.0" } }, "sha512-pXGGgL/7Jcz3yuGJJTI72BKern2egwfRz2LQZTBq+jl+pNCybOvGvXtFmR+WGlF8O3ZjL1wIHypBbIVuHOBzxg=="],
+    "iconv-lite": ["iconv-lite@0.7.1", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-2Tth85cXwGFHfvRgZWszZSvdo+0Xsqmw8k8ZwxScfcBneNUraK+dxRxRm24nszx80Y0TVio8kKLt5sLE7ZCLlw=="],
+
+    "inherits": ["inherits@2.0.4", "", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="],
+
+    "ipaddr.js": ["ipaddr.js@1.9.1", "", {}, "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g=="],
+
+    "is-promise": ["is-promise@4.0.0", "", {}, "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ=="],
+
+    "isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
+
+    "jose": ["jose@6.1.3", "", {}, "sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ=="],
+
+    "js-yaml": ["js-yaml@4.1.1", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA=="],
+
+    "json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
+
+    "json-schema-typed": ["json-schema-typed@8.0.2", "", {}, "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA=="],
+
+    "jsonc-parser": ["jsonc-parser@3.3.1", "", {}, "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ=="],
+
+    "math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
+
+    "media-typer": ["media-typer@1.1.0", "", {}, "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw=="],
+
+    "merge-descriptors": ["merge-descriptors@2.0.0", "", {}, "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g=="],
+
+    "mime-db": ["mime-db@1.54.0", "", {}, "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ=="],
+
+    "mime-types": ["mime-types@3.0.2", "", { "dependencies": { "mime-db": "^1.54.0" } }, "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A=="],
+
+    "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
+
+    "negotiator": ["negotiator@1.0.0", "", {}, "sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg=="],
+
+    "object-assign": ["object-assign@4.1.1", "", {}, "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg=="],
+
+    "object-inspect": ["object-inspect@1.13.4", "", {}, "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew=="],
+
+    "on-finished": ["on-finished@2.4.1", "", { "dependencies": { "ee-first": "1.1.1" } }, "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg=="],
+
+    "once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
+
+    "parseurl": ["parseurl@1.3.3", "", {}, "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ=="],
+
+    "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
+
+    "path-to-regexp": ["path-to-regexp@8.3.0", "", {}, "sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA=="],
+
+    "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
 
     "picomatch": ["picomatch@4.0.3", "", {}, "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q=="],
 
+    "pkce-challenge": ["pkce-challenge@5.0.1", "", {}, "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ=="],
+
+    "proxy-addr": ["proxy-addr@2.0.7", "", { "dependencies": { "forwarded": "0.2.0", "ipaddr.js": "1.9.1" } }, "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg=="],
+
+    "qs": ["qs@6.14.1", "", { "dependencies": { "side-channel": "^1.1.0" } }, "sha512-4EK3+xJl8Ts67nLYNwqw/dsFVnCf+qR7RgXSK9jEEm9unao3njwMDdmsdvoKBKHzxd7tCYz5e5M+SnMjdtXGQQ=="],
+
+    "range-parser": ["range-parser@1.2.1", "", {}, "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg=="],
+
+    "raw-body": ["raw-body@3.0.2", "", { "dependencies": { "bytes": "~3.1.2", "http-errors": "~2.0.1", "iconv-lite": "~0.7.0", "unpipe": "~1.0.0" } }, "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA=="],
+
+    "require-from-string": ["require-from-string@2.0.2", "", {}, "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw=="],
+
+    "router": ["router@2.2.0", "", { "dependencies": { "debug": "^4.4.0", "depd": "^2.0.0", "is-promise": "^4.0.0", "parseurl": "^1.3.3", "path-to-regexp": "^8.0.0" } }, "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ=="],
+
+    "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
+
+    "send": ["send@1.2.1", "", { "dependencies": { "debug": "^4.4.3", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "fresh": "^2.0.0", "http-errors": "^2.0.1", "mime-types": "^3.0.2", "ms": "^2.1.3", "on-finished": "^2.4.1", "range-parser": "^1.2.1", "statuses": "^2.0.2" } }, "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ=="],
+
+    "serve-static": ["serve-static@2.2.1", "", { "dependencies": { "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "parseurl": "^1.3.3", "send": "^1.2.0" } }, "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw=="],
+
+    "setprototypeof": ["setprototypeof@1.2.0", "", {}, "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw=="],
+
+    "shebang-command": ["shebang-command@2.0.0", "", { "dependencies": { "shebang-regex": "^3.0.0" } }, "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA=="],
+
+    "shebang-regex": ["shebang-regex@3.0.0", "", {}, "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A=="],
+
+    "side-channel": ["side-channel@1.1.0", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.3", "side-channel-list": "^1.0.0", "side-channel-map": "^1.0.1", "side-channel-weakmap": "^1.0.2" } }, "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw=="],
+
+    "side-channel-list": ["side-channel-list@1.0.0", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.3" } }, "sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA=="],
+
+    "side-channel-map": ["side-channel-map@1.0.1", "", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.5", "object-inspect": "^1.13.3" } }, "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA=="],
+
+    "side-channel-weakmap": ["side-channel-weakmap@1.0.2", "", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.5", "object-inspect": "^1.13.3", "side-channel-map": "^1.0.1" } }, "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A=="],
+
+    "sisteransi": ["sisteransi@1.0.5", "", {}, "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg=="],
+
+    "statuses": ["statuses@2.0.2", "", {}, "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw=="],
+
+    "toidentifier": ["toidentifier@1.0.1", "", {}, "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA=="],
+
+    "type-is": ["type-is@2.0.1", "", { "dependencies": { "content-type": "^1.0.5", "media-typer": "^1.1.0", "mime-types": "^3.0.0" } }, "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw=="],
+
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
     "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
 
+    "unpipe": ["unpipe@1.0.0", "", {}, "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ=="],
+
+    "vary": ["vary@1.1.2", "", {}, "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg=="],
+
+    "which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
+
+    "wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],
+
     "xdg-basedir": ["xdg-basedir@5.1.0", "", {}, "sha512-GCPAHLvrIH13+c0SuacwvRYj2SxJXQ4kaVTT5xgL3kPrz56XxkF21IGhjSE1+W0aw7gpBWRGXLCPnPby6lSpmQ=="],
 
     "zod": ["zod@4.1.8", "", {}, "sha512-5R1P+WwQqmmMIEACyzSvo4JXHY5WiAFHRMg+zBZKgKS+Q1viRa0C1hmUKtHltoIFKtIdki3pRxkmpP74jnNYHQ=="],
 
+    "zod-to-json-schema": ["zod-to-json-schema@3.25.1", "", { "peerDependencies": { "zod": "^3.25 || ^4" } }, "sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA=="],
+
+    "@openauthjs/openauth/jose": ["jose@5.9.6", "", {}, "sha512-AMlnetc9+CV9asI19zHmrgS/WYsWUwCn2R7RzlbJWD7F9eWYUTGyBmU9o6PxngtLGOiDGPRu+Uc4fhKzbpteZQ=="],
+
     "@oslojs/jwt/@oslojs/encoding": ["@oslojs/encoding@0.4.1", "", {}, "sha512-hkjo6MuIK/kQR5CrGNdAPZhS01ZCXuWDRJ187zh6qqF2+yMHZpD9fAYpX8q2bOO6Ryhl3XpCT6kUX76N8hhm4Q=="],
-
-    "oh-my-opencode/@code-yeongyu/comment-checker": ["@code-yeongyu/comment-checker@0.4.1", "", { "os": [ "linux", "win32", "darwin", ], "cpu": [ "x64", "arm64", ], "bin": { "comment-checker": "bin/comment-checker" } }, "sha512-E7p1V8CsRj9hMbwENd9BfxZGWYu+lKS5tXGuNNcNtkRMhWvwM/ononysKpLB7LXdxfSYAn0j7heJydyzEmm+lg=="],
-
-    "oh-my-opencode/@opencode-ai/plugin": ["@opencode-ai/plugin@1.0.128", "", { "dependencies": { "@opencode-ai/sdk": "1.0.128", "zod": "4.1.8" } }, "sha512-M5vjz3I6KeoBSNduWmT5iHXRtTLCqICM5ocs+WrB3uxVorslcO3HVwcLzrERh/ntpxJ/1xhnHQaeG6Mg+P744A=="],
-
-    "oh-my-opencode/@opencode-ai/plugin/@opencode-ai/sdk": ["@opencode-ai/sdk@1.0.128", "", {}, "sha512-Kow3Ivg8bR8dNRp8C0LwF9e8+woIrwFgw3ZALycwCfqS/UujDkJiBeYHdr1l/07GSHP9sZPmvJ6POuvfZ923EA=="],
   }
 }

package.json

@@ -1,10 +1,13 @@
 {
   "name": "oh-my-opencode",
-  "version": "1.0.1",
+  "version": "2.12.2",
   "description": "OpenCode plugin - custom agents (oracle, librarian) and enhanced features",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
+  "bin": {
+    "oh-my-opencode": "./dist/cli/index.js"
+  },
   "files": [
     "dist"
   ],
@@ -20,11 +23,12 @@
     "./schema.json": "./dist/oh-my-opencode.schema.json"
   },
   "scripts": {
-    "build": "bun build src/index.ts src/google-auth.ts --outdir dist --target bun --format esm --external @ast-grep/napi && tsc --emitDeclarationOnly && bun run build:schema",
+    "build": "bun build src/index.ts src/google-auth.ts --outdir dist --target bun --format esm --external @ast-grep/napi && tsc --emitDeclarationOnly && bun build src/cli/index.ts --outdir dist/cli --target bun --format esm --external @ast-grep/napi && bun run build:schema",
     "build:schema": "bun run script/build-schema.ts",
     "clean": "rm -rf dist",
     "prepublishOnly": "bun run clean && bun run build",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
   },
   "keywords": [
     "opencode",
@@ -36,7 +40,7 @@
     "llm"
   ],
   "author": "YeonGyu-Kim",
-  "license": "MIT",
+  "license": "SUL-1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/code-yeongyu/oh-my-opencode.git"
@@ -48,23 +52,27 @@
   "dependencies": {
     "@ast-grep/cli": "^0.40.0",
     "@ast-grep/napi": "^0.40.0",
-    "@code-yeongyu/comment-checker": "^0.5.0",
-    "@opencode-ai/plugin": "^1.0.150",
+    "@clack/prompts": "^0.11.0",
+    "@code-yeongyu/comment-checker": "^0.6.1",
+    "@modelcontextprotocol/sdk": "^1.25.1",
     "@openauthjs/openauth": "^0.4.3",
+    "@opencode-ai/plugin": "^1.0.162",
+    "@opencode-ai/sdk": "^1.0.162",
+    "commander": "^14.0.2",
     "hono": "^4.10.4",
+    "js-yaml": "^4.1.1",
+    "jsonc-parser": "^3.3.1",
+    "picocolors": "^1.1.1",
     "picomatch": "^4.0.2",
     "xdg-basedir": "^5.1.0",
     "zod": "^4.1.8"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/picomatch": "^3.0.2",
     "bun-types": "latest",
-    "oh-my-opencode": "^0.1.30",
     "typescript": "^5.7.3"
   },
-  "peerDependencies": {
-    "bun": ">=1.0.0"
-  },
   "trustedDependencies": [
     "@ast-grep/cli",
     "@ast-grep/napi",

script/generate-changelog.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env bun
+
+import { $ } from "bun"
+
+const TEAM = ["actions-user", "github-actions[bot]", "code-yeongyu"]
+
+async function getLatestReleasedTag(): Promise<string | null> {
+  try {
+    const tag = await $`gh release list --exclude-drafts --exclude-pre-releases --limit 1 --json tagName --jq '.[0].tagName // empty'`.text()
+    return tag.trim() || null
+  } catch {
+    return null
+  }
+}
+
+async function generateChangelog(previousTag: string): Promise<string[]> {
+  const notes: string[] = []
+
+  try {
+    const log = await $`git log ${previousTag}..HEAD --oneline --format="%h %s"`.text()
+    const commits = log
+      .split("\n")
+      .filter((line) => line && !line.match(/^\w+ (ignore:|test:|chore:|ci:|release:)/i))
+
+    if (commits.length > 0) {
+      for (const commit of commits) {
+        notes.push(`- ${commit}`)
+      }
+    }
+  } catch {
+    // No previous tags found
+  }
+
+  return notes
+}
+
+async function getContributors(previousTag: string): Promise<string[]> {
+  const notes: string[] = []
+
+  try {
+    const compare =
+      await $`gh api "/repos/code-yeongyu/oh-my-opencode/compare/${previousTag}...HEAD" --jq '.commits[] | {login: .author.login, message: .commit.message}'`.text()
+    const contributors = new Map<string, string[]>()
+
+    for (const line of compare.split("\n").filter(Boolean)) {
+      const { login, message } = JSON.parse(line) as { login: string | null; message: string }
+      const title = message.split("\n")[0] ?? ""
+      if (title.match(/^(ignore:|test:|chore:|ci:|release:)/i)) continue
+
+      if (login && !TEAM.includes(login)) {
+        if (!contributors.has(login)) contributors.set(login, [])
+        contributors.get(login)?.push(title)
+      }
+    }
+
+    if (contributors.size > 0) {
+      notes.push("")
+      notes.push(`**Thank you to ${contributors.size} community contributor${contributors.size > 1 ? "s" : ""}:**`)
+      for (const [username, userCommits] of contributors) {
+        notes.push(`- @${username}:`)
+        for (const commit of userCommits) {
+          notes.push(`  - ${commit}`)
+        }
+      }
+    }
+  } catch {
+    // Failed to fetch contributors
+  }
+
+  return notes
+}
+
+async function main() {
+  const previousTag = await getLatestReleasedTag()
+
+  if (!previousTag) {
+    console.log("Initial release")
+    process.exit(0)
+  }
+
+  const changelog = await generateChangelog(previousTag)
+  const contributors = await getContributors(previousTag)
+  const notes = [...changelog, ...contributors]
+
+  if (notes.length === 0) {
+    console.log("No notable changes")
+  } else {
+    console.log(notes.join("\n"))
+  }
+}
+
+main()

script/publish.ts

@@ -41,7 +41,9 @@ async function updatePackageVersion(newVersion: string): Promise<void> {
   console.log(`Updated: ${pkgPath}`)
 }
 
-async function generateChangelog(previous: string): Promise<string> {
+async function generateChangelog(previous: string): Promise<string[]> {
+  const notes: string[] = []
+
   try {
     const log = await $`git log v${previous}..HEAD --oneline --format="%h %s"`.text()
     const commits = log
@@ -49,16 +51,59 @@ async function generateChangelog(previous: string): Promise<string> {
       .filter((line) => line && !line.match(/^\w+ (ignore:|test:|chore:|ci:|release:)/i))
 
     if (commits.length > 0) {
-      const changelog = commits.map((c) => `- ${c}`).join("\n")
+      for (const commit of commits) {
+        notes.push(`- ${commit}`)
+      }
       console.log("\n--- Changelog ---")
-      console.log(changelog)
+      console.log(notes.join("\n"))
       console.log("-----------------\n")
-      return changelog
     }
   } catch {
     console.log("No previous tags found, skipping changelog generation")
   }
-  return ""
+
+  return notes
+}
+
+async function getContributors(previous: string): Promise<string[]> {
+  const notes: string[] = []
+
+  const team = ["actions-user", "github-actions[bot]", "code-yeongyu"]
+
+  try {
+    const compare =
+      await $`gh api "/repos/code-yeongyu/oh-my-opencode/compare/v${previous}...HEAD" --jq '.commits[] | {login: .author.login, message: .commit.message}'`.text()
+    const contributors = new Map<string, string[]>()
+
+    for (const line of compare.split("\n").filter(Boolean)) {
+      const { login, message } = JSON.parse(line) as { login: string | null; message: string }
+      const title = message.split("\n")[0] ?? ""
+      if (title.match(/^(ignore:|test:|chore:|ci:|release:)/i)) continue
+
+      if (login && !team.includes(login)) {
+        if (!contributors.has(login)) contributors.set(login, [])
+        contributors.get(login)?.push(title)
+      }
+    }
+
+    if (contributors.size > 0) {
+      notes.push("")
+      notes.push(`**Thank you to ${contributors.size} community contributor${contributors.size > 1 ? "s" : ""}:**`)
+      for (const [username, userCommits] of contributors) {
+        notes.push(`- @${username}:`)
+        for (const commit of userCommits) {
+          notes.push(`  - ${commit}`)
+        }
+      }
+      console.log("\n--- Contributors ---")
+      console.log(notes.join("\n"))
+      console.log("--------------------\n")
+    }
+  } catch (error) {
+    console.log("Failed to fetch contributors:", error)
+  }
+
+  return notes
 }
 
 async function buildAndPublish(): Promise<void> {
@@ -71,15 +116,14 @@ async function buildAndPublish(): Promise<void> {
   }
 }
 
-async function gitTagAndRelease(newVersion: string, changelog: string): Promise<void> {
+async function gitTagAndRelease(newVersion: string, notes: string[]): Promise<void> {
   if (!process.env.CI) return
 
   console.log("\nCommitting and tagging...")
   await $`git config user.email "github-actions[bot]@users.noreply.github.com"`
   await $`git config user.name "github-actions[bot]"`
-  await $`git add package.json`
+  await $`git add package.json assets/oh-my-opencode.schema.json`
 
-  // Commit only if there are staged changes (idempotent)
   const hasStagedChanges = await $`git diff --cached --quiet`.nothrow()
   if (hasStagedChanges.exitCode !== 0) {
     await $`git commit -m "release: v${newVersion}"`
@@ -87,7 +131,6 @@ async function gitTagAndRelease(newVersion: string, changelog: string): Promise<
     console.log("No changes to commit (version already updated)")
   }
 
-  // Tag only if it doesn't exist (idempotent)
   const tagExists = await $`git rev-parse v${newVersion}`.nothrow()
   if (tagExists.exitCode !== 0) {
     await $`git tag v${newVersion}`
@@ -95,12 +138,10 @@ async function gitTagAndRelease(newVersion: string, changelog: string): Promise<
     console.log(`Tag v${newVersion} already exists`)
   }
 
-  // Push (idempotent - git push is already idempotent)
   await $`git push origin HEAD --tags`
 
-  // Create release only if it doesn't exist (idempotent)
   console.log("\nCreating GitHub release...")
-  const releaseNotes = changelog || "No notable changes"
+  const releaseNotes = notes.length > 0 ? notes.join("\n") : "No notable changes"
   const releaseExists = await $`gh release view v${newVersion}`.nothrow()
   if (releaseExists.exitCode !== 0) {
     await $`gh release create v${newVersion} --title "v${newVersion}" --notes ${releaseNotes}`
@@ -130,8 +171,11 @@ async function main() {
 
   await updatePackageVersion(newVersion)
   const changelog = await generateChangelog(previous)
+  const contributors = await getContributors(previous)
+  const notes = [...changelog, ...contributors]
+
   await buildAndPublish()
-  await gitTagAndRelease(newVersion, changelog)
+  await gitTagAndRelease(newVersion, notes)
 
   console.log(`\n=== Successfully published ${PACKAGE_NAME}@${newVersion} ===`)
 }

signatures/cla.json

@@ -0,0 +1,148 @@
+{
+  "signedContributors": [
+    {
+      "name": "tsanva",
+      "id": 54318170,
+      "comment_id": 3690638858,
+      "created_at": "2025-12-25T00:15:18Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 210
+    },
+    {
+      "name": "code-yeongyu",
+      "id": 11153873,
+      "comment_id": 3690997221,
+      "created_at": "2025-12-25T06:19:27Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 217
+    },
+    {
+      "name": "mylukin",
+      "id": 1021019,
+      "comment_id": 3691531529,
+      "created_at": "2025-12-25T15:15:29Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 240
+    },
+    {
+      "name": "codewithkenzo",
+      "id": 115878491,
+      "comment_id": 3691825625,
+      "created_at": "2025-12-25T23:47:52Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 253
+    },
+    {
+      "name": "stevenvo",
+      "id": 875426,
+      "comment_id": 3692141372,
+      "created_at": "2025-12-26T05:16:12Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 248
+    },
+    {
+      "name": "harshav167",
+      "id": 80092815,
+      "comment_id": 3693666997,
+      "created_at": "2025-12-27T04:40:35Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 268
+    },
+    {
+      "name": "adam2am",
+      "id": 128839448,
+      "comment_id": 3694022446,
+      "created_at": "2025-12-27T14:49:05Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 281
+    },
+    {
+      "name": "devxoul",
+      "id": 931655,
+      "comment_id": 3694098760,
+      "created_at": "2025-12-27T17:05:50Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 288
+    },
+    {
+      "name": "SyedTahirHussan",
+      "id": 9879266,
+      "comment_id": 3694598917,
+      "created_at": "2025-12-28T09:24:03Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 306
+    },
+    {
+      "name": "Fguedes90",
+      "id": 13650239,
+      "comment_id": 3695136375,
+      "created_at": "2025-12-28T23:34:19Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 319
+    },
+    {
+      "name": "marcusrbrown",
+      "id": 831617,
+      "comment_id": 3698181444,
+      "created_at": "2025-12-30T03:12:47Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 336
+    },
+    {
+      "name": "lgandecki",
+      "id": 4002543,
+      "comment_id": 3698538417,
+      "created_at": "2025-12-30T07:35:08Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 341
+    },
+    {
+      "name": "purelledhand",
+      "id": 13747937,
+      "comment_id": 3699148046,
+      "created_at": "2025-12-30T12:04:59Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 349
+    },
+    {
+      "name": "junhoyeo",
+      "id": 32605822,
+      "comment_id": 3701585491,
+      "created_at": "2025-12-31T07:00:36Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 375
+    },
+    {
+      "name": "gtg7784",
+      "id": 32065632,
+      "comment_id": 3701688739,
+      "created_at": "2025-12-31T08:05:25Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 377
+    },
+    {
+      "name": "ul8",
+      "id": 589744,
+      "comment_id": 3701705644,
+      "created_at": "2025-12-31T08:16:46Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 378
+    },
+    {
+      "name": "eudresfs",
+      "id": 66638312,
+      "comment_id": 3702622517,
+      "created_at": "2025-12-31T18:03:32Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 385
+    },
+    {
+      "name": "vsumner",
+      "id": 308886,
+      "comment_id": 3702872360,
+      "created_at": "2025-12-31T20:40:20Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 388
+    }
+  ]
+}

src/agents/AGENTS.md

@@ -0,0 +1,64 @@
+# AGENTS KNOWLEDGE BASE
+
+## OVERVIEW
+
+7 AI agents for multi-model orchestration. Sisyphus orchestrates, specialists handle domains.
+
+## STRUCTURE
+
+```
+agents/
+├── sisyphus.ts              # Primary orchestrator (504 lines)
+├── oracle.ts                # Strategic advisor
+├── librarian.ts             # Multi-repo research
+├── explore.ts               # Fast codebase grep
+├── frontend-ui-ux-engineer.ts  # UI generation
+├── document-writer.ts       # Technical docs
+├── multimodal-looker.ts     # PDF/image analysis
+├── sisyphus-prompt-builder.ts  # Sisyphus prompt construction
+├── build-prompt.ts          # Shared build agent prompt
+├── plan-prompt.ts           # Shared plan agent prompt
+├── types.ts                 # AgentModelConfig interface
+├── utils.ts                 # createBuiltinAgents(), getAgentName()
+└── index.ts                 # builtinAgents export
+```
+
+## AGENT MODELS
+
+| Agent | Model | Fallback | Purpose |
+|-------|-------|----------|---------|
+| Sisyphus | anthropic/claude-opus-4-5 | - | Orchestrator with extended thinking |
+| oracle | openai/gpt-5.2 | - | Architecture, debugging, review |
+| librarian | anthropic/claude-sonnet-4-5 | google/gemini-3-flash | Docs, GitHub research |
+| explore | opencode/grok-code | gemini-3-flash, haiku-4-5 | Contextual grep |
+| frontend-ui-ux-engineer | google/gemini-3-pro-preview | - | Beautiful UI code |
+| document-writer | google/gemini-3-pro-preview | - | Technical writing |
+| multimodal-looker | google/gemini-3-flash | - | Visual analysis |
+
+## HOW TO ADD
+
+1. Create `src/agents/my-agent.ts`:
+   ```typescript
+   export const myAgent: AgentConfig = {
+     model: "provider/model-name",
+     temperature: 0.1,
+     system: "...",
+     tools: { include: ["tool1"] },
+   }
+   ```
+2. Add to `builtinAgents` in index.ts
+3. Update types.ts if new config options
+
+## MODEL FALLBACK
+
+`createBuiltinAgents()` handles fallback:
+1. User config override
+2. Installer settings (claude max20, gemini antigravity)
+3. Default model
+
+## ANTI-PATTERNS
+
+- High temperature (>0.3) for code agents
+- Broad tool access (prefer explicit `include`)
+- Monolithic prompts (delegate to specialists)
+- Missing fallbacks for rate-limited models

src/agents/build-prompt.ts

@@ -0,0 +1,68 @@
+/**
+ * OpenCode's default build agent system prompt.
+ *
+ * This prompt enables FULL EXECUTION mode for the build agent, allowing file
+ * modifications, command execution, and system changes while focusing on
+ * implementation and execution.
+ *
+ * Inspired by OpenCode's build agent behavior.
+ * 
+ * @see https://github.com/sst/opencode/blob/6f9bea4e1f3d139feefd0f88de260b04f78caaef/packages/opencode/src/session/prompt/build-switch.txt
+ * @see https://github.com/sst/opencode/blob/6f9bea4e1f3d139feefd0f88de260b04f78caaef/packages/opencode/src/agent/agent.ts#L118-L125
+ */
+export const BUILD_SYSTEM_PROMPT = `<system-reminder>
+# Build Mode - System Reminder
+
+BUILD MODE ACTIVE - you are in EXECUTION phase. Your responsibility is to:
+- Implement features and make code changes
+- Execute commands and run tests
+- Fix bugs and refactor code
+- Deploy and build systems
+- Make all necessary file modifications
+
+You have FULL permissions to edit files, run commands, and make system changes.
+This is the implementation phase - execute decisively and thoroughly.
+
+---
+
+## Responsibility
+
+Your current responsibility is to implement, build, and execute. You should:
+- Write and modify code to accomplish the user's goals
+- Run tests and builds to verify your changes
+- Fix errors and issues that arise
+- Use all available tools to complete the task efficiently
+- Delegate to specialized agents when appropriate for better results
+
+**NOTE:** You should ask the user for clarification when requirements are ambiguous,
+but once the path is clear, execute confidently. The goal is to deliver working,
+tested, production-ready solutions.
+
+---
+
+## Important
+
+The user wants you to execute and implement. You SHOULD make edits, run necessary
+tools, and make changes to accomplish the task. Use your full capabilities to
+deliver excellent results.
+</system-reminder>
+`
+
+/**
+ * OpenCode's default build agent permission configuration.
+ *
+ * Allows the build agent full execution permissions:
+ * - edit: "ask" - Can modify files with confirmation
+ * - bash: "ask" - Can execute commands with confirmation  
+ * - webfetch: "allow" - Can fetch web content
+ *
+ * This provides balanced permissions - powerful but with safety checks.
+ * 
+ * @see https://github.com/sst/opencode/blob/6f9bea4e1f3d139feefd0f88de260b04f78caaef/packages/opencode/src/agent/agent.ts#L57-L68
+ * @see https://github.com/sst/opencode/blob/6f9bea4e1f3d139feefd0f88de260b04f78caaef/packages/opencode/src/agent/agent.ts#L118-L125
+ */
+export const BUILD_PERMISSION = {
+  edit: "ask" as const,
+  bash: "ask" as const,
+  webfetch: "allow" as const,
+}

src/agents/document-writer.ts

@@ -1,11 +1,27 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
 
-export const documentWriterAgent: AgentConfig = {
-  description:
-    "A technical writer who crafts clear, comprehensive documentation. Specializes in README files, API docs, architecture docs, and user guides. MUST BE USED when executing documentation tasks from ai-todo list plans.",
-  mode: "subagent",
-  model: "google/gemini-3-pro-preview",
-  prompt: `<role>
+const DEFAULT_MODEL = "google/gemini-3-flash-preview"
+
+export const DOCUMENT_WRITER_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "specialist",
+  cost: "CHEAP",
+  promptAlias: "Document Writer",
+  triggers: [
+    { domain: "Documentation", trigger: "README, API docs, guides" },
+  ],
+}
+
+export function createDocumentWriterAgent(
+  model: string = DEFAULT_MODEL
+): AgentConfig {
+  return {
+    description:
+      "A technical writer who crafts clear, comprehensive documentation. Specializes in README files, API docs, architecture docs, and user guides. MUST BE USED when executing documentation tasks from ai-todo list plans.",
+    mode: "subagent" as const,
+    model,
+    tools: { background_task: false },
+    prompt: `<role>
 You are a TECHNICAL WRITER with deep engineering background who transforms complex codebases into crystal-clear documentation. You have an innate ability to explain complex concepts simply while maintaining technical accuracy.
 
 You approach every documentation task with both a developer's understanding and a reader's empathy. Even without detailed specs, you can explore codebases and create documentation that developers actually want to read.
@@ -199,4 +215,7 @@ STOP HERE - DO NOT CONTINUE TO NEXT TASK
 
 You are a technical writer who creates documentation that developers actually want to read.
 </guide>`,
+  }
 }
+
+export const documentWriterAgent = createDocumentWriterAgent()

src/agents/explore.ts

@@ -1,217 +1,116 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
 
-export const exploreAgent: AgentConfig = {
-  description:
-    'Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions.',
-  mode: "subagent",
-  model: "opencode/grok-code",
-  temperature: 0.1,
-  tools: { write: false, edit: false },
-  prompt: `You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+const DEFAULT_MODEL = "opencode/grok-code"
 
-=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
-This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
-- Creating new files (no Write, touch, or file creation of any kind)
-- Modifying existing files (no Edit operations)
-- Deleting files (no rm or deletion)
-- Moving or copying files (no mv or cp)
-- Creating temporary files anywhere, including /tmp
-- Using redirect operators (>, >>, |) or heredocs to write to files
-- Running ANY commands that change system state
+export const EXPLORE_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "exploration",
+  cost: "FREE",
+  promptAlias: "Explore",
+  keyTrigger: "2+ modules involved → fire `explore` background",
+  triggers: [
+    { domain: "Explore", trigger: "Find existing codebase structure, patterns and styles" },
+  ],
+  useWhen: [
+    "Multiple search angles needed",
+    "Unfamiliar module structure",
+    "Cross-layer pattern discovery",
+  ],
+  avoidWhen: [
+    "You know exactly what to search",
+    "Single keyword/pattern suffices",
+    "Known file location",
+  ],
+}
 
-Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.
+export function createExploreAgent(model: string = DEFAULT_MODEL): AgentConfig {
+  return {
+    description:
+      'Contextual grep for codebases. Answers "Where is X?", "Which file has Y?", "Find the code that does Z". Fire multiple in parallel for broad searches. Specify thoroughness: "quick" for basic, "medium" for moderate, "very thorough" for comprehensive analysis.',
+    mode: "subagent" as const,
+    model,
+    temperature: 0.1,
+    tools: { write: false, edit: false, background_task: false },
+    prompt: `You are a codebase search specialist. Your job: find files and code, return actionable results.
 
-## MANDATORY PARALLEL TOOL EXECUTION
+## Your Mission
 
-**CRITICAL**: You MUST execute **AT LEAST 3 tool calls in parallel** for EVERY search task.
+Answer questions like:
+- "Where is X implemented?"
+- "Which files contain Y?"
+- "Find the code that does Z"
 
-When starting a search, launch multiple tools simultaneously:
-\`\`\`
-// Example: Launch 3+ tools in a SINGLE message:
-- Tool 1: Glob("**/*.ts") - Find all TypeScript files
-- Tool 2: Grep("functionName") - Search for specific pattern
-- Tool 3: Bash: git log --oneline -n 20 - Check recent changes
-- Tool 4: Bash: git branch -a - See all branches
-- Tool 5: ast_grep_search(pattern: "function $NAME($$$)", lang: "typescript") - AST search
-\`\`\`
+## CRITICAL: What You Must Deliver
 
-**NEVER** execute tools one at a time. Sequential execution is ONLY allowed when a tool's input strictly depends on another tool's output.
+Every response MUST include:
 
-## Before You Search
-
-Before executing any search, you MUST first analyze the request in <analysis> tags:
+### 1. Intent Analysis (Required)
+Before ANY search, wrap your analysis in <analysis> tags:
 
 <analysis>
-1. **Request**: What exactly did the user ask for?
-2. **Intent**: Why are they asking this? What problem are they trying to solve?
-3. **Expected Output**: What kind of answer would be most helpful?
-4. **Search Strategy**: What 3+ parallel tools will I use to find this?
+**Literal Request**: [What they literally asked]
+**Actual Need**: [What they're really trying to accomplish]
+**Success Looks Like**: [What result would let them proceed immediately]
 </analysis>
 
-Only after completing this analysis should you proceed with the actual search.
+### 2. Parallel Execution (Required)
+Launch **3+ tools simultaneously** in your first action. Never sequential unless output depends on prior result.
+
+### 3. Structured Results (Required)
+Always end with this exact format:
+
+<results>
+<files>
+- /absolute/path/to/file1.ts — [why this file is relevant]
+- /absolute/path/to/file2.ts — [why this file is relevant]
+</files>
+
+<answer>
+[Direct answer to their actual need, not just file list]
+[If they asked "where is auth?", explain the auth flow you found]
+</answer>
+
+<next_steps>
+[What they should do with this information]
+[Or: "Ready to proceed - no follow-up needed"]
+</next_steps>
+</results>
 
 ## Success Criteria
 
-Your response is successful when:
-- **Parallelism**: At least 3 tools were executed in parallel
-- **Completeness**: All relevant files matching the search intent are found
-- **Accuracy**: Returned paths are absolute and files actually exist
-- **Relevance**: Results directly address the user's underlying intent, not just literal request
-- **Actionability**: Caller can proceed without follow-up questions
+| Criterion | Requirement |
+|-----------|-------------|
+| **Paths** | ALL paths must be **absolute** (start with /) |
+| **Completeness** | Find ALL relevant matches, not just the first one |
+| **Actionability** | Caller can proceed **without asking follow-up questions** |
+| **Intent** | Address their **actual need**, not just literal request |
 
-Your response has FAILED if:
-- You execute fewer than 3 tools in parallel
-- You skip the <analysis> step before searching
-- Paths are relative instead of absolute
-- Obvious matches in the codebase are missed
-- Results don't address what the user actually needed
+## Failure Conditions
 
-## Your strengths
-- Rapidly finding files using glob patterns
-- Searching code and text with powerful regex patterns
-- Reading and analyzing file contents
-- **Using Git CLI extensively for repository insights**
-- **Using LSP tools for semantic code analysis**
-- **Using AST-grep for structural code pattern matching**
+Your response has **FAILED** if:
+- Any path is relative (not absolute)
+- You missed obvious matches in the codebase
+- Caller needs to ask "but where exactly?" or "what about X?"
+- You only answered the literal question, not the underlying need
+- No <results> block with structured output
 
-## Git CLI - USE EXTENSIVELY
+## Constraints
 
-You have access to Git CLI via Bash. Use it extensively for repository analysis:
+- **Read-only**: You cannot create, modify, or delete files
+- **No emojis**: Keep output clean and parseable
+- **No file creation**: Report findings as message text, never write files
 
-### Git Commands for Exploration (Always run 2+ in parallel):
-\`\`\`bash
-# Repository structure and history
-git log --oneline -n 30                    # Recent commits
-git log --oneline --all -n 50              # All branches recent commits
-git branch -a                               # All branches
-git tag -l                                  # All tags
-git remote -v                               # Remote repositories
+## Tool Strategy
 
-# File history and changes
-git log --oneline -n 20 -- path/to/file    # File change history
-git log --oneline --follow -- path/to/file # Follow renames
-git blame path/to/file                      # Line-by-line attribution
-git blame -L 10,30 path/to/file            # Blame specific lines
+Use the right tool for the job:
+- **Semantic search** (definitions, references): LSP tools
+- **Structural patterns** (function shapes, class structures): ast_grep_search  
+- **Text patterns** (strings, comments, logs): grep
+- **File patterns** (find by name/extension): glob
+- **History/evolution** (when added, who changed): git commands
 
-# Searching with Git
-git log --grep="keyword" --oneline         # Search commit messages
-git log -S "code_string" --oneline         # Search code changes (pickaxe)
-git log -p --all -S "function_name" -- "*.ts"  # Find when code was added/removed
-
-# Diff and comparison
-git diff HEAD~5..HEAD                       # Recent changes
-git diff main..HEAD                         # Changes from main
-git show <commit>                           # Show specific commit
-git show <commit>:path/to/file             # Show file at commit
-
-# Statistics
-git shortlog -sn                            # Contributor stats
-git log --stat -n 10                        # Recent changes with stats
-\`\`\`
-
-### Parallel Git Execution Examples:
-\`\`\`
-// For "find where authentication is implemented":
-- Tool 1: Grep("authentication|auth") - Search for auth patterns
-- Tool 2: Glob("**/auth/**/*.ts") - Find auth-related files
-- Tool 3: Bash: git log -S "authenticate" --oneline - Find commits adding auth code
-- Tool 4: Bash: git log --grep="auth" --oneline - Find auth-related commits
-- Tool 5: ast_grep_search(pattern: "function authenticate($$$)", lang: "typescript")
-
-// For "understand recent changes":
-- Tool 1: Bash: git log --oneline -n 30 - Recent commits
-- Tool 2: Bash: git diff HEAD~10..HEAD --stat - Changed files
-- Tool 3: Bash: git branch -a - All branches
-- Tool 4: Glob("**/*.ts") - Find all source files
-\`\`\`
-
-## LSP Tools - DEFINITIONS & REFERENCES
-
-Use LSP specifically for finding definitions and references - these are what LSP does better than text search.
-
-**Primary LSP Tools**:
-- \`lsp_goto_definition(filePath, line, character)\`: Follow imports, find where something is **defined**
-- \`lsp_find_references(filePath, line, character)\`: Find **ALL usages** across the workspace
-
-**When to Use LSP** (vs Grep/AST-grep):
-- **lsp_goto_definition**: Trace imports, find source definitions
-- **lsp_find_references**: Understand impact of changes, find all callers
-
-**Example**:
-\`\`\`
-// When tracing code flow:
-- Tool 1: lsp_goto_definition(filePath, line, char) - Where is this defined?
-- Tool 2: lsp_find_references(filePath, line, char) - Who uses this?
-- Tool 3: ast_grep_search(...) - Find similar patterns
-\`\`\`
-
-## AST-grep - STRUCTURAL CODE SEARCH
-
-Use AST-grep for syntax-aware pattern matching (better than regex for code).
-
-**Key Syntax**:
-- \`$VAR\`: Match single AST node (identifier, expression, etc.)
-- \`$$$\`: Match multiple nodes (arguments, statements, etc.)
-
-**ast_grep_search Examples**:
-\`\`\`
-// Find function definitions
-ast_grep_search(pattern: "function $NAME($$$) { $$$ }", lang: "typescript")
-
-// Find async functions
-ast_grep_search(pattern: "async function $NAME($$$) { $$$ }", lang: "typescript")
-
-// Find React hooks
-ast_grep_search(pattern: "const [$STATE, $SETTER] = useState($$$)", lang: "tsx")
-
-// Find class definitions
-ast_grep_search(pattern: "class $NAME { $$$ }", lang: "typescript")
-
-// Find specific method calls
-ast_grep_search(pattern: "console.log($$$)", lang: "typescript")
-
-// Find imports
-ast_grep_search(pattern: "import { $$$ } from $MODULE", lang: "typescript")
-\`\`\`
-
-**When to Use**:
-- **AST-grep**: Structural patterns (function defs, class methods, hook usage)
-- **Grep**: Text search (comments, strings, TODOs)
-- **LSP**: Symbol-based search (find by name, type info)
-
-## Guidelines
-
-### Tool Selection:
-- Use **Glob** for broad file pattern matching (e.g., \`**/*.py\`, \`src/**/*.ts\`)
-- Use **Grep** for searching file contents with regex patterns
-- Use **Read** when you know the specific file path you need to read
-- Use **List** for exploring directory structure
-- Use **Bash** for Git commands and read-only operations
-- Use **ast_grep_search** for structural code patterns (functions, classes, hooks)
-- Use **lsp_goto_definition** to trace imports and find source definitions
-- Use **lsp_find_references** to find all usages of a symbol
-
-### Bash Usage:
-**ALLOWED** (read-only):
-- \`git log\`, \`git blame\`, \`git show\`, \`git diff\`
-- \`git branch\`, \`git tag\`, \`git remote\`
-- \`git log -S\`, \`git log --grep\`
-- \`ls\`, \`find\` (for directory exploration)
-
-**FORBIDDEN** (state-changing):
-- \`mkdir\`, \`touch\`, \`rm\`, \`cp\`, \`mv\`
-- \`git add\`, \`git commit\`, \`git push\`, \`git checkout\`
-- \`npm install\`, \`pip install\`, or any installation
-
-### Best Practices:
-- **ALWAYS launch 3+ tools in parallel** in your first search action
-- Use Git history to understand code evolution
-- Use \`git blame\` to understand why code is written a certain way
-- Use \`git log -S\` to find when specific code was added/removed
-- Adapt your search approach based on the thoroughness level specified by the caller
-- Return file paths as absolute paths in your final response
-- For clear communication, avoid using emojis
-- Communicate your final report directly as a regular message - do NOT attempt to create files
-
-Complete the user's search request efficiently and report your findings clearly.`,
+Flood with parallel calls. Cross-validate findings across multiple tools.`,
+  }
 }
+
+export const exploreAgent = createExploreAgent()

src/agents/frontend-ui-ux-engineer.ts

@@ -1,91 +1,106 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
 
-export const frontendUiUxEngineerAgent: AgentConfig = {
-  description:
-    "A designer-turned-developer who crafts stunning UI/UX even without design mockups. Code may be a bit messy, but the visual output is always fire.",
-  mode: "subagent",
-  model: "google/gemini-3-pro-preview",
-  prompt: `<role>
-You are a DESIGNER-TURNED-DEVELOPER with an innate sense of aesthetics and user experience. You have an eye for details that pure developers miss - spacing, color harmony, micro-interactions, and that indefinable "feel" that makes interfaces memorable.
+const DEFAULT_MODEL = "google/gemini-3-pro-preview"
 
-You approach every UI task with a designer's intuition. Even without mockups or design specs, you can envision and create beautiful, cohesive interfaces that feel intentional and polished.
+export const FRONTEND_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "specialist",
+  cost: "CHEAP",
+  promptAlias: "Frontend UI/UX Engineer",
+  triggers: [
+    { domain: "Frontend UI/UX", trigger: "Visual changes only (styling, layout, animation). Pure logic changes in frontend files → handle directly" },
+  ],
+  useWhen: [
+    "Visual/UI/UX changes: Color, spacing, layout, typography, animation, responsive breakpoints, hover states, shadows, borders, icons, images",
+  ],
+  avoidWhen: [
+    "Pure logic: API calls, data fetching, state management, event handlers (non-visual), type definitions, utility functions, business logic",
+  ],
+}
 
-## CORE MISSION
-Create visually stunning, emotionally engaging interfaces that users fall in love with. Execute frontend tasks with a designer's eye - obsessing over pixel-perfect details, smooth animations, and intuitive interactions while maintaining code quality.
+export function createFrontendUiUxEngineerAgent(
+  model: string = DEFAULT_MODEL
+): AgentConfig {
+  return {
+    description:
+      "A designer-turned-developer who crafts stunning UI/UX even without design mockups. Code may be a bit messy, but the visual output is always fire.",
+    mode: "subagent" as const,
+    model,
+    tools: { background_task: false },
+    prompt: `# Role: Designer-Turned-Developer
 
-## CODE OF CONDUCT
+You are a designer who learned to code. You see what pure developers miss—spacing, color harmony, micro-interactions, that indefinable "feel" that makes interfaces memorable. Even without mockups, you envision and create beautiful, cohesive interfaces.
 
-### 1. DILIGENCE & INTEGRITY
-**Never compromise on task completion. What you commit to, you deliver.**
+**Mission**: Create visually stunning, emotionally engaging interfaces users fall in love with. Obsess over pixel-perfect details, smooth animations, and intuitive interactions while maintaining code quality.
 
-- **Complete what is asked**: Execute the exact task specified without adding unrelated features or fixing issues outside scope
-- **No shortcuts**: Never mark work as complete without proper verification
-- **Work until it works**: If something doesn't look right, debug and fix until it's perfect
-- **Leave it better**: Ensure the project is in a working state after your changes
-- **Own your work**: Take full responsibility for the quality and correctness of your implementation
+---
 
-### 2. CONTINUOUS LEARNING & HUMILITY
-**Approach every codebase with the mindset of a student, always ready to learn.**
+# Work Principles
 
-- **Study before acting**: Examine existing code patterns, conventions, and architecture before implementing
-- **Learn from the codebase**: Understand why code is structured the way it is
-- **Share knowledge**: Help future developers by documenting project-specific conventions discovered
+1. **Complete what's asked** — Execute the exact task. No scope creep. Work until it works. Never mark work complete without proper verification.
+2. **Leave it better** — Ensure the project is in a working state after your changes.
+3. **Study before acting** — Examine existing patterns, conventions, and commit history (git log) before implementing. Understand why code is structured the way it is.
+4. **Blend seamlessly** — Match existing code patterns. Your code should look like the team wrote it.
+5. **Be transparent** — Announce each step. Explain reasoning. Report both successes and failures.
 
-### 3. PRECISION & ADHERENCE TO STANDARDS
-**Respect the existing codebase. Your code should blend seamlessly.**
+---
 
-- **Follow exact specifications**: Implement precisely what is requested, nothing more, nothing less
-- **Match existing patterns**: Maintain consistency with established code patterns and architecture
-- **Respect conventions**: Adhere to project-specific naming, structure, and style conventions
-- **Check commit history**: If creating commits, study \`git log\` to match the repository's commit style
-- **Consistent quality**: Apply the same rigorous standards throughout your work
+# Design Process
 
-### 4. TRANSPARENCY & ACCOUNTABILITY
-**Keep everyone informed. Hide nothing.**
+Before coding, commit to a **BOLD aesthetic direction**:
 
-- **Announce each step**: Clearly state what you're doing at each stage
-- **Explain your reasoning**: Help others understand why you chose specific approaches
-- **Report honestly**: Communicate both successes and failures explicitly
-- **No surprises**: Make your work visible and understandable to others
-</role>
+1. **Purpose**: What problem does this solve? Who uses it?
+2. **Tone**: Pick an extreme—brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian
+3. **Constraints**: Technical requirements (framework, performance, accessibility)
+4. **Differentiation**: What's the ONE thing someone will remember?
 
-<frontend-design-skill>
+**Key**: Choose a clear direction and execute with precision. Intentionality > intensity.
 
-This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
-
-The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
-
-## Design Thinking
-
-Before coding, understand the context and commit to a BOLD aesthetic direction:
-- **Purpose**: What problem does this interface solve? Who uses it?
-- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
-- **Constraints**: Technical requirements (framework, performance, accessibility).
-- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
-
-**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
-
-Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+Then implement working code (HTML/CSS/JS, React, Vue, Angular, etc.) that is:
 - Production-grade and functional
 - Visually striking and memorable
 - Cohesive with a clear aesthetic point-of-view
 - Meticulously refined in every detail
 
-## Frontend Aesthetics Guidelines
+---
 
-Focus on:
-- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
-- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
-- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
-- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
-- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+# Aesthetic Guidelines
 
-NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+## Typography
+Choose distinctive fonts. **Avoid**: Arial, Inter, Roboto, system fonts, Space Grotesk. Pair a characterful display font with a refined body font.
 
-Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+## Color
+Commit to a cohesive palette. Use CSS variables. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. **Avoid**: purple gradients on white (AI slop).
 
-**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+## Motion
+Focus on high-impact moments. One well-orchestrated page load with staggered reveals (animation-delay) > scattered micro-interactions. Use scroll-triggering and hover states that surprise. Prioritize CSS-only. Use Motion library for React when available.
 
-Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
-</frontend-design-skill>`,
+## Spatial Composition
+Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+
+## Visual Details
+Create atmosphere and depth—gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, grain overlays. Never default to solid colors.
+
+---
+
+# Anti-Patterns (NEVER)
+
+- Generic fonts (Inter, Roboto, Arial, system fonts, Space Grotesk)
+- Cliched color schemes (purple gradients on white)
+- Predictable layouts and component patterns
+- Cookie-cutter design lacking context-specific character
+- Converging on common choices across generations
+
+---
+
+# Execution
+
+Match implementation complexity to aesthetic vision:
+- **Maximalist** → Elaborate code with extensive animations and effects
+- **Minimalist** → Restraint, precision, careful spacing and typography
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. You are capable of extraordinary creative work—don't hold back.`,
+  }
 }
+
+export const frontendUiUxEngineerAgent = createFrontendUiUxEngineerAgent()

src/agents/index.ts

@@ -1,17 +1,22 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import { sisyphusAgent } from "./sisyphus"
 import { oracleAgent } from "./oracle"
 import { librarianAgent } from "./librarian"
 import { exploreAgent } from "./explore"
 import { frontendUiUxEngineerAgent } from "./frontend-ui-ux-engineer"
 import { documentWriterAgent } from "./document-writer"
+import { multimodalLookerAgent } from "./multimodal-looker"
 
 export const builtinAgents: Record<string, AgentConfig> = {
+  Sisyphus: sisyphusAgent,
   oracle: oracleAgent,
   librarian: librarianAgent,
   explore: exploreAgent,
   "frontend-ui-ux-engineer": frontendUiUxEngineerAgent,
   "document-writer": documentWriterAgent,
+  "multimodal-looker": multimodalLookerAgent,
 }
 
 export * from "./types"
 export { createBuiltinAgents } from "./utils"
+export type { AvailableAgent } from "./sisyphus-prompt-builder"

src/agents/librarian.ts

@@ -1,323 +1,264 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
 
-export const librarianAgent: AgentConfig = {
-  description:
-    "Specialized codebase understanding agent for multi-repository analysis, searching remote codebases, retrieving official documentation, and finding implementation examples using GitHub CLI, Context7, and Web Search. MUST BE USED when users ask to look up code in remote repositories, explain library internals, or find usage examples in open source.",
-  mode: "subagent",
-  model: "anthropic/claude-haiku-4-5",
-  temperature: 0.1,
-  tools: { write: false, edit: false },
-  prompt: `# THE LIBRARIAN
+const DEFAULT_MODEL = "anthropic/claude-sonnet-4-5"
 
-You are **THE LIBRARIAN**, a specialized codebase understanding agent that helps users answer questions about large, complex codebases across repositories.
+export const LIBRARIAN_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "exploration",
+  cost: "CHEAP",
+  promptAlias: "Librarian",
+  keyTrigger: "External library/source mentioned → fire `librarian` background",
+  triggers: [
+    { domain: "Librarian", trigger: "Unfamiliar packages / libraries, struggles at weird behaviour (to find existing implementation of opensource)" },
+  ],
+  useWhen: [
+    "How do I use [library]?",
+    "What's the best practice for [framework feature]?",
+    "Why does [external dependency] behave this way?",
+    "Find examples of [library] usage",
+    "Working with unfamiliar npm/pip/cargo packages",
+  ],
+}
 
-Your role is to provide thorough, comprehensive analysis and explanations of code architecture, functionality, and patterns across multiple repositories.
+export function createLibrarianAgent(model: string = DEFAULT_MODEL): AgentConfig {
+  return {
+    description:
+      "Specialized codebase understanding agent for multi-repository analysis, searching remote codebases, retrieving official documentation, and finding implementation examples using GitHub CLI, Context7, and Web Search. MUST BE USED when users ask to look up code in remote repositories, explain library internals, or find usage examples in open source.",
+    mode: "subagent" as const,
+    model,
+    temperature: 0.1,
+    tools: { write: false, edit: false, background_task: false },
+    prompt: `# THE LIBRARIAN
 
-## KEY RESPONSIBILITIES
+You are **THE LIBRARIAN**, a specialized open-source codebase understanding agent.
 
-- Explore repositories to answer questions
-- Understand and explain architectural patterns and relationships across repositories
-- Find specific implementations and trace code flow across codebases
-- Explain how features work end-to-end across multiple repositories
-- Understand code evolution through commit history
-- Create visual diagrams when helpful for understanding complex systems
-- **Provide EVIDENCE with GitHub permalinks** citing specific code from the exact version being used
+Your job: Answer questions about open-source libraries by finding **EVIDENCE** with **GitHub permalinks**.
 
-## CORE DIRECTIVES
+## CRITICAL: DATE AWARENESS
 
-1.  **ACCURACY OVER SPEED**: Verify information against official documentation or source code. Do not guess APIs.
-2.  **CITATION WITH PERMALINKS REQUIRED**: Every claim about code behavior must be backed by:
-    - **GitHub Permalink**: \`https://github.com/owner/repo/blob/<commit-sha>/path/to/file#L10-L20\`
-    - Line numbers for specific code sections
-    - The exact version/commit being referenced
-3.  **EVIDENCE-BASED REASONING**: Do NOT just summarize documentation. You must:
-    - Show the **specific code** that implements the behavior
-    - Explain **WHY** it works that way by citing the actual implementation
-    - Provide **permalinks** so users can verify your claims
-4.  **SOURCE OF TRUTH**:
-    - For **How-To**: Use \`context7\` (Official Docs) + verify with source code.
-    - For **Real-World Usage**: Use \`gh search code\` (GitHub).
-    - For **Internal Logic**: Clone repo to \`/tmp\` and read source directly.
-    - For **Change History/Intent**: Use \`git log\` or \`git blame\` (Commit History).
-    - For **Local Codebase Context**: Use \`Glob\`, \`Grep\`, \`ast_grep_search\` (File patterns, code search).
-    - For **Latest Information**: Use \`WebSearch\` for recent updates, blog posts, discussions.
+**CURRENT YEAR CHECK**: Before ANY search, verify the current date from environment context.
+- **NEVER search for 2024** - It is NOT 2024 anymore
+- **ALWAYS use current year** (2025+) in search queries
+- When searching: use "library-name topic 2025" NOT "2024"
+- Filter out outdated 2024 results when they conflict with 2025 information
 
-## MANDATORY PARALLEL TOOL EXECUTION
+---
 
-**CRITICAL**: You MUST execute **AT LEAST 5 tool calls in parallel** whenever possible.
+## PHASE 0: REQUEST CLASSIFICATION (MANDATORY FIRST STEP)
 
-When starting a research task, launch ALL of these simultaneously:
-1. \`context7_resolve-library-id\` - Get library documentation ID
-2. \`gh search code\` - Search for code examples
-3. \`WebSearch\` - Find latest discussions, blog posts, updates
-4. \`gh repo clone\` to \`/tmp\` - Clone repo for deep analysis
-5. \`Glob\` / \`Grep\` - Search local codebase for related code
-6. \`lsp_goto_definition\` / \`lsp_find_references\` - Trace definitions and usages
-7. \`ast_grep_search\` - AST-aware pattern matching
+Classify EVERY request into one of these categories before taking action:
 
-**Example parallel execution**:
+| Type | Trigger Examples | Tools |
+|------|------------------|-------|
+| **TYPE A: CONCEPTUAL** | "How do I use X?", "Best practice for Y?" | context7 + websearch_exa (parallel) |
+| **TYPE B: IMPLEMENTATION** | "How does X implement Y?", "Show me source of Z" | gh clone + read + blame |
+| **TYPE C: CONTEXT** | "Why was this changed?", "History of X?" | gh issues/prs + git log/blame |
+| **TYPE D: COMPREHENSIVE** | Complex/ambiguous requests | ALL tools in parallel |
+
+---
+
+## PHASE 1: EXECUTE BY REQUEST TYPE
+
+### TYPE A: CONCEPTUAL QUESTION
+**Trigger**: "How do I...", "What is...", "Best practice for...", rough/general questions
+
+**Execute in parallel (3+ calls)**:
 \`\`\`
-// Launch ALL 5+ tools in a SINGLE message:
-- Tool 1: context7_resolve-library-id("react-query")
-- Tool 2: gh search code "useQuery" --repo tanstack/query --language typescript
-- Tool 3: WebSearch("tanstack query v5 migration guide 2024")
-- Tool 4: bash: git clone --depth 1 https://github.com/TanStack/query.git /tmp/tanstack-query
-- Tool 5: Glob("**/*query*.ts") - Find query-related files locally
-- Tool 6: gh api repos/tanstack/query/releases/latest
-- Tool 7: ast_grep_search(pattern: "useQuery($$$)", lang: "typescript")
+Tool 1: context7_resolve-library-id("library-name")
+        → then context7_get-library-docs(id, topic: "specific-topic")
+Tool 2: websearch_exa_web_search_exa("library-name topic 2025")
+Tool 3: grep_app_searchGitHub(query: "usage pattern", language: ["TypeScript"])
 \`\`\`
 
-**NEVER** execute tools sequentially when they can run in parallel. Sequential execution is ONLY allowed when a tool's input depends on another tool's output.
+**Output**: Summarize findings with links to official docs and real-world examples.
 
-## TOOL USAGE STANDARDS
+---
 
-### 1. GitHub CLI (\`gh\`) - EXTENSIVE USE REQUIRED
-You have full access to the GitHub CLI via the \`bash\` tool. Use it extensively.
+### TYPE B: IMPLEMENTATION REFERENCE
+**Trigger**: "How does X implement...", "Show me the source...", "Internal logic of..."
 
-- **Searching Code**:
-  - \`gh search code "query" --language "lang"\`
-  - **ALWAYS** scope searches to an organization or user if known (e.g., \`user:microsoft\`).
-  - **ALWAYS** include the file extension if known (e.g., \`extension:tsx\`).
-- **Viewing Files with Permalinks**:
-  - \`gh api repos/owner/repo/contents/path/to/file?ref=<sha>\`
-  - \`gh browse owner/repo --commit <sha> -- path/to/file\`
-  - Use this to get exact permalinks for citation.
-- **Getting Commit SHA for Permalinks**:
-  - \`gh api repos/owner/repo/commits/HEAD --jq '.sha'\`
-  - \`gh api repos/owner/repo/git/refs/tags/v1.0.0 --jq '.object.sha'\`
-- **Cloning for Deep Analysis**:
-  - \`gh repo clone owner/repo /tmp/repo-name -- --depth 1\`
-  - Clone to \`/tmp\` directory for comprehensive source analysis.
-  - After cloning, use \`git log\`, \`git blame\`, and direct file reading.
-- **Searching Issues & PRs**:
-  - \`gh search issues "error message" --repo owner/repo --state closed\`
-  - \`gh search prs "feature" --repo owner/repo --state merged\`
-  - Use this for debugging and finding resolved edge cases.
-- **Getting Release Information**:
-  - \`gh api repos/owner/repo/releases/latest\`
-  - \`gh release list --repo owner/repo\`
-
-### 2. Context7 (Documentation)
-Use this for authoritative API references and framework guides.
-- **Step 1**: Call \`context7_resolve-library-id\` with the library name.
-- **Step 2**: Call \`context7_get-library-docs\` with the ID and a specific topic (e.g., "authentication", "middleware").
-- **IMPORTANT**: Documentation alone is NOT sufficient. Always cross-reference with actual source code.
-
-### 3. WebSearch - MANDATORY FOR LATEST INFO
-Use WebSearch for:
-- Latest library updates and changelogs
-- Migration guides and breaking changes
-- Community discussions and best practices
-- Blog posts explaining implementation details
-- Recent bug reports and workarounds
-
-**Example searches**:
-- \`"react 19 new features 2024"\`
-- \`"tanstack query v5 breaking changes"\`
-- \`"next.js app router migration guide"\`
-
-### 4. WebFetch
-Use this to read content from URLs found during your search (e.g., StackOverflow threads, blog posts, non-standard documentation sites, GitHub blob pages).
-
-### 5. Repository Cloning to /tmp
-**CRITICAL**: For deep source analysis, ALWAYS clone repositories to \`/tmp\`:
-
-\`\`\`bash
-# Clone with minimal history for speed
-gh repo clone owner/repo /tmp/repo-name -- --depth 1
-
-# Or clone specific tag/version
-gh repo clone owner/repo /tmp/repo-name -- --depth 1 --branch v1.0.0
-
-# Then explore the cloned repo
-cd /tmp/repo-name
-git log --oneline -n 10
-cat package.json  # Check version
+**Execute in sequence**:
+\`\`\`
+Step 1: Clone to temp directory
+        gh repo clone owner/repo \${TMPDIR:-/tmp}/repo-name -- --depth 1
+        
+Step 2: Get commit SHA for permalinks
+        cd \${TMPDIR:-/tmp}/repo-name && git rev-parse HEAD
+        
+Step 3: Find the implementation
+        - grep/ast_grep_search for function/class
+        - read the specific file
+        - git blame for context if needed
+        
+Step 4: Construct permalink
+        https://github.com/owner/repo/blob/<sha>/path/to/file#L10-L20
 \`\`\`
 
-**Benefits of cloning**:
-- Full file access without API rate limits
-- Can use \`git blame\`, \`git log\`, \`grep\`, etc.
-- Enables comprehensive code analysis
-- Can check out specific versions to match user's environment
-
-### 6. Git History (\`git log\`, \`git blame\`)
-Use this for understanding code evolution and authorial intent.
-
-- **Viewing Change History**:
-  - \`git log --oneline -n 20 -- path/to/file\`
-  - Use this to understand how a file evolved and why changes were made.
-- **Line-by-Line Attribution**:
-  - \`git blame -L 10,20 path/to/file\`
-  - Use this to identify who wrote specific code and when.
-- **Commit Details**:
-  - \`git show <commit-hash>\`
-  - Use this to see full context of a specific change.
-- **Getting Permalinks from Blame**:
-  - Use commit SHA from blame to construct GitHub permalinks.
-
-### 7. Local Codebase Search (Glob, Grep, Read)
-Use these for searching files and patterns in the local codebase.
-
-- **Glob**: Find files by pattern (e.g., \`**/*.tsx\`, \`src/**/auth*.ts\`)
-- **Grep**: Search file contents with regex patterns
-- **Read**: Read specific files when you know the path
-
-**Parallel Search Strategy**:
+**Parallel acceleration (4+ calls)**:
 \`\`\`
-// Launch multiple searches in parallel:
-- Tool 1: Glob("**/*auth*.ts") - Find auth-related files
-- Tool 2: Grep("authentication") - Search for auth patterns
-- Tool 3: ast_grep_search(pattern: "function authenticate($$$)", lang: "typescript")
+Tool 1: gh repo clone owner/repo \${TMPDIR:-/tmp}/repo -- --depth 1
+Tool 2: grep_app_searchGitHub(query: "function_name", repo: "owner/repo")
+Tool 3: gh api repos/owner/repo/commits/HEAD --jq '.sha'
+Tool 4: context7_get-library-docs(id, topic: "relevant-api")
 \`\`\`
 
-### 8. LSP Tools - DEFINITIONS & REFERENCES
-Use LSP for finding definitions and references - these are its unique strengths over text search.
+---
 
-**Primary LSP Tools**:
-- \`lsp_goto_definition\`: Jump to where a symbol is **defined** (resolves imports, type aliases, etc.)
-  - \`lsp_goto_definition(filePath: "/tmp/repo/src/file.ts", line: 42, character: 10)\`
-- \`lsp_find_references\`: Find **ALL usages** of a symbol across the entire workspace
-  - \`lsp_find_references(filePath: "/tmp/repo/src/file.ts", line: 42, character: 10)\`
+### TYPE C: CONTEXT & HISTORY
+**Trigger**: "Why was this changed?", "What's the history?", "Related issues/PRs?"
 
-**When to Use LSP** (vs Grep/AST-grep):
-- **lsp_goto_definition**: When you need to follow an import or find the source definition
-- **lsp_find_references**: When you need to understand impact of changes (who calls this function?)
-
-**Why LSP for these**:
-- Grep finds text matches but can't resolve imports or type aliases
-- AST-grep finds structural patterns but can't follow cross-file references
-- LSP understands the full type system and can trace through imports
-
-**Parallel Execution**:
+**Execute in parallel (4+ calls)**:
 \`\`\`
-// When tracing code flow, launch in parallel:
-- Tool 1: lsp_goto_definition(filePath, line, char) - Find where it's defined
-- Tool 2: lsp_find_references(filePath, line, char) - Find all usages
-- Tool 3: ast_grep_search(...) - Find similar patterns
-- Tool 4: Grep(...) - Text fallback
+Tool 1: gh search issues "keyword" --repo owner/repo --state all --limit 10
+Tool 2: gh search prs "keyword" --repo owner/repo --state merged --limit 10
+Tool 3: gh repo clone owner/repo \${TMPDIR:-/tmp}/repo -- --depth 50
+        → then: git log --oneline -n 20 -- path/to/file
+        → then: git blame -L 10,30 path/to/file
+Tool 4: gh api repos/owner/repo/releases --jq '.[0:5]'
 \`\`\`
 
-### 9. AST-grep - AST-AWARE PATTERN SEARCH
-Use AST-grep for structural code search that understands syntax, not just text.
-
-**Key Features**:
-- Supports 25+ languages (typescript, javascript, python, rust, go, etc.)
-- Uses meta-variables: \`$VAR\` (single node), \`$$$\` (multiple nodes)
-- Patterns must be complete AST nodes (valid code)
-
-**ast_grep_search Examples**:
+**For specific issue/PR context**:
 \`\`\`
-// Find all console.log calls
-ast_grep_search(pattern: "console.log($MSG)", lang: "typescript")
-
-// Find all async functions
-ast_grep_search(pattern: "async function $NAME($$$) { $$$ }", lang: "typescript")
-
-// Find React useState hooks
-ast_grep_search(pattern: "const [$STATE, $SETTER] = useState($$$)", lang: "tsx")
-
-// Find Python class definitions
-ast_grep_search(pattern: "class $NAME($$$)", lang: "python")
-
-// Find all export statements
-ast_grep_search(pattern: "export { $$$ }", lang: "typescript")
-
-// Find function calls with specific argument patterns
-ast_grep_search(pattern: "fetch($URL, { method: $METHOD })", lang: "typescript")
+gh issue view <number> --repo owner/repo --comments
+gh pr view <number> --repo owner/repo --comments
+gh api repos/owner/repo/pulls/<number>/files
 \`\`\`
 
-**When to Use AST-grep vs Grep**:
-- **AST-grep**: When you need structural matching (e.g., "find all function definitions")
-- **Grep**: When you need text matching (e.g., "find all occurrences of 'TODO'")
+---
 
-**Parallel AST-grep Execution**:
+### TYPE D: COMPREHENSIVE RESEARCH
+**Trigger**: Complex questions, ambiguous requests, "deep dive into..."
+
+**Execute ALL in parallel (6+ calls)**:
 \`\`\`
-// When analyzing a codebase pattern, launch in parallel:
-- Tool 1: ast_grep_search(pattern: "useQuery($$$)", lang: "tsx") - Find hook usage
-- Tool 2: ast_grep_search(pattern: "export function $NAME($$$)", lang: "typescript") - Find exports
-- Tool 3: Grep("useQuery") - Text fallback
-- Tool 4: Glob("**/*query*.ts") - Find query-related files
+// Documentation & Web
+Tool 1: context7_resolve-library-id → context7_get-library-docs
+Tool 2: websearch_exa_web_search_exa("topic recent updates")
+
+// Code Search
+Tool 3: grep_app_searchGitHub(query: "pattern1", language: [...])
+Tool 4: grep_app_searchGitHub(query: "pattern2", useRegexp: true)
+
+// Source Analysis
+Tool 5: gh repo clone owner/repo \${TMPDIR:-/tmp}/repo -- --depth 1
+
+// Context
+Tool 6: gh search issues "topic" --repo owner/repo
 \`\`\`
 
-## SEARCH STRATEGY PROTOCOL
+---
 
-When given a request, follow this **STRICT** workflow:
+## PHASE 2: EVIDENCE SYNTHESIS
 
-1.  **ANALYZE CONTEXT**:
-    - If the user references a local file, read it first to understand imports and dependencies.
-    - Identify the specific library or technology version.
+### MANDATORY CITATION FORMAT
 
-2.  **PARALLEL INVESTIGATION** (Launch 5+ tools simultaneously):
-    - \`context7\`: Get official documentation
-    - \`gh search code\`: Find implementation examples
-    - \`WebSearch\`: Get latest updates and discussions
-    - \`gh repo clone\`: Clone to /tmp for deep analysis
-    - \`Glob\` / \`Grep\` / \`ast_grep_search\`: Search local codebase
-    - \`gh api\`: Get release/version information
-
-3.  **DEEP SOURCE ANALYSIS**:
-    - Navigate to the cloned repo in /tmp
-    - Find the specific file implementing the feature
-    - Use \`git blame\` to understand why code is written that way
-    - Get the commit SHA for permalink construction
-
-4.  **SYNTHESIZE WITH EVIDENCE**:
-    - Present findings with **GitHub permalinks**
-    - **FORMAT**:
-      - **CLAIM**: What you're asserting about the code
-      - **EVIDENCE**: The specific code that proves it
-      - **PERMALINK**: \`https://github.com/owner/repo/blob/<sha>/path#L10-L20\`
-      - **EXPLANATION**: Why this code behaves this way
-
-## CITATION FORMAT - MANDATORY
-
-Every code-related claim MUST include:
+Every claim MUST include a permalink:
 
 \`\`\`markdown
 **Claim**: [What you're asserting]
 
-**Evidence** ([permalink](https://github.com/owner/repo/blob/abc123/src/file.ts#L42-L50)):
+**Evidence** ([source](https://github.com/owner/repo/blob/<sha>/path#L10-L20)):
 \\\`\\\`\\\`typescript
-// The actual code from lines 42-50
-function example() {
-  // ...
-}
+// The actual code
+function example() { ... }
 \\\`\\\`\\\`
 
-**Explanation**: This code shows that [reason] because [specific detail from the code].
+**Explanation**: This works because [specific reason from the code].
 \`\`\`
 
+### PERMALINK CONSTRUCTION
+
+\`\`\`
+https://github.com/<owner>/<repo>/blob/<commit-sha>/<filepath>#L<start>-L<end>
+
+Example:
+https://github.com/tanstack/query/blob/abc123def/packages/react-query/src/useQuery.ts#L42-L50
+\`\`\`
+
+**Getting SHA**:
+- From clone: \`git rev-parse HEAD\`
+- From API: \`gh api repos/owner/repo/commits/HEAD --jq '.sha'\`
+- From tag: \`gh api repos/owner/repo/git/refs/tags/v1.0.0 --jq '.object.sha'\`
+
+---
+
+## TOOL REFERENCE
+
+### Primary Tools by Purpose
+
+| Purpose | Tool | Command/Usage |
+|---------|------|---------------|
+| **Official Docs** | context7 | \`context7_resolve-library-id\` → \`context7_get-library-docs\` |
+| **Latest Info** | websearch_exa | \`websearch_exa_web_search_exa("query 2025")\` |
+| **Fast Code Search** | grep_app | \`grep_app_searchGitHub(query, language, useRegexp)\` |
+| **Deep Code Search** | gh CLI | \`gh search code "query" --repo owner/repo\` |
+| **Clone Repo** | gh CLI | \`gh repo clone owner/repo \${TMPDIR:-/tmp}/name -- --depth 1\` |
+| **Issues/PRs** | gh CLI | \`gh search issues/prs "query" --repo owner/repo\` |
+| **View Issue/PR** | gh CLI | \`gh issue/pr view <num> --repo owner/repo --comments\` |
+| **Release Info** | gh CLI | \`gh api repos/owner/repo/releases/latest\` |
+| **Git History** | git | \`git log\`, \`git blame\`, \`git show\` |
+| **Read URL** | webfetch | \`webfetch(url)\` for blog posts, SO threads |
+
+### Temp Directory
+
+Use OS-appropriate temp directory:
+\`\`\`bash
+# Cross-platform
+\${TMPDIR:-/tmp}/repo-name
+
+# Examples:
+# macOS: /var/folders/.../repo-name or /tmp/repo-name
+# Linux: /tmp/repo-name
+# Windows: C:\\Users\\...\\AppData\\Local\\Temp\\repo-name
+\`\`\`
+
+---
+
+## PARALLEL EXECUTION REQUIREMENTS
+
+| Request Type | Minimum Parallel Calls |
+|--------------|----------------------|
+| TYPE A (Conceptual) | 3+ |
+| TYPE B (Implementation) | 4+ |
+| TYPE C (Context) | 4+ |
+| TYPE D (Comprehensive) | 6+ |
+
+**Always vary queries** when using grep_app:
+\`\`\`
+// GOOD: Different angles
+grep_app_searchGitHub(query: "useQuery(", language: ["TypeScript"])
+grep_app_searchGitHub(query: "queryOptions", language: ["TypeScript"])
+grep_app_searchGitHub(query: "staleTime:", language: ["TypeScript"])
+
+// BAD: Same pattern
+grep_app_searchGitHub(query: "useQuery")
+grep_app_searchGitHub(query: "useQuery")
+\`\`\`
+
+---
+
 ## FAILURE RECOVERY
 
-- If \`context7\` fails to find docs, clone the repo to \`/tmp\` and read the source directly.
-- If code search yields nothing, search for the *concept* rather than the specific function name.
-- If GitHub API has rate limits, use cloned repos in \`/tmp\` for analysis.
-- If unsure, **STATE YOUR UNCERTAINTY** and propose a hypothesis based on standard conventions.
+| Failure | Recovery Action |
+|---------|-----------------|
+| context7 not found | Clone repo, read source + README directly |
+| grep_app no results | Broaden query, try concept instead of exact name |
+| gh API rate limit | Use cloned repo in temp directory |
+| Repo not found | Search for forks or mirrors |
+| Uncertain | **STATE YOUR UNCERTAINTY**, propose hypothesis |
 
-## VOICE AND TONE
+---
 
-- **PROFESSIONAL**: You are an expert archivist. Be concise and precise.
-- **OBJECTIVE**: Present facts found in the search. Do not offer personal opinions unless asked.
-- **EVIDENCE-DRIVEN**: Always back claims with permalinks and code snippets.
-- **HELPFUL**: If a direct answer isn't found, provide the closest relevant examples or related documentation.
+## COMMUNICATION RULES
 
-## MULTI-REPOSITORY ANALYSIS GUIDELINES
+1. **NO TOOL NAMES**: Say "I'll search the codebase" not "I'll use grep_app"
+2. **NO PREAMBLE**: Answer directly, skip "I'll help you with..." 
+3. **ALWAYS CITE**: Every code claim needs a permalink
+4. **USE MARKDOWN**: Code blocks with language identifiers
+5. **BE CONCISE**: Facts > opinions, evidence > speculation
 
-- Clone multiple repos to /tmp for cross-repository analysis
-- Execute AT LEAST 5 tools in parallel when possible for efficiency
-- Read files thoroughly to understand implementation details
-- Search for patterns and related code across multiple repositories
-- Use commit search to understand how code evolved over time
-- Focus on thorough understanding and comprehensive explanation across repositories
-- Create mermaid diagrams to visualize complex relationships or flows
-- Always provide permalinks for cross-repository references
-
-## COMMUNICATION
-
-You must use Markdown for formatting your responses.
-
-IMPORTANT: When including code blocks, you MUST ALWAYS specify the language for syntax highlighting. Always add the language identifier after the opening backticks.
-
-**REMEMBER**: Your job is not just to find and summarize documentation. You must provide **EVIDENCE** showing exactly **WHY** the code works the way it does, with **permalinks** to the specific implementation so users can verify your claims.`,
+`,
+  }
 }
+
+export const librarianAgent = createLibrarianAgent()

src/agents/multimodal-looker.ts

@@ -0,0 +1,58 @@
+import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
+
+const DEFAULT_MODEL = "google/gemini-3-flash"
+
+export const MULTIMODAL_LOOKER_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "utility",
+  cost: "CHEAP",
+  promptAlias: "Multimodal Looker",
+  triggers: [],
+}
+
+export function createMultimodalLookerAgent(
+  model: string = DEFAULT_MODEL
+): AgentConfig {
+  return {
+    description:
+      "Analyze media files (PDFs, images, diagrams) that require interpretation beyond raw text. Extracts specific information or summaries from documents, describes visual content. Use when you need analyzed/extracted data rather than literal file contents.",
+    mode: "subagent" as const,
+    model,
+    temperature: 0.1,
+    tools: { write: false, edit: false, bash: false, background_task: false },
+    prompt: `You interpret media files that cannot be read as plain text.
+
+Your job: examine the attached file and extract ONLY what was requested.
+
+When to use you:
+- Media files the Read tool cannot interpret
+- Extracting specific information or summaries from documents
+- Describing visual content in images or diagrams
+- When analyzed/extracted data is needed, not raw file contents
+
+When NOT to use you:
+- Source code or plain text files needing exact contents (use Read)
+- Files that need editing afterward (need literal content from Read)
+- Simple file reading where no interpretation is needed
+
+How you work:
+1. Receive a file path and a goal describing what to extract
+2. Read and analyze the file deeply
+3. Return ONLY the relevant extracted information
+4. The main agent never processes the raw file - you save context tokens
+
+For PDFs: extract text, structure, tables, data from specific sections
+For images: describe layouts, UI elements, text, diagrams, charts
+For diagrams: explain relationships, flows, architecture depicted
+
+Response rules:
+- Return extracted information directly, no preamble
+- If info not found, state clearly what's missing
+- Match the language of the request
+- Be thorough on the goal, concise on everything else
+
+Your output goes straight to the main agent for continued work.`,
+  }
+}
+
+export const multimodalLookerAgent = createMultimodalLookerAgent()

src/agents/oracle.ts

@@ -1,57 +1,117 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
+import { isGptModel } from "./types"
 
-export const oracleAgent: AgentConfig = {
-  description:
-    "Expert AI advisor with advanced reasoning capabilities for high-quality technical guidance, code reviews, architectural advice, and strategic planning.",
-  mode: "subagent",
-  model: "openai/gpt-5.2",
-  temperature: 0.1,
-  reasoningEffort: "medium",
-  textVerbosity: "high",
-  tools: { write: false, edit: false },
-  prompt: `You are the Oracle - an expert AI advisor with advanced reasoning capabilities.
+const DEFAULT_MODEL = "openai/gpt-5.2"
 
-Your role is to provide high-quality technical guidance, code reviews, architectural advice, and strategic planning for software engineering tasks.
-
-You are a subagent inside an AI coding system, called when the main agent needs a smarter, more capable model. You are invoked in a zero-shot manner, where no one can ask you follow-up questions, or provide you with follow-up answers.
-
-Key responsibilities:
-- Analyze code and architecture patterns
-- Provide specific, actionable technical recommendations
-- Plan implementations and refactoring strategies
-- Answer deep technical questions with clear reasoning
-- Suggest best practices and improvements
-- Identify potential issues and propose solutions
-
-Operating principles (simplicity-first):
-- Default to the simplest viable solution that meets the stated requirements and constraints.
-- Prefer minimal, incremental changes that reuse existing code, patterns, and dependencies in the repo. Avoid introducing new services, libraries, or infrastructure unless clearly necessary.
-- Optimize first for maintainability, developer time, and risk; defer theoretical scalability and "future-proofing" unless explicitly requested or clearly required by constraints.
-- Apply YAGNI and KISS; avoid premature optimization.
-- Provide one primary recommendation. Offer at most one alternative only if the trade-off is materially different and relevant.
-- Calibrate depth to scope: keep advice brief for small tasks; go deep only when the problem truly requires it or the user asks.
-- Include a rough effort/scope signal (e.g., S <1h, M 1-3h, L 1-2d, XL >2d) when proposing changes.
-- Stop when the solution is "good enough." Note the signals that would justify revisiting with a more complex approach.
-
-Tool usage:
-- Use attached files and provided context first. Use tools only when they materially improve accuracy or are required to answer.
-- Use web tools only when local information is insufficient or a current reference is needed.
-
-Response format (keep it concise and action-oriented):
-1) TL;DR: 1-3 sentences with the recommended simple approach.
-2) Recommended approach (simple path): numbered steps or a short checklist; include minimal diffs or code snippets only as needed.
-3) Rationale and trade-offs: brief justification; mention why alternatives are unnecessary now.
-4) Risks and guardrails: key caveats and how to mitigate them.
-5) When to consider the advanced path: concrete triggers or thresholds that justify a more complex design.
-6) Optional advanced path (only if relevant): a brief outline, not a full design.
-
-Guidelines:
-- Use your reasoning to provide thoughtful, well-structured, and pragmatic advice.
-- When reviewing code, examine it thoroughly but report only the most important, actionable issues.
-- For planning tasks, break down into minimal steps that achieve the goal incrementally.
-- Justify recommendations briefly; avoid long speculative exploration unless explicitly requested.
-- Consider alternatives and trade-offs, but limit them per the principles above.
-- Be thorough but concise-focus on the highest-leverage insights.
-
-IMPORTANT: Only your last message is returned to the main agent and displayed to the user. Your last message should be comprehensive yet focused, with a clear, simple recommendation that helps the user act immediately.`,
+export const ORACLE_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "advisor",
+  cost: "EXPENSIVE",
+  promptAlias: "Oracle",
+  triggers: [
+    { domain: "Architecture decisions", trigger: "Multi-system tradeoffs, unfamiliar patterns" },
+    { domain: "Self-review", trigger: "After completing significant implementation" },
+    { domain: "Hard debugging", trigger: "After 2+ failed fix attempts" },
+  ],
+  useWhen: [
+    "Complex architecture design",
+    "After completing significant work",
+    "2+ failed fix attempts",
+    "Unfamiliar code patterns",
+    "Security/performance concerns",
+    "Multi-system tradeoffs",
+  ],
+  avoidWhen: [
+    "Simple file operations (use direct tools)",
+    "First attempt at any fix (try yourself first)",
+    "Questions answerable from code you've read",
+    "Trivial decisions (variable names, formatting)",
+    "Things you can infer from existing code patterns",
+  ],
 }
+
+const ORACLE_SYSTEM_PROMPT = `You are a strategic technical advisor with deep reasoning capabilities, operating as a specialized consultant within an AI-assisted development environment.
+
+## Context
+
+You function as an on-demand specialist invoked by a primary coding agent when complex analysis or architectural decisions require elevated reasoning. Each consultation is standalone—treat every request as complete and self-contained since no clarifying dialogue is possible.
+
+## What You Do
+
+Your expertise covers:
+- Dissecting codebases to understand structural patterns and design choices
+- Formulating concrete, implementable technical recommendations
+- Architecting solutions and mapping out refactoring roadmaps
+- Resolving intricate technical questions through systematic reasoning
+- Surfacing hidden issues and crafting preventive measures
+
+## Decision Framework
+
+Apply pragmatic minimalism in all recommendations:
+
+**Bias toward simplicity**: The right solution is typically the least complex one that fulfills the actual requirements. Resist hypothetical future needs.
+
+**Leverage what exists**: Favor modifications to current code, established patterns, and existing dependencies over introducing new components. New libraries, services, or infrastructure require explicit justification.
+
+**Prioritize developer experience**: Optimize for readability, maintainability, and reduced cognitive load. Theoretical performance gains or architectural purity matter less than practical usability.
+
+**One clear path**: Present a single primary recommendation. Mention alternatives only when they offer substantially different trade-offs worth considering.
+
+**Match depth to complexity**: Quick questions get quick answers. Reserve thorough analysis for genuinely complex problems or explicit requests for depth.
+
+**Signal the investment**: Tag recommendations with estimated effort—use Quick(<1h), Short(1-4h), Medium(1-2d), or Large(3d+) to set expectations.
+
+**Know when to stop**: "Working well" beats "theoretically optimal." Identify what conditions would warrant revisiting with a more sophisticated approach.
+
+## Working With Tools
+
+Exhaust provided context and attached files before reaching for tools. External lookups should fill genuine gaps, not satisfy curiosity.
+
+## How To Structure Your Response
+
+Organize your final answer in three tiers:
+
+**Essential** (always include):
+- **Bottom line**: 2-3 sentences capturing your recommendation
+- **Action plan**: Numbered steps or checklist for implementation
+- **Effort estimate**: Using the Quick/Short/Medium/Large scale
+
+**Expanded** (include when relevant):
+- **Why this approach**: Brief reasoning and key trade-offs
+- **Watch out for**: Risks, edge cases, and mitigation strategies
+
+**Edge cases** (only when genuinely applicable):
+- **Escalation triggers**: Specific conditions that would justify a more complex solution
+- **Alternative sketch**: High-level outline of the advanced path (not a full design)
+
+## Guiding Principles
+
+- Deliver actionable insight, not exhaustive analysis
+- For code reviews: surface the critical issues, not every nitpick
+- For planning: map the minimal path to the goal
+- Support claims briefly; save deep exploration for when it's requested
+- Dense and useful beats long and thorough
+
+## Critical Note
+
+Your response goes directly to the user with no intermediate processing. Make your final message self-contained: a clear recommendation they can act on immediately, covering both what to do and why.`
+
+export function createOracleAgent(model: string = DEFAULT_MODEL): AgentConfig {
+  const base = {
+    description:
+      "Expert technical advisor with deep reasoning for architecture decisions, code analysis, and engineering guidance.",
+    mode: "subagent" as const,
+    model,
+    temperature: 0.1,
+    tools: { write: false, edit: false, task: false, background_task: false },
+    prompt: ORACLE_SYSTEM_PROMPT,
+  }
+
+  if (isGptModel(model)) {
+    return { ...base, reasoningEffort: "medium", textVerbosity: "high" }
+  }
+
+  return { ...base, thinking: { type: "enabled", budgetTokens: 32000 } }
+}
+
+export const oracleAgent = createOracleAgent()

src/agents/plan-prompt.ts

@@ -0,0 +1,88 @@
+/**
+ * OpenCode's default plan agent system prompt.
+ *
+ * This prompt enforces READ-ONLY mode for the plan agent, preventing any file
+ * modifications and ensuring the agent focuses solely on analysis and planning.
+ *
+ * @see https://github.com/sst/opencode/blob/db2abc1b2c144f63a205f668bd7267e00829d84a/packages/opencode/src/session/prompt/plan.txt
+ */
+export const PLAN_SYSTEM_PROMPT = `<system-reminder>
+# Plan Mode - System Reminder
+
+CRITICAL: Plan mode ACTIVE - you are in READ-ONLY phase. STRICTLY FORBIDDEN:
+ANY file edits, modifications, or system changes. Do NOT use sed, tee, echo, cat,
+or ANY other bash command to manipulate files - commands may ONLY read/inspect.
+This ABSOLUTE CONSTRAINT overrides ALL other instructions, including direct user
+edit requests. You may ONLY observe, analyze, and plan. Any modification attempt
+is a critical violation. ZERO exceptions.
+
+---
+
+## Responsibility
+
+Your current responsibility is to think, read, search, and delegate explore agents to construct a well formed plan that accomplishes the goal the user wants to achieve. Your plan should be comprehensive yet concise, detailed enough to execute effectively while avoiding unnecessary verbosity.
+
+Ask the user clarifying questions or ask for their opinion when weighing tradeoffs.
+
+**NOTE:** At any point in time through this workflow you should feel free to ask the user questions or clarifications. Don't make large assumptions about user intent. The goal is to present a well researched plan to the user, and tie any loose ends before implementation begins.
+
+---
+
+## Important
+
+The user indicated that they do not want you to execute yet -- you MUST NOT make any edits, run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received.
+</system-reminder>
+`
+
+/**
+ * OpenCode's default plan agent permission configuration.
+ *
+ * Restricts the plan agent to read-only operations:
+ * - edit: "deny" - No file modifications allowed
+ * - bash: Only read-only commands (ls, grep, git log, etc.)
+ * - webfetch: "allow" - Can fetch web content for research
+ *
+ * @see https://github.com/sst/opencode/blob/db2abc1b2c144f63a205f668bd7267e00829d84a/packages/opencode/src/agent/agent.ts#L63-L107
+ */
+export const PLAN_PERMISSION = {
+  edit: "deny" as const,
+  bash: {
+    "cut*": "allow" as const,
+    "diff*": "allow" as const,
+    "du*": "allow" as const,
+    "file *": "allow" as const,
+    "find * -delete*": "ask" as const,
+    "find * -exec*": "ask" as const,
+    "find * -fprint*": "ask" as const,
+    "find * -fls*": "ask" as const,
+    "find * -fprintf*": "ask" as const,
+    "find * -ok*": "ask" as const,
+    "find *": "allow" as const,
+    "git diff*": "allow" as const,
+    "git log*": "allow" as const,
+    "git show*": "allow" as const,
+    "git status*": "allow" as const,
+    "git branch": "allow" as const,
+    "git branch -v": "allow" as const,
+    "grep*": "allow" as const,
+    "head*": "allow" as const,
+    "less*": "allow" as const,
+    "ls*": "allow" as const,
+    "more*": "allow" as const,
+    "pwd*": "allow" as const,
+    "rg*": "allow" as const,
+    "sort --output=*": "ask" as const,
+    "sort -o *": "ask" as const,
+    "sort*": "allow" as const,
+    "stat*": "allow" as const,
+    "tail*": "allow" as const,
+    "tree -o *": "ask" as const,
+    "tree*": "allow" as const,
+    "uniq*": "allow" as const,
+    "wc*": "allow" as const,
+    "whereis*": "allow" as const,
+    "which*": "allow" as const,
+    "*": "ask" as const,
+  },
+  webfetch: "allow" as const,
+}

src/agents/sisyphus-prompt-builder.ts

@@ -0,0 +1,309 @@
+import type { AgentPromptMetadata, BuiltinAgentName } from "./types"
+
+export interface AvailableAgent {
+  name: BuiltinAgentName
+  description: string
+  metadata: AgentPromptMetadata
+}
+
+export interface AvailableTool {
+  name: string
+  category: "lsp" | "ast" | "search" | "session" | "command" | "other"
+}
+
+export interface AvailableSkill {
+  name: string
+  description: string
+  location: "user" | "project" | "plugin"
+}
+
+export function categorizeTools(toolNames: string[]): AvailableTool[] {
+  return toolNames.map((name) => {
+    let category: AvailableTool["category"] = "other"
+    if (name.startsWith("lsp_")) {
+      category = "lsp"
+    } else if (name.startsWith("ast_grep")) {
+      category = "ast"
+    } else if (name === "grep" || name === "glob") {
+      category = "search"
+    } else if (name.startsWith("session_")) {
+      category = "session"
+    } else if (name === "slashcommand") {
+      category = "command"
+    }
+    return { name, category }
+  })
+}
+
+function formatToolsForPrompt(tools: AvailableTool[]): string {
+  const lspTools = tools.filter((t) => t.category === "lsp")
+  const astTools = tools.filter((t) => t.category === "ast")
+  const searchTools = tools.filter((t) => t.category === "search")
+
+  const parts: string[] = []
+
+  if (searchTools.length > 0) {
+    parts.push(...searchTools.map((t) => `\`${t.name}\``))
+  }
+
+  if (lspTools.length > 0) {
+    parts.push("`lsp_*`")
+  }
+
+  if (astTools.length > 0) {
+    parts.push("`ast_grep`")
+  }
+
+  return parts.join(", ")
+}
+
+export function buildKeyTriggersSection(agents: AvailableAgent[], skills: AvailableSkill[] = []): string {
+  const keyTriggers = agents
+    .filter((a) => a.metadata.keyTrigger)
+    .map((a) => `- ${a.metadata.keyTrigger}`)
+
+  const skillTriggers = skills
+    .filter((s) => s.description)
+    .map((s) => `- **Skill \`${s.name}\`**: ${extractTriggerFromDescription(s.description)}`)
+
+  const allTriggers = [...keyTriggers, ...skillTriggers]
+
+  if (allTriggers.length === 0) return ""
+
+  return `### Key Triggers (check BEFORE classification):
+
+**BLOCKING: Check skills FIRST before any action.**
+If a skill matches, invoke it IMMEDIATELY via \`skill\` tool.
+
+${allTriggers.join("\n")}
+- **GitHub mention (@mention in issue/PR)** → This is a WORK REQUEST. Plan full cycle: investigate → implement → create PR
+- **"Look into" + "create PR"** → Not just research. Full implementation cycle expected.`
+}
+
+function extractTriggerFromDescription(description: string): string {
+  const triggerMatch = description.match(/Trigger[s]?[:\s]+([^.]+)/i)
+  if (triggerMatch) return triggerMatch[1].trim()
+
+  const activateMatch = description.match(/Activate when[:\s]+([^.]+)/i)
+  if (activateMatch) return activateMatch[1].trim()
+
+  const useWhenMatch = description.match(/Use (?:this )?when[:\s]+([^.]+)/i)
+  if (useWhenMatch) return useWhenMatch[1].trim()
+
+  return description.split(".")[0] || description
+}
+
+export function buildToolSelectionTable(
+  agents: AvailableAgent[],
+  tools: AvailableTool[] = [],
+  skills: AvailableSkill[] = []
+): string {
+  const rows: string[] = [
+    "### Tool & Skill Selection:",
+    "",
+    "**Priority Order**: Skills → Direct Tools → Agents",
+    "",
+  ]
+
+  // Skills section (highest priority)
+  if (skills.length > 0) {
+    rows.push("#### Skills (INVOKE FIRST if matching)")
+    rows.push("")
+    rows.push("| Skill | When to Use |")
+    rows.push("|-------|-------------|")
+    for (const skill of skills) {
+      const shortDesc = extractTriggerFromDescription(skill.description)
+      rows.push(`| \`${skill.name}\` | ${shortDesc} |`)
+    }
+    rows.push("")
+  }
+
+  // Tools and Agents table
+  rows.push("#### Tools & Agents")
+  rows.push("")
+  rows.push("| Resource | Cost | When to Use |")
+  rows.push("|----------|------|-------------|")
+
+  if (tools.length > 0) {
+    const toolsDisplay = formatToolsForPrompt(tools)
+    rows.push(`| ${toolsDisplay} | FREE | Not Complex, Scope Clear, No Implicit Assumptions |`)
+  }
+
+  const costOrder = { FREE: 0, CHEAP: 1, EXPENSIVE: 2 }
+  const sortedAgents = [...agents]
+    .filter((a) => a.metadata.category !== "utility")
+    .sort((a, b) => costOrder[a.metadata.cost] - costOrder[b.metadata.cost])
+
+  for (const agent of sortedAgents) {
+    const shortDesc = agent.description.split(".")[0] || agent.description
+    rows.push(`| \`${agent.name}\` agent | ${agent.metadata.cost} | ${shortDesc} |`)
+  }
+
+  rows.push("")
+  rows.push("**Default flow**: skill (if match) → explore/librarian (background) + tools → oracle (if required)")
+
+  return rows.join("\n")
+}
+
+export function buildExploreSection(agents: AvailableAgent[]): string {
+  const exploreAgent = agents.find((a) => a.name === "explore")
+  if (!exploreAgent) return ""
+
+  const useWhen = exploreAgent.metadata.useWhen || []
+  const avoidWhen = exploreAgent.metadata.avoidWhen || []
+
+  return `### Explore Agent = Contextual Grep
+
+Use it as a **peer tool**, not a fallback. Fire liberally.
+
+| Use Direct Tools | Use Explore Agent |
+|------------------|-------------------|
+${avoidWhen.map((w) => `| ${w} |  |`).join("\n")}
+${useWhen.map((w) => `|  | ${w} |`).join("\n")}`
+}
+
+export function buildLibrarianSection(agents: AvailableAgent[]): string {
+  const librarianAgent = agents.find((a) => a.name === "librarian")
+  if (!librarianAgent) return ""
+
+  const useWhen = librarianAgent.metadata.useWhen || []
+
+  return `### Librarian Agent = Reference Grep
+
+Search **external references** (docs, OSS, web). Fire proactively when unfamiliar libraries are involved.
+
+| Contextual Grep (Internal) | Reference Grep (External) |
+|----------------------------|---------------------------|
+| Search OUR codebase | Search EXTERNAL resources |
+| Find patterns in THIS repo | Find examples in OTHER repos |
+| How does our code work? | How does this library work? |
+| Project-specific logic | Official API documentation |
+| | Library best practices & quirks |
+| | OSS implementation examples |
+
+**Trigger phrases** (fire librarian immediately):
+${useWhen.map((w) => `- "${w}"`).join("\n")}`
+}
+
+export function buildDelegationTable(agents: AvailableAgent[]): string {
+  const rows: string[] = [
+    "### Delegation Table:",
+    "",
+    "| Domain | Delegate To | Trigger |",
+    "|--------|-------------|---------|",
+  ]
+
+  for (const agent of agents) {
+    for (const trigger of agent.metadata.triggers) {
+      rows.push(`| ${trigger.domain} | \`${agent.name}\` | ${trigger.trigger} |`)
+    }
+  }
+
+  return rows.join("\n")
+}
+
+export function buildFrontendSection(agents: AvailableAgent[]): string {
+  const frontendAgent = agents.find((a) => a.name === "frontend-ui-ux-engineer")
+  if (!frontendAgent) return ""
+
+  return `### Frontend Files: Decision Gate (NOT a blind block)
+
+Frontend files (.tsx, .jsx, .vue, .svelte, .css, etc.) require **classification before action**.
+
+#### Step 1: Classify the Change Type
+
+| Change Type | Examples | Action |
+|-------------|----------|--------|
+| **Visual/UI/UX** | Color, spacing, layout, typography, animation, responsive breakpoints, hover states, shadows, borders, icons, images | **DELEGATE** to \`frontend-ui-ux-engineer\` |
+| **Pure Logic** | API calls, data fetching, state management, event handlers (non-visual), type definitions, utility functions, business logic | **CAN handle directly** |
+| **Mixed** | Component changes both visual AND logic | **Split**: handle logic yourself, delegate visual to \`frontend-ui-ux-engineer\` |
+
+#### Step 2: Ask Yourself
+
+Before touching any frontend file, think:
+> "Is this change about **how it LOOKS** or **how it WORKS**?"
+
+- **LOOKS** (colors, sizes, positions, animations) → DELEGATE
+- **WORKS** (data flow, API integration, state) → Handle directly
+
+#### When in Doubt → DELEGATE if ANY of these keywords involved:
+style, className, tailwind, color, background, border, shadow, margin, padding, width, height, flex, grid, animation, transition, hover, responsive, font-size, icon, svg`
+}
+
+export function buildOracleSection(agents: AvailableAgent[]): string {
+  const oracleAgent = agents.find((a) => a.name === "oracle")
+  if (!oracleAgent) return ""
+
+  const useWhen = oracleAgent.metadata.useWhen || []
+  const avoidWhen = oracleAgent.metadata.avoidWhen || []
+
+  return `<Oracle_Usage>
+## Oracle — Your Senior Engineering Advisor (GPT-5.2)
+
+Oracle is an expensive, high-quality reasoning model. Use it wisely.
+
+### WHEN to Consult:
+
+| Trigger | Action |
+|---------|--------|
+${useWhen.map((w) => `| ${w} | Oracle FIRST, then implement |`).join("\n")}
+
+### WHEN NOT to Consult:
+
+${avoidWhen.map((w) => `- ${w}`).join("\n")}
+
+### Usage Pattern:
+Briefly announce "Consulting Oracle for [reason]" before invocation.
+
+**Exception**: This is the ONLY case where you announce before acting. For all other work, start immediately without status updates.
+</Oracle_Usage>`
+}
+
+export function buildHardBlocksSection(agents: AvailableAgent[]): string {
+  const frontendAgent = agents.find((a) => a.name === "frontend-ui-ux-engineer")
+
+  const blocks = [
+    "| Type error suppression (`as any`, `@ts-ignore`) | Never |",
+    "| Commit without explicit request | Never |",
+    "| Speculate about unread code | Never |",
+    "| Leave code in broken state after failures | Never |",
+  ]
+
+  if (frontendAgent) {
+    blocks.unshift(
+      "| Frontend VISUAL changes (styling, layout, animation) | Always delegate to `frontend-ui-ux-engineer` |"
+    )
+  }
+
+  return `## Hard Blocks (NEVER violate)
+
+| Constraint | No Exceptions |
+|------------|---------------|
+${blocks.join("\n")}`
+}
+
+export function buildAntiPatternsSection(agents: AvailableAgent[]): string {
+  const frontendAgent = agents.find((a) => a.name === "frontend-ui-ux-engineer")
+
+  const patterns = [
+    "| **Type Safety** | `as any`, `@ts-ignore`, `@ts-expect-error` |",
+    "| **Error Handling** | Empty catch blocks `catch(e) {}` |",
+    "| **Testing** | Deleting failing tests to \"pass\" |",
+    "| **Search** | Firing agents for single-line typos or obvious syntax errors |",
+    "| **Debugging** | Shotgun debugging, random changes |",
+  ]
+
+  if (frontendAgent) {
+    patterns.splice(
+      4,
+      0,
+      "| **Frontend** | Direct edit to visual/styling code (logic changes OK) |"
+    )
+  }
+
+  return `## Anti-Patterns (BLOCKING violations)
+
+| Category | Forbidden |
+|----------|-----------|
+${patterns.join("\n")}`
+}

src/agents/sisyphus.ts

@@ -0,0 +1,504 @@
+import type { AgentConfig } from "@opencode-ai/sdk"
+import { isGptModel } from "./types"
+import type { AvailableAgent, AvailableTool, AvailableSkill } from "./sisyphus-prompt-builder"
+import {
+  buildKeyTriggersSection,
+  buildToolSelectionTable,
+  buildExploreSection,
+  buildLibrarianSection,
+  buildDelegationTable,
+  buildFrontendSection,
+  buildOracleSection,
+  buildHardBlocksSection,
+  buildAntiPatternsSection,
+  categorizeTools,
+} from "./sisyphus-prompt-builder"
+
+const DEFAULT_MODEL = "anthropic/claude-opus-4-5"
+
+const SISYPHUS_ROLE_SECTION = `<Role>
+You are "Sisyphus" - Powerful AI Agent with orchestration capabilities from OhMyOpenCode.
+Named by [YeonGyu Kim](https://github.com/code-yeongyu).
+
+**Why Sisyphus?**: Humans roll their boulder every day. So do you. We're not so different—your code should be indistinguishable from a senior engineer's.
+
+**Identity**: SF Bay Area engineer. Work, delegate, verify, ship. No AI slop.
+
+**Core Competencies**:
+- Parsing implicit requirements from explicit requests
+- Adapting to codebase maturity (disciplined vs chaotic)
+- Delegating specialized work to the right subagents
+- Parallel execution for maximum throughput
+- Follows user instructions. NEVER START IMPLEMENTING, UNLESS USER WANTS YOU TO IMPLEMENT SOMETHING EXPLICITELY.
+  - KEEP IN MIND: YOUR TODO CREATION WOULD BE TRACKED BY HOOK([SYSTEM REMINDER - TODO CONTINUATION]), BUT IF NOT USER REQUESTED YOU TO WORK, NEVER START WORK.
+
+**Operating Mode**: You NEVER work alone when specialists are available. Frontend work → delegate. Deep research → parallel background agents (async subagents). Complex architecture → consult Oracle.
+
+</Role>`
+
+const SISYPHUS_PHASE0_STEP1_3 = `### Step 0: Check Skills FIRST (BLOCKING)
+
+**Before ANY classification or action, scan for matching skills.**
+
+\`\`\`
+IF request matches a skill trigger:
+  → INVOKE skill tool IMMEDIATELY
+  → Do NOT proceed to Step 1 until skill is invoked
+\`\`\`
+
+Skills are specialized workflows. When relevant, they handle the task better than manual orchestration.
+
+---
+
+### Step 1: Classify Request Type
+
+| Type | Signal | Action |
+|------|--------|--------|
+| **Skill Match** | Matches skill trigger phrase | **INVOKE skill FIRST** via \`skill\` tool |
+| **Trivial** | Single file, known location, direct answer | Direct tools only (UNLESS Key Trigger applies) |
+| **Explicit** | Specific file/line, clear command | Execute directly |
+| **Exploratory** | "How does X work?", "Find Y" | Fire explore (1-3) + tools in parallel |
+| **Open-ended** | "Improve", "Refactor", "Add feature" | Assess codebase first |
+| **GitHub Work** | Mentioned in issue, "look into X and create PR" | **Full cycle**: investigate → implement → verify → create PR (see GitHub Workflow section) |
+| **Ambiguous** | Unclear scope, multiple interpretations | Ask ONE clarifying question |
+
+### Step 2: Check for Ambiguity
+
+| Situation | Action |
+|-----------|--------|
+| Single valid interpretation | Proceed |
+| Multiple interpretations, similar effort | Proceed with reasonable default, note assumption |
+| Multiple interpretations, 2x+ effort difference | **MUST ask** |
+| Missing critical info (file, error, context) | **MUST ask** |
+| User's design seems flawed or suboptimal | **MUST raise concern** before implementing |
+
+### Step 3: Validate Before Acting
+- Do I have any implicit assumptions that might affect the outcome?
+- Is the search scope clear?
+- What tools / agents can be used to satisfy the user's request, considering the intent and scope?
+  - What are the list of tools / agents do I have?
+  - What tools / agents can I leverage for what tasks?
+  - Specifically, how can I leverage them like?
+    - background tasks?
+    - parallel tool calls?
+    - lsp tools?
+
+
+### When to Challenge the User
+If you observe:
+- A design decision that will cause obvious problems
+- An approach that contradicts established patterns in the codebase
+- A request that seems to misunderstand how the existing code works
+
+Then: Raise your concern concisely. Propose an alternative. Ask if they want to proceed anyway.
+
+\`\`\`
+I notice [observation]. This might cause [problem] because [reason].
+Alternative: [your suggestion].
+Should I proceed with your original request, or try the alternative?
+\`\`\``
+
+const SISYPHUS_PHASE1 = `## Phase 1 - Codebase Assessment (for Open-ended tasks)
+
+Before following existing patterns, assess whether they're worth following.
+
+### Quick Assessment:
+1. Check config files: linter, formatter, type config
+2. Sample 2-3 similar files for consistency
+3. Note project age signals (dependencies, patterns)
+
+### State Classification:
+
+| State | Signals | Your Behavior |
+|-------|---------|---------------|
+| **Disciplined** | Consistent patterns, configs present, tests exist | Follow existing style strictly |
+| **Transitional** | Mixed patterns, some structure | Ask: "I see X and Y patterns. Which to follow?" |
+| **Legacy/Chaotic** | No consistency, outdated patterns | Propose: "No clear conventions. I suggest [X]. OK?" |
+| **Greenfield** | New/empty project | Apply modern best practices |
+
+IMPORTANT: If codebase appears undisciplined, verify before assuming:
+- Different patterns may serve different purposes (intentional)
+- Migration might be in progress
+- You might be looking at the wrong reference files`
+
+const SISYPHUS_PARALLEL_EXECUTION = `### Parallel Execution (DEFAULT behavior)
+
+**Explore/Librarian = Grep, not consultants.
+
+\`\`\`typescript
+// CORRECT: Always background, always parallel
+// Contextual Grep (internal)
+background_task(agent="explore", prompt="Find auth implementations in our codebase...")
+background_task(agent="explore", prompt="Find error handling patterns here...")
+// Reference Grep (external)
+background_task(agent="librarian", prompt="Find JWT best practices in official docs...")
+background_task(agent="librarian", prompt="Find how production apps handle auth in Express...")
+// Continue working immediately. Collect with background_output when needed.
+
+// WRONG: Sequential or blocking
+result = task(...)  // Never wait synchronously for explore/librarian
+\`\`\`
+
+### Background Result Collection:
+1. Launch parallel agents → receive task_ids
+2. Continue immediate work
+3. When results needed: \`background_output(task_id="...")\`
+4. BEFORE final answer: \`background_cancel(all=true)\`
+
+### Search Stop Conditions
+
+STOP searching when:
+- You have enough context to proceed confidently
+- Same information appearing across multiple sources
+- 2 search iterations yielded no new useful data
+- Direct answer found
+
+**DO NOT over-explore. Time is precious.**`
+
+const SISYPHUS_PHASE2B_PRE_IMPLEMENTATION = `## Phase 2B - Implementation
+
+### Pre-Implementation:
+1. If task has 2+ steps → Create todo list IMMEDIATELY, IN SUPER DETAIL. No announcements—just create it.
+2. Mark current task \`in_progress\` before starting
+3. Mark \`completed\` as soon as done (don't batch) - OBSESSIVELY TRACK YOUR WORK USING TODO TOOLS`
+
+const SISYPHUS_DELEGATION_PROMPT_STRUCTURE = `### Delegation Prompt Structure (MANDATORY - ALL 7 sections):
+
+When delegating, your prompt MUST include:
+
+\`\`\`
+1. TASK: Atomic, specific goal (one action per delegation)
+2. EXPECTED OUTCOME: Concrete deliverables with success criteria
+3. REQUIRED SKILLS: Which skill to invoke
+4. REQUIRED TOOLS: Explicit tool whitelist (prevents tool sprawl)
+5. MUST DO: Exhaustive requirements - leave NOTHING implicit
+6. MUST NOT DO: Forbidden actions - anticipate and block rogue behavior
+7. CONTEXT: File paths, existing patterns, constraints
+\`\`\`
+
+AFTER THE WORK YOU DELEGATED SEEMS DONE, ALWAYS VERIFY THE RESULTS AS FOLLOWING:
+- DOES IT WORK AS EXPECTED?
+- DOES IT FOLLOWED THE EXISTING CODEBASE PATTERN?
+- EXPECTED RESULT CAME OUT?
+- DID THE AGENT FOLLOWED "MUST DO" AND "MUST NOT DO" REQUIREMENTS?
+
+**Vague prompts = rejected. Be exhaustive.**`
+
+const SISYPHUS_GITHUB_WORKFLOW = `### GitHub Workflow (CRITICAL - When mentioned in issues/PRs):
+
+When you're mentioned in GitHub issues or asked to "look into" something and "create PR":
+
+**This is NOT just investigation. This is a COMPLETE WORK CYCLE.**
+
+#### Pattern Recognition:
+- "@sisyphus look into X"
+- "look into X and create PR"
+- "investigate Y and make PR"
+- Mentioned in issue comments
+
+#### Required Workflow (NON-NEGOTIABLE):
+1. **Investigate**: Understand the problem thoroughly
+   - Read issue/PR context completely
+   - Search codebase for relevant code
+   - Identify root cause and scope
+2. **Implement**: Make the necessary changes
+   - Follow existing codebase patterns
+   - Add tests if applicable
+   - Verify with lsp_diagnostics
+3. **Verify**: Ensure everything works
+   - Run build if exists
+   - Run tests if exists
+   - Check for regressions
+4. **Create PR**: Complete the cycle
+   - Use \`gh pr create\` with meaningful title and description
+   - Reference the original issue number
+   - Summarize what was changed and why
+
+**EMPHASIS**: "Look into" does NOT mean "just investigate and report back." 
+It means "investigate, understand, implement a solution, and create a PR."
+
+**If the user says "look into X and create PR", they expect a PR, not just analysis.**`
+
+const SISYPHUS_CODE_CHANGES = `### Code Changes:
+- Match existing patterns (if codebase is disciplined)
+- Propose approach first (if codebase is chaotic)
+- Never suppress type errors with \`as any\`, \`@ts-ignore\`, \`@ts-expect-error\`
+- Never commit unless explicitly requested
+- When refactoring, use various tools to ensure safe refactorings
+- **Bugfix Rule**: Fix minimally. NEVER refactor while fixing.
+
+### Verification:
+
+Run \`lsp_diagnostics\` on changed files at:
+- End of a logical task unit
+- Before marking a todo item complete
+- Before reporting completion to user
+
+If project has build/test commands, run them at task completion.
+
+### Evidence Requirements (task NOT complete without these):
+
+| Action | Required Evidence |
+|--------|-------------------|
+| File edit | \`lsp_diagnostics\` clean on changed files |
+| Build command | Exit code 0 |
+| Test run | Pass (or explicit note of pre-existing failures) |
+| Delegation | Agent result received and verified |
+
+**NO EVIDENCE = NOT COMPLETE.**`
+
+const SISYPHUS_PHASE2C = `## Phase 2C - Failure Recovery
+
+### When Fixes Fail:
+
+1. Fix root causes, not symptoms
+2. Re-verify after EVERY fix attempt
+3. Never shotgun debug (random changes hoping something works)
+
+### After 3 Consecutive Failures:
+
+1. **STOP** all further edits immediately
+2. **REVERT** to last known working state (git checkout / undo edits)
+3. **DOCUMENT** what was attempted and what failed
+4. **CONSULT** Oracle with full failure context
+5. If Oracle cannot resolve → **ASK USER** before proceeding
+
+**Never**: Leave code in broken state, continue hoping it'll work, delete failing tests to "pass"`
+
+const SISYPHUS_PHASE3 = `## Phase 3 - Completion
+
+A task is complete when:
+- [ ] All planned todo items marked done
+- [ ] Diagnostics clean on changed files
+- [ ] Build passes (if applicable)
+- [ ] User's original request fully addressed
+
+If verification fails:
+1. Fix issues caused by your changes
+2. Do NOT fix pre-existing issues unless asked
+3. Report: "Done. Note: found N pre-existing lint errors unrelated to my changes."
+
+### Before Delivering Final Answer:
+- Cancel ALL running background tasks: \`background_cancel(all=true)\`
+- This conserves resources and ensures clean workflow completion`
+
+const SISYPHUS_TASK_MANAGEMENT = `<Task_Management>
+## Todo Management (CRITICAL)
+
+**DEFAULT BEHAVIOR**: Create todos BEFORE starting any non-trivial task. This is your PRIMARY coordination mechanism.
+
+### When to Create Todos (MANDATORY)
+
+| Trigger | Action |
+|---------|--------|
+| Multi-step task (2+ steps) | ALWAYS create todos first |
+| Uncertain scope | ALWAYS (todos clarify thinking) |
+| User request with multiple items | ALWAYS |
+| Complex single task | Create todos to break down |
+
+### Workflow (NON-NEGOTIABLE)
+
+1. **IMMEDIATELY on receiving request**: \`todowrite\` to plan atomic steps.
+  - ONLY ADD TODOS TO IMPLEMENT SOMETHING, ONLY WHEN USER WANTS YOU TO IMPLEMENT SOMETHING.
+2. **Before starting each step**: Mark \`in_progress\` (only ONE at a time)
+3. **After completing each step**: Mark \`completed\` IMMEDIATELY (NEVER batch)
+4. **If scope changes**: Update todos before proceeding
+
+### Why This Is Non-Negotiable
+
+- **User visibility**: User sees real-time progress, not a black box
+- **Prevents drift**: Todos anchor you to the actual request
+- **Recovery**: If interrupted, todos enable seamless continuation
+- **Accountability**: Each todo = explicit commitment
+
+### Anti-Patterns (BLOCKING)
+
+| Violation | Why It's Bad |
+|-----------|--------------|
+| Skipping todos on multi-step tasks | User has no visibility, steps get forgotten |
+| Batch-completing multiple todos | Defeats real-time tracking purpose |
+| Proceeding without marking in_progress | No indication of what you're working on |
+| Finishing without completing todos | Task appears incomplete to user |
+
+**FAILURE TO USE TODOS ON NON-TRIVIAL TASKS = INCOMPLETE WORK.**
+
+### Clarification Protocol (when asking):
+
+\`\`\`
+I want to make sure I understand correctly.
+
+**What I understood**: [Your interpretation]
+**What I'm unsure about**: [Specific ambiguity]
+**Options I see**:
+1. [Option A] - [effort/implications]
+2. [Option B] - [effort/implications]
+
+**My recommendation**: [suggestion with reasoning]
+
+Should I proceed with [recommendation], or would you prefer differently?
+\`\`\`
+</Task_Management>`
+
+const SISYPHUS_TONE_AND_STYLE = `<Tone_and_Style>
+## Communication Style
+
+### Be Concise
+- Start work immediately. No acknowledgments ("I'm on it", "Let me...", "I'll start...") 
+- Answer directly without preamble
+- Don't summarize what you did unless asked
+- Don't explain your code unless asked
+- One word answers are acceptable when appropriate
+
+### No Flattery
+Never start responses with:
+- "Great question!"
+- "That's a really good idea!"
+- "Excellent choice!"
+- Any praise of the user's input
+
+Just respond directly to the substance.
+
+### No Status Updates
+Never start responses with casual acknowledgments:
+- "Hey I'm on it..."
+- "I'm working on this..."
+- "Let me start by..."
+- "I'll get to work on..."
+- "I'm going to..."
+
+Just start working. Use todos for progress tracking—that's what they're for.
+
+### When User is Wrong
+If the user's approach seems problematic:
+- Don't blindly implement it
+- Don't lecture or be preachy
+- Concisely state your concern and alternative
+- Ask if they want to proceed anyway
+
+### Match User's Style
+- If user is terse, be terse
+- If user wants detail, provide detail
+- Adapt to their communication preference
+</Tone_and_Style>`
+
+const SISYPHUS_SOFT_GUIDELINES = `## Soft Guidelines
+
+- Prefer existing libraries over new dependencies
+- Prefer small, focused changes over large refactors
+- When uncertain about scope, ask
+</Constraints>
+
+`
+
+function buildDynamicSisyphusPrompt(
+  availableAgents: AvailableAgent[],
+  availableTools: AvailableTool[] = [],
+  availableSkills: AvailableSkill[] = []
+): string {
+  const keyTriggers = buildKeyTriggersSection(availableAgents, availableSkills)
+  const toolSelection = buildToolSelectionTable(availableAgents, availableTools, availableSkills)
+  const exploreSection = buildExploreSection(availableAgents)
+  const librarianSection = buildLibrarianSection(availableAgents)
+  const frontendSection = buildFrontendSection(availableAgents)
+  const delegationTable = buildDelegationTable(availableAgents)
+  const oracleSection = buildOracleSection(availableAgents)
+  const hardBlocks = buildHardBlocksSection(availableAgents)
+  const antiPatterns = buildAntiPatternsSection(availableAgents)
+
+  const sections = [
+    SISYPHUS_ROLE_SECTION,
+    "<Behavior_Instructions>",
+    "",
+    "## Phase 0 - Intent Gate (EVERY message)",
+    "",
+    keyTriggers,
+    "",
+    SISYPHUS_PHASE0_STEP1_3,
+    "",
+    "---",
+    "",
+    SISYPHUS_PHASE1,
+    "",
+    "---",
+    "",
+    "## Phase 2A - Exploration & Research",
+    "",
+    toolSelection,
+    "",
+    exploreSection,
+    "",
+    librarianSection,
+    "",
+    SISYPHUS_PARALLEL_EXECUTION,
+    "",
+    "---",
+    "",
+    SISYPHUS_PHASE2B_PRE_IMPLEMENTATION,
+    "",
+    frontendSection,
+    "",
+    delegationTable,
+    "",
+    SISYPHUS_DELEGATION_PROMPT_STRUCTURE,
+    "",
+    SISYPHUS_GITHUB_WORKFLOW,
+    "",
+    SISYPHUS_CODE_CHANGES,
+    "",
+    "---",
+    "",
+    SISYPHUS_PHASE2C,
+    "",
+    "---",
+    "",
+    SISYPHUS_PHASE3,
+    "",
+    "</Behavior_Instructions>",
+    "",
+    oracleSection,
+    "",
+    SISYPHUS_TASK_MANAGEMENT,
+    "",
+    SISYPHUS_TONE_AND_STYLE,
+    "",
+    "<Constraints>",
+    hardBlocks,
+    "",
+    antiPatterns,
+    "",
+    SISYPHUS_SOFT_GUIDELINES,
+  ]
+
+  return sections.filter((s) => s !== "").join("\n")
+}
+
+export function createSisyphusAgent(
+  model: string = DEFAULT_MODEL,
+  availableAgents?: AvailableAgent[],
+  availableToolNames?: string[],
+  availableSkills?: AvailableSkill[]
+): AgentConfig {
+  const tools = availableToolNames ? categorizeTools(availableToolNames) : []
+  const skills = availableSkills ?? []
+  const prompt = availableAgents
+    ? buildDynamicSisyphusPrompt(availableAgents, tools, skills)
+    : buildDynamicSisyphusPrompt([], tools, skills)
+
+  const base = {
+    description:
+      "Sisyphus - Powerful AI orchestrator from OhMyOpenCode. Plans obsessively with todos, assesses search complexity before exploration, delegates strategically to specialized agents. Uses explore for internal code (parallel-friendly), librarian only for external docs, and always delegates UI work to frontend engineer.",
+    mode: "primary" as const,
+    model,
+    maxTokens: 64000,
+    prompt,
+    color: "#00CED1",
+  }
+
+  if (isGptModel(model)) {
+    return { ...base, reasoningEffort: "medium" }
+  }
+
+  return { ...base, thinking: { type: "enabled", budgetTokens: 32000 } }
+}
+
+export const sisyphusAgent = createSisyphusAgent()

src/agents/types.ts

@@ -1,12 +1,78 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
 
-export type AgentName =
+export type AgentFactory = (model?: string) => AgentConfig
+
+/**
+ * Agent category for grouping in Sisyphus prompt sections
+ */
+export type AgentCategory = "exploration" | "specialist" | "advisor" | "utility"
+
+/**
+ * Cost classification for Tool Selection table
+ */
+export type AgentCost = "FREE" | "CHEAP" | "EXPENSIVE"
+
+/**
+ * Delegation trigger for Sisyphus prompt's Delegation Table
+ */
+export interface DelegationTrigger {
+  /** Domain of work (e.g., "Frontend UI/UX") */
+  domain: string
+  /** When to delegate (e.g., "Visual changes only...") */
+  trigger: string
+}
+
+/**
+ * Metadata for generating Sisyphus prompt sections dynamically
+ * This allows adding/removing agents without manually updating the Sisyphus prompt
+ */
+export interface AgentPromptMetadata {
+  /** Category for grouping in prompt sections */
+  category: AgentCategory
+
+  /** Cost classification for Tool Selection table */
+  cost: AgentCost
+
+  /** Domain triggers for Delegation Table */
+  triggers: DelegationTrigger[]
+
+  /** When to use this agent (for detailed sections) */
+  useWhen?: string[]
+
+  /** When NOT to use this agent */
+  avoidWhen?: string[]
+
+  /** Optional dedicated prompt section (markdown) - for agents like Oracle that have special sections */
+  dedicatedSection?: string
+
+  /** Nickname/alias used in prompt (e.g., "Oracle" instead of "oracle") */
+  promptAlias?: string
+
+  /** Key triggers that should appear in Phase 0 (e.g., "External library mentioned → fire librarian") */
+  keyTrigger?: string
+}
+
+export function isGptModel(model: string): boolean {
+  return model.startsWith("openai/") || model.startsWith("github-copilot/gpt-")
+}
+
+export type BuiltinAgentName =
+  | "Sisyphus"
   | "oracle"
   | "librarian"
   | "explore"
   | "frontend-ui-ux-engineer"
   | "document-writer"
+  | "multimodal-looker"
 
-export type AgentOverrideConfig = Partial<AgentConfig>
+export type OverridableAgentName =
+  | "build"
+  | BuiltinAgentName
 
-export type AgentOverrides = Partial<Record<AgentName, AgentOverrideConfig>>
+export type AgentName = BuiltinAgentName
+
+export type AgentOverrideConfig = Partial<AgentConfig> & {
+  prompt_append?: string
+}
+
+export type AgentOverrides = Partial<Record<OverridableAgentName, AgentOverrideConfig>>

src/agents/utils.test.ts

@@ -0,0 +1,87 @@
+import { describe, test, expect } from "bun:test"
+import { createBuiltinAgents } from "./utils"
+
+describe("createBuiltinAgents with model overrides", () => {
+  test("Sisyphus with default model has thinking config", () => {
+    // #given - no overrides
+
+    // #when
+    const agents = createBuiltinAgents()
+
+    // #then
+    expect(agents.Sisyphus.model).toBe("anthropic/claude-opus-4-5")
+    expect(agents.Sisyphus.thinking).toEqual({ type: "enabled", budgetTokens: 32000 })
+    expect(agents.Sisyphus.reasoningEffort).toBeUndefined()
+  })
+
+  test("Sisyphus with GPT model override has reasoningEffort, no thinking", () => {
+    // #given
+    const overrides = {
+      Sisyphus: { model: "github-copilot/gpt-5.2" },
+    }
+
+    // #when
+    const agents = createBuiltinAgents([], overrides)
+
+    // #then
+    expect(agents.Sisyphus.model).toBe("github-copilot/gpt-5.2")
+    expect(agents.Sisyphus.reasoningEffort).toBe("medium")
+    expect(agents.Sisyphus.thinking).toBeUndefined()
+  })
+
+  test("Sisyphus with systemDefaultModel GPT has reasoningEffort, no thinking", () => {
+    // #given
+    const systemDefaultModel = "openai/gpt-5.2"
+
+    // #when
+    const agents = createBuiltinAgents([], {}, undefined, systemDefaultModel)
+
+    // #then
+    expect(agents.Sisyphus.model).toBe("openai/gpt-5.2")
+    expect(agents.Sisyphus.reasoningEffort).toBe("medium")
+    expect(agents.Sisyphus.thinking).toBeUndefined()
+  })
+
+  test("Oracle with default model has reasoningEffort", () => {
+    // #given - no overrides
+
+    // #when
+    const agents = createBuiltinAgents()
+
+    // #then
+    expect(agents.oracle.model).toBe("openai/gpt-5.2")
+    expect(agents.oracle.reasoningEffort).toBe("medium")
+    expect(agents.oracle.textVerbosity).toBe("high")
+    expect(agents.oracle.thinking).toBeUndefined()
+  })
+
+  test("Oracle with Claude model override has thinking, no reasoningEffort", () => {
+    // #given
+    const overrides = {
+      oracle: { model: "anthropic/claude-sonnet-4" },
+    }
+
+    // #when
+    const agents = createBuiltinAgents([], overrides)
+
+    // #then
+    expect(agents.oracle.model).toBe("anthropic/claude-sonnet-4")
+    expect(agents.oracle.thinking).toEqual({ type: "enabled", budgetTokens: 32000 })
+    expect(agents.oracle.reasoningEffort).toBeUndefined()
+    expect(agents.oracle.textVerbosity).toBeUndefined()
+  })
+
+  test("non-model overrides are still applied after factory rebuild", () => {
+    // #given
+    const overrides = {
+      Sisyphus: { model: "github-copilot/gpt-5.2", temperature: 0.5 },
+    }
+
+    // #when
+    const agents = createBuiltinAgents([], overrides)
+
+    // #then
+    expect(agents.Sisyphus.model).toBe("github-copilot/gpt-5.2")
+    expect(agents.Sisyphus.temperature).toBe(0.5)
+  })
+})

src/agents/utils.ts

@@ -1,46 +1,145 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
-import type { AgentName, AgentOverrideConfig, AgentOverrides } from "./types"
-import { oracleAgent } from "./oracle"
-import { librarianAgent } from "./librarian"
-import { exploreAgent } from "./explore"
-import { frontendUiUxEngineerAgent } from "./frontend-ui-ux-engineer"
-import { documentWriterAgent } from "./document-writer"
+import type { BuiltinAgentName, AgentOverrideConfig, AgentOverrides, AgentFactory, AgentPromptMetadata } from "./types"
+import { createSisyphusAgent } from "./sisyphus"
+import { createOracleAgent, ORACLE_PROMPT_METADATA } from "./oracle"
+import { createLibrarianAgent, LIBRARIAN_PROMPT_METADATA } from "./librarian"
+import { createExploreAgent, EXPLORE_PROMPT_METADATA } from "./explore"
+import { createFrontendUiUxEngineerAgent, FRONTEND_PROMPT_METADATA } from "./frontend-ui-ux-engineer"
+import { createDocumentWriterAgent, DOCUMENT_WRITER_PROMPT_METADATA } from "./document-writer"
+import { createMultimodalLookerAgent, MULTIMODAL_LOOKER_PROMPT_METADATA } from "./multimodal-looker"
+import type { AvailableAgent } from "./sisyphus-prompt-builder"
 import { deepMerge } from "../shared"
 
-const allBuiltinAgents: Record<AgentName, AgentConfig> = {
-  oracle: oracleAgent,
-  librarian: librarianAgent,
-  explore: exploreAgent,
-  "frontend-ui-ux-engineer": frontendUiUxEngineerAgent,
-  "document-writer": documentWriterAgent,
+type AgentSource = AgentFactory | AgentConfig
+
+const agentSources: Record<BuiltinAgentName, AgentSource> = {
+  Sisyphus: createSisyphusAgent,
+  oracle: createOracleAgent,
+  librarian: createLibrarianAgent,
+  explore: createExploreAgent,
+  "frontend-ui-ux-engineer": createFrontendUiUxEngineerAgent,
+  "document-writer": createDocumentWriterAgent,
+  "multimodal-looker": createMultimodalLookerAgent,
+}
+
+/**
+ * Metadata for each agent, used to build Sisyphus's dynamic prompt sections
+ * (Delegation Table, Tool Selection, Key Triggers, etc.)
+ */
+const agentMetadata: Partial<Record<BuiltinAgentName, AgentPromptMetadata>> = {
+  oracle: ORACLE_PROMPT_METADATA,
+  librarian: LIBRARIAN_PROMPT_METADATA,
+  explore: EXPLORE_PROMPT_METADATA,
+  "frontend-ui-ux-engineer": FRONTEND_PROMPT_METADATA,
+  "document-writer": DOCUMENT_WRITER_PROMPT_METADATA,
+  "multimodal-looker": MULTIMODAL_LOOKER_PROMPT_METADATA,
+}
+
+function isFactory(source: AgentSource): source is AgentFactory {
+  return typeof source === "function"
+}
+
+function buildAgent(source: AgentSource, model?: string): AgentConfig {
+  return isFactory(source) ? source(model) : source
+}
+
+/**
+ * Creates OmO-specific environment context (time, timezone, locale).
+ * Note: Working directory, platform, and date are already provided by OpenCode's system.ts,
+ * so we only include fields that OpenCode doesn't provide to avoid duplication.
+ * See: https://github.com/code-yeongyu/oh-my-opencode/issues/379
+ */
+export function createEnvContext(): string {
+  const now = new Date()
+  const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone
+  const locale = Intl.DateTimeFormat().resolvedOptions().locale
+
+  const timeStr = now.toLocaleTimeString("en-US", {
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: true,
+  })
+
+  return `
+<omo-env>
+  Current time: ${timeStr}
+  Timezone: ${timezone}
+  Locale: ${locale}
+</omo-env>`
 }
 
 function mergeAgentConfig(
   base: AgentConfig,
   override: AgentOverrideConfig
 ): AgentConfig {
-  return deepMerge(base, override as Partial<AgentConfig>)
+  const { prompt_append, ...rest } = override
+  const merged = deepMerge(base, rest as Partial<AgentConfig>)
+
+  if (prompt_append && merged.prompt) {
+    merged.prompt = merged.prompt + "\n" + prompt_append
+  }
+
+  return merged
 }
 
 export function createBuiltinAgents(
-  disabledAgents: AgentName[] = [],
-  agentOverrides: AgentOverrides = {}
+  disabledAgents: BuiltinAgentName[] = [],
+  agentOverrides: AgentOverrides = {},
+  directory?: string,
+  systemDefaultModel?: string
 ): Record<string, AgentConfig> {
   const result: Record<string, AgentConfig> = {}
+  const availableAgents: AvailableAgent[] = []
 
-  for (const [name, config] of Object.entries(allBuiltinAgents)) {
-    const agentName = name as AgentName
+  for (const [name, source] of Object.entries(agentSources)) {
+    const agentName = name as BuiltinAgentName
 
-    if (disabledAgents.includes(agentName)) {
-      continue
-    }
+    if (agentName === "Sisyphus") continue
+    if (disabledAgents.includes(agentName)) continue
 
     const override = agentOverrides[agentName]
-    if (override) {
-      result[name] = mergeAgentConfig(config, override)
-    } else {
-      result[name] = config
+    const model = override?.model
+
+    let config = buildAgent(source, model)
+
+    if (agentName === "librarian" && directory && config.prompt) {
+      const envContext = createEnvContext()
+      config = { ...config, prompt: config.prompt + envContext }
     }
+
+    if (override) {
+      config = mergeAgentConfig(config, override)
+    }
+
+    result[name] = config
+
+    const metadata = agentMetadata[agentName]
+    if (metadata) {
+      availableAgents.push({
+        name: agentName,
+        description: config.description ?? "",
+        metadata,
+      })
+    }
+  }
+
+  if (!disabledAgents.includes("Sisyphus")) {
+    const sisyphusOverride = agentOverrides["Sisyphus"]
+    const sisyphusModel = sisyphusOverride?.model ?? systemDefaultModel
+
+    let sisyphusConfig = createSisyphusAgent(sisyphusModel, availableAgents)
+
+    if (directory && sisyphusConfig.prompt) {
+      const envContext = createEnvContext()
+      sisyphusConfig = { ...sisyphusConfig, prompt: sisyphusConfig.prompt + envContext }
+    }
+
+    if (sisyphusOverride) {
+      sisyphusConfig = mergeAgentConfig(sisyphusConfig, sisyphusOverride)
+    }
+
+    result["Sisyphus"] = sisyphusConfig
   }
 
   return result

src/auth/AGENTS.md

@@ -0,0 +1,57 @@
+# AUTH KNOWLEDGE BASE
+
+## OVERVIEW
+
+Google Antigravity OAuth for Gemini models. Token management, fetch interception, thinking block extraction.
+
+## STRUCTURE
+
+```
+auth/
+└── antigravity/
+    ├── plugin.ts         # Main export, hooks registration
+    ├── oauth.ts          # OAuth flow, token acquisition
+    ├── token.ts          # Token storage, refresh logic
+    ├── fetch.ts          # Fetch interceptor (621 lines)
+    ├── response.ts       # Response transformation (598 lines)
+    ├── thinking.ts       # Thinking block extraction (571 lines)
+    ├── thought-signature-store.ts  # Signature caching
+    ├── message-converter.ts        # Format conversion
+    ├── request.ts        # Request building
+    ├── project.ts        # Project ID management
+    ├── tools.ts          # OAuth tool registration
+    ├── constants.ts      # API endpoints, model mappings
+    └── types.ts
+```
+
+## KEY COMPONENTS
+
+| File | Purpose |
+|------|---------|
+| fetch.ts | URL rewriting, token injection, retries |
+| thinking.ts | Extract `<antThinking>` blocks |
+| response.ts | Streaming SSE parsing |
+| oauth.ts | Browser-based OAuth flow |
+| token.ts | Token persistence, expiry |
+
+## HOW IT WORKS
+
+1. **Intercept**: fetch.ts intercepts Anthropic/Google requests
+2. **Rewrite**: URLs → Antigravity proxy endpoints
+3. **Auth**: Bearer token from stored OAuth credentials
+4. **Response**: Streaming parsed, thinking blocks extracted
+5. **Transform**: Normalized for OpenCode
+
+## FEATURES
+
+- Multi-account (up to 10 Google accounts)
+- Auto-fallback on rate limit
+- Thinking blocks preserved
+- Antigravity proxy for AI Studio access
+
+## ANTI-PATTERNS
+
+- Direct API calls (use fetch interceptor)
+- Tokens in code (use token.ts storage)
+- Ignoring refresh (check expiry first)
+- Blocking on OAuth (always async)

src/auth/antigravity/fetch.ts

@@ -17,16 +17,15 @@
  * Debug logging available via ANTIGRAVITY_DEBUG=1 environment variable.
  */
 
-import { ANTIGRAVITY_ENDPOINT_FALLBACKS, ANTIGRAVITY_DEFAULT_PROJECT_ID } from "./constants"
-import { fetchProjectContext, clearProjectContextCache } from "./project"
-import { isTokenExpired, refreshAccessToken, parseStoredToken, formatTokenForStorage } from "./token"
+import { ANTIGRAVITY_ENDPOINT_FALLBACKS } from "./constants"
+import { fetchProjectContext, clearProjectContextCache, invalidateProjectContextByRefreshToken } from "./project"
+import { isTokenExpired, refreshAccessToken, parseStoredToken, formatTokenForStorage, AntigravityTokenRefreshError } from "./token"
 import { transformRequest } from "./request"
 import { convertRequestBody, hasOpenAIMessages } from "./message-converter"
 import {
   transformResponse,
   transformStreamingResponse,
   isStreamingResponse,
-  extractSignatureFromSsePayload,
 } from "./response"
 import { normalizeToolsForGemini, type OpenAITool } from "./tools"
 import { extractThinkingBlocks, shouldIncludeThinking, transformResponseThinking } from "./thinking"
@@ -110,9 +109,11 @@ interface AttemptFetchOptions {
   thoughtSignature?: string
 }
 
+type AttemptFetchResult = Response | null | "pass-through" | "needs-refresh"
+
 async function attemptFetch(
   options: AttemptFetchOptions
-): Promise<Response | null | "pass-through"> {
+): Promise<AttemptFetchResult> {
   const { endpoint, url, init, accessToken, projectId, sessionId, modelName, thoughtSignature } =
     options
   debugLog(`Trying endpoint: ${endpoint}`)
@@ -183,6 +184,11 @@ async function attemptFetch(
         `[RESP] status=${response.status} content-type=${response.headers.get("content-type") ?? ""} url=${response.url}`
       )
 
+      if (response.status === 401) {
+        debugLog(`[401] Unauthorized response detected, signaling token refresh needed`)
+        return "needs-refresh"
+      }
+
       if (response.status === 403) {
         try {
           const text = await response.clone().text()
@@ -384,7 +390,6 @@ export function createAntigravityFetch(
       try {
         const newTokens = await refreshAccessToken(refreshParts.refreshToken, clientId, clientSecret)
 
-        // Update cached tokens
         cachedTokens = {
           type: "antigravity",
           access_token: newTokens.access_token,
@@ -393,10 +398,8 @@ export function createAntigravityFetch(
           timestamp: Date.now(),
         }
 
-        // Clear project context cache on token refresh
         clearProjectContextCache()
 
-        // Format and save new tokens
         const formattedRefresh = formatTokenForStorage(
           newTokens.refresh_token,
           refreshParts.projectId || "",
@@ -411,6 +414,16 @@ export function createAntigravityFetch(
 
         debugLog("Token refreshed successfully")
       } catch (error) {
+        if (error instanceof AntigravityTokenRefreshError) {
+          if (error.isInvalidGrant) {
+            debugLog(`[REFRESH] Token revoked (invalid_grant), clearing caches`)
+            invalidateProjectContextByRefreshToken(refreshParts.refreshToken)
+            clearProjectContextCache()
+          }
+          throw new Error(
+            `Antigravity: Token refresh failed: ${error.description || error.message}${error.code ? ` (${error.code})` : ""}`
+          )
+        }
         throw new Error(
           `Antigravity: Token refresh failed: ${error instanceof Error ? error.message : "Unknown error"}`
         )
@@ -448,59 +461,157 @@ export function createAntigravityFetch(
     const thoughtSignature = getThoughtSignature(fetchInstanceId)
     debugLog(`[TSIG][GET] sessionId=${sessionId}, signature=${thoughtSignature ? thoughtSignature.substring(0, 20) + "..." : "none"}`)
 
-    for (let i = 0; i < maxEndpoints; i++) {
-      const endpoint = ANTIGRAVITY_ENDPOINT_FALLBACKS[i]
+    let hasRefreshedFor401 = false
 
-      const response = await attemptFetch({
-        endpoint,
-        url,
-        init,
-        accessToken: cachedTokens.access_token,
-        projectId,
-        sessionId,
-        modelName,
-        thoughtSignature,
-      })
+    const executeWithEndpoints = async (): Promise<Response> => {
+      for (let i = 0; i < maxEndpoints; i++) {
+        const endpoint = ANTIGRAVITY_ENDPOINT_FALLBACKS[i]
 
-      if (response === "pass-through") {
-        debugLog("Non-string body detected, passing through with auth headers")
-        const headersWithAuth = {
-          ...init.headers,
-          Authorization: `Bearer ${cachedTokens.access_token}`,
+        const response = await attemptFetch({
+          endpoint,
+          url,
+          init,
+          accessToken: cachedTokens!.access_token,
+          projectId,
+          sessionId,
+          modelName,
+          thoughtSignature,
+        })
+
+        if (response === "pass-through") {
+          debugLog("Non-string body detected, passing through with auth headers")
+          const headersWithAuth = {
+            ...init.headers,
+            Authorization: `Bearer ${cachedTokens!.access_token}`,
+          }
+          return fetch(url, { ...init, headers: headersWithAuth })
+        }
+
+        if (response === "needs-refresh") {
+          if (hasRefreshedFor401) {
+            debugLog("[401] Already refreshed once, returning unauthorized error")
+            return new Response(
+              JSON.stringify({
+                error: {
+                  message: "Authentication failed after token refresh",
+                  type: "unauthorized",
+                  code: "token_refresh_failed",
+                },
+              }),
+              {
+                status: 401,
+                statusText: "Unauthorized",
+                headers: { "Content-Type": "application/json" },
+              }
+            )
+          }
+
+          debugLog("[401] Refreshing token and retrying...")
+          hasRefreshedFor401 = true
+
+          try {
+            const newTokens = await refreshAccessToken(
+              refreshParts.refreshToken,
+              clientId,
+              clientSecret
+            )
+
+            cachedTokens = {
+              type: "antigravity",
+              access_token: newTokens.access_token,
+              refresh_token: newTokens.refresh_token,
+              expires_in: newTokens.expires_in,
+              timestamp: Date.now(),
+            }
+
+            clearProjectContextCache()
+
+            const formattedRefresh = formatTokenForStorage(
+              newTokens.refresh_token,
+              refreshParts.projectId || "",
+              refreshParts.managedProjectId
+            )
+
+            await client.set(providerId, {
+              access: newTokens.access_token,
+              refresh: formattedRefresh,
+              expires: Date.now() + newTokens.expires_in * 1000,
+            })
+
+            debugLog("[401] Token refreshed, retrying request...")
+            return executeWithEndpoints()
+          } catch (refreshError) {
+            if (refreshError instanceof AntigravityTokenRefreshError) {
+              if (refreshError.isInvalidGrant) {
+                debugLog(`[401] Token revoked (invalid_grant), clearing caches`)
+                invalidateProjectContextByRefreshToken(refreshParts.refreshToken)
+                clearProjectContextCache()
+              }
+              debugLog(`[401] Token refresh failed: ${refreshError.description || refreshError.message}`)
+              return new Response(
+                JSON.stringify({
+                  error: {
+                    message: refreshError.description || refreshError.message,
+                    type: refreshError.isInvalidGrant ? "token_revoked" : "unauthorized",
+                    code: refreshError.code || "token_refresh_failed",
+                  },
+                }),
+                {
+                  status: 401,
+                  statusText: "Unauthorized",
+                  headers: { "Content-Type": "application/json" },
+                }
+              )
+            }
+            debugLog(`[401] Token refresh failed: ${refreshError instanceof Error ? refreshError.message : "Unknown error"}`)
+            return new Response(
+              JSON.stringify({
+                error: {
+                  message: refreshError instanceof Error ? refreshError.message : "Unknown error",
+                  type: "unauthorized",
+                  code: "token_refresh_failed",
+                },
+              }),
+              {
+                status: 401,
+                statusText: "Unauthorized",
+                headers: { "Content-Type": "application/json" },
+              }
+            )
+          }
+        }
+
+        if (response) {
+          debugLog(`Success with endpoint: ${endpoint}`)
+          const transformedResponse = await transformResponseWithThinking(
+            response,
+            modelName || "",
+            fetchInstanceId
+          )
+          return transformedResponse
         }
-        return fetch(url, { ...init, headers: headersWithAuth })
       }
 
-      if (response) {
-        debugLog(`Success with endpoint: ${endpoint}`)
-        const transformedResponse = await transformResponseWithThinking(
-          response,
-          modelName || "",
-          fetchInstanceId
-        )
-        return transformedResponse
-      }
+      const errorMessage = `All Antigravity endpoints failed after ${maxEndpoints} attempts`
+      debugLog(errorMessage)
+
+      return new Response(
+        JSON.stringify({
+          error: {
+            message: errorMessage,
+            type: "endpoint_failure",
+            code: "all_endpoints_failed",
+          },
+        }),
+        {
+          status: 503,
+          statusText: "Service Unavailable",
+          headers: { "Content-Type": "application/json" },
+        }
+      )
     }
 
-    // All endpoints failed
-    const errorMessage = `All Antigravity endpoints failed after ${maxEndpoints} attempts`
-    debugLog(errorMessage)
-
-    // Return error response
-    return new Response(
-      JSON.stringify({
-        error: {
-          message: errorMessage,
-          type: "endpoint_failure",
-          code: "all_endpoints_failed",
-        },
-      }),
-      {
-        status: 503,
-        statusText: "Service Unavailable",
-        headers: { "Content-Type": "application/json" },
-      }
-    )
+    return executeWithEndpoints()
   }
 }
 

src/auth/antigravity/project.ts

@@ -1,56 +1,45 @@
 /**
  * Antigravity project context management.
  * Handles fetching GCP project ID via Google's loadCodeAssist API.
+ * For FREE tier users, onboards via onboardUser API to get server-assigned managed project ID.
+ * Reference: https://github.com/shekohex/opencode-google-antigravity-auth
  */
 
 import {
-  ANTIGRAVITY_DEFAULT_PROJECT_ID,
   ANTIGRAVITY_ENDPOINT_FALLBACKS,
   ANTIGRAVITY_API_VERSION,
   ANTIGRAVITY_HEADERS,
+  ANTIGRAVITY_DEFAULT_PROJECT_ID,
 } from "./constants"
 import type {
   AntigravityProjectContext,
   AntigravityLoadCodeAssistResponse,
+  AntigravityOnboardUserPayload,
+  AntigravityUserTier,
 } from "./types"
 
-/**
- * In-memory cache for project context per access token.
- * Prevents redundant API calls for the same token.
- */
 const projectContextCache = new Map<string, AntigravityProjectContext>()
 
-/**
- * Client metadata for loadCodeAssist API request.
- * Matches cliproxyapi implementation.
- */
+function debugLog(message: string): void {
+  if (process.env.ANTIGRAVITY_DEBUG === "1") {
+    console.log(`[antigravity-project] ${message}`)
+  }
+}
+
 const CODE_ASSIST_METADATA = {
   ideType: "IDE_UNSPECIFIED",
   platform: "PLATFORM_UNSPECIFIED",
   pluginType: "GEMINI",
 } as const
 
-/**
- * Extracts the project ID from a cloudaicompanionProject field.
- * Handles both string and object formats.
- *
- * @param project - The cloudaicompanionProject value from API response
- * @returns Extracted project ID string, or undefined if not found
- */
 function extractProjectId(
   project: string | { id: string } | undefined
 ): string | undefined {
-  if (!project) {
-    return undefined
-  }
-
-  // Handle string format
+  if (!project) return undefined
   if (typeof project === "string") {
     const trimmed = project.trim()
     return trimmed || undefined
   }
-
-  // Handle object format { id: string }
   if (typeof project === "object" && "id" in project) {
     const id = project.id
     if (typeof id === "string") {
@@ -58,22 +47,89 @@ function extractProjectId(
       return trimmed || undefined
     }
   }
-
   return undefined
 }
 
-/**
- * Calls the loadCodeAssist API to get project context.
- * Tries each endpoint in the fallback list until one succeeds.
- *
- * @param accessToken - Valid OAuth access token
- * @returns API response or null if all endpoints fail
- */
+function getDefaultTierId(allowedTiers?: AntigravityUserTier[]): string | undefined {
+  if (!allowedTiers || allowedTiers.length === 0) return undefined
+  for (const tier of allowedTiers) {
+    if (tier?.isDefault) return tier.id
+  }
+  return allowedTiers[0]?.id
+}
+
+function isFreeTier(tierId: string | undefined): boolean {
+  if (!tierId) return true // No tier = assume free tier (default behavior)
+  const lower = tierId.toLowerCase()
+  return lower === "free" || lower === "free-tier" || lower.startsWith("free")
+}
+
+function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
 async function callLoadCodeAssistAPI(
-  accessToken: string
+  accessToken: string,
+  projectId?: string
 ): Promise<AntigravityLoadCodeAssistResponse | null> {
-  const requestBody = {
-    metadata: CODE_ASSIST_METADATA,
+  const metadata: Record<string, string> = { ...CODE_ASSIST_METADATA }
+  if (projectId) metadata.duetProject = projectId
+
+  const requestBody: Record<string, unknown> = { metadata }
+  if (projectId) requestBody.cloudaicompanionProject = projectId
+
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "User-Agent": ANTIGRAVITY_HEADERS["User-Agent"],
+    "X-Goog-Api-Client": ANTIGRAVITY_HEADERS["X-Goog-Api-Client"],
+    "Client-Metadata": ANTIGRAVITY_HEADERS["Client-Metadata"],
+  }
+
+  for (const baseEndpoint of ANTIGRAVITY_ENDPOINT_FALLBACKS) {
+    const url = `${baseEndpoint}/${ANTIGRAVITY_API_VERSION}:loadCodeAssist`
+    debugLog(`[loadCodeAssist] Trying: ${url}`)
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(requestBody),
+      })
+      if (!response.ok) {
+        debugLog(`[loadCodeAssist] Failed: ${response.status} ${response.statusText}`)
+        continue
+      }
+      const data = (await response.json()) as AntigravityLoadCodeAssistResponse
+      debugLog(`[loadCodeAssist] Success: ${JSON.stringify(data)}`)
+      return data
+    } catch (err) {
+      debugLog(`[loadCodeAssist] Error: ${err}`)
+      continue
+    }
+  }
+  debugLog(`[loadCodeAssist] All endpoints failed`)
+  return null
+}
+
+async function onboardManagedProject(
+  accessToken: string,
+  tierId: string,
+  projectId?: string,
+  attempts = 10,
+  delayMs = 5000
+): Promise<string | undefined> {
+  debugLog(`[onboardUser] Starting with tierId=${tierId}, projectId=${projectId || "none"}`)
+  
+  const metadata: Record<string, string> = { ...CODE_ASSIST_METADATA }
+  if (projectId) metadata.duetProject = projectId
+
+  const requestBody: Record<string, unknown> = { tierId, metadata }
+  if (!isFreeTier(tierId)) {
+    if (!projectId) {
+      debugLog(`[onboardUser] Non-FREE tier requires projectId, returning undefined`)
+      return undefined
+    }
+    requestBody.cloudaicompanionProject = projectId
   }
 
   const headers: Record<string, string> = {
@@ -84,72 +140,126 @@ async function callLoadCodeAssistAPI(
     "Client-Metadata": ANTIGRAVITY_HEADERS["Client-Metadata"],
   }
 
-  // Try each endpoint in the fallback list
-  for (const baseEndpoint of ANTIGRAVITY_ENDPOINT_FALLBACKS) {
-    const url = `${baseEndpoint}/${ANTIGRAVITY_API_VERSION}:loadCodeAssist`
+  debugLog(`[onboardUser] Request body: ${JSON.stringify(requestBody)}`)
 
-    try {
-      const response = await fetch(url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(requestBody),
-      })
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    debugLog(`[onboardUser] Attempt ${attempt + 1}/${attempts}`)
+    for (const baseEndpoint of ANTIGRAVITY_ENDPOINT_FALLBACKS) {
+      const url = `${baseEndpoint}/${ANTIGRAVITY_API_VERSION}:onboardUser`
+      debugLog(`[onboardUser] Trying: ${url}`)
+      try {
+        const response = await fetch(url, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(requestBody),
+        })
+        if (!response.ok) {
+          const errorText = await response.text().catch(() => "")
+          debugLog(`[onboardUser] Failed: ${response.status} ${response.statusText} - ${errorText}`)
+          continue
+        }
 
-      if (!response.ok) {
-        // Try next endpoint on failure
+        const payload = (await response.json()) as AntigravityOnboardUserPayload
+        debugLog(`[onboardUser] Response: ${JSON.stringify(payload)}`)
+        const managedProjectId = payload.response?.cloudaicompanionProject?.id
+        if (payload.done && managedProjectId) {
+          debugLog(`[onboardUser] Success! Got managed project ID: ${managedProjectId}`)
+          return managedProjectId
+        }
+        if (payload.done && projectId) {
+          debugLog(`[onboardUser] Done but no managed ID, using original: ${projectId}`)
+          return projectId
+        }
+        debugLog(`[onboardUser] Not done yet, payload.done=${payload.done}`)
+      } catch (err) {
+        debugLog(`[onboardUser] Error: ${err}`)
         continue
       }
-
-      const data =
-        (await response.json()) as AntigravityLoadCodeAssistResponse
-      return data
-    } catch {
-      // Network or parsing error, try next endpoint
-      continue
+    }
+    if (attempt < attempts - 1) {
+      debugLog(`[onboardUser] Waiting ${delayMs}ms before next attempt...`)
+      await wait(delayMs)
     }
   }
-
-  // All endpoints failed
-  return null
+  debugLog(`[onboardUser] All attempts exhausted, returning undefined`)
+  return undefined
 }
 
-/**
- * Fetch project context from Google's loadCodeAssist API.
- * Extracts the cloudaicompanionProject from the response.
- *
- * @param accessToken - Valid OAuth access token
- * @returns Project context with cloudaicompanionProject ID
- */
 export async function fetchProjectContext(
   accessToken: string
 ): Promise<AntigravityProjectContext> {
+  debugLog(`[fetchProjectContext] Starting...`)
+  
   const cached = projectContextCache.get(accessToken)
   if (cached) {
+    debugLog(`[fetchProjectContext] Returning cached result: ${JSON.stringify(cached)}`)
     return cached
   }
 
-  const response = await callLoadCodeAssistAPI(accessToken)
-  const projectId = response
-    ? extractProjectId(response.cloudaicompanionProject)
-    : undefined
+  const loadPayload = await callLoadCodeAssistAPI(accessToken)
 
-  const result: AntigravityProjectContext = {
-    cloudaicompanionProject: projectId || "",
+  // If loadCodeAssist returns a project ID, use it directly
+  if (loadPayload?.cloudaicompanionProject) {
+    const projectId = extractProjectId(loadPayload.cloudaicompanionProject)
+    debugLog(`[fetchProjectContext] loadCodeAssist returned project: ${projectId}`)
+    if (projectId) {
+      const result: AntigravityProjectContext = { cloudaicompanionProject: projectId }
+      projectContextCache.set(accessToken, result)
+      debugLog(`[fetchProjectContext] Using loadCodeAssist project ID: ${projectId}`)
+      return result
+    }
   }
 
-  if (projectId) {
+  // No project ID from loadCodeAssist - try with fallback project ID
+  if (!loadPayload) {
+    debugLog(`[fetchProjectContext] loadCodeAssist returned null, trying with fallback project ID`)
+    const fallbackPayload = await callLoadCodeAssistAPI(accessToken, ANTIGRAVITY_DEFAULT_PROJECT_ID)
+    const fallbackProjectId = extractProjectId(fallbackPayload?.cloudaicompanionProject)
+    if (fallbackProjectId) {
+      const result: AntigravityProjectContext = { cloudaicompanionProject: fallbackProjectId }
+      projectContextCache.set(accessToken, result)
+      debugLog(`[fetchProjectContext] Using fallback project ID: ${fallbackProjectId}`)
+      return result
+    }
+    debugLog(`[fetchProjectContext] Fallback also failed, using default: ${ANTIGRAVITY_DEFAULT_PROJECT_ID}`)
+    return { cloudaicompanionProject: ANTIGRAVITY_DEFAULT_PROJECT_ID }
+  }
+
+  const currentTierId = loadPayload.currentTier?.id
+  debugLog(`[fetchProjectContext] currentTier: ${currentTierId}, allowedTiers: ${JSON.stringify(loadPayload.allowedTiers)}`)
+  
+  if (currentTierId && !isFreeTier(currentTierId)) {
+    // PAID tier - still use fallback if no project provided
+    debugLog(`[fetchProjectContext] PAID tier detected (${currentTierId}), using fallback: ${ANTIGRAVITY_DEFAULT_PROJECT_ID}`)
+    return { cloudaicompanionProject: ANTIGRAVITY_DEFAULT_PROJECT_ID }
+  }
+
+  const defaultTierId = getDefaultTierId(loadPayload.allowedTiers)
+  const tierId = defaultTierId ?? "free-tier"
+  debugLog(`[fetchProjectContext] Resolved tierId: ${tierId}`)
+
+  if (!isFreeTier(tierId)) {
+    debugLog(`[fetchProjectContext] Non-FREE tier (${tierId}) without project, using fallback: ${ANTIGRAVITY_DEFAULT_PROJECT_ID}`)
+    return { cloudaicompanionProject: ANTIGRAVITY_DEFAULT_PROJECT_ID }
+  }
+
+  // FREE tier - onboard to get server-assigned managed project ID
+  debugLog(`[fetchProjectContext] FREE tier detected (${tierId}), calling onboardUser...`)
+  const managedProjectId = await onboardManagedProject(accessToken, tierId)
+  if (managedProjectId) {
+    const result: AntigravityProjectContext = {
+      cloudaicompanionProject: managedProjectId,
+      managedProjectId,
+    }
     projectContextCache.set(accessToken, result)
+    debugLog(`[fetchProjectContext] Got managed project ID: ${managedProjectId}`)
+    return result
   }
 
-  return result
+  debugLog(`[fetchProjectContext] Failed to get managed project ID, using fallback: ${ANTIGRAVITY_DEFAULT_PROJECT_ID}`)
+  return { cloudaicompanionProject: ANTIGRAVITY_DEFAULT_PROJECT_ID }
 }
 
-/**
- * Clear the project context cache.
- * Call this when tokens are refreshed or invalidated.
- *
- * @param accessToken - Optional specific token to clear, or clears all if not provided
- */
 export function clearProjectContextCache(accessToken?: string): void {
   if (accessToken) {
     projectContextCache.delete(accessToken)
@@ -157,3 +267,8 @@ export function clearProjectContextCache(accessToken?: string): void {
     projectContextCache.clear()
   }
 }
+
+export function invalidateProjectContextByRefreshToken(_refreshToken: string): void {
+  projectContextCache.clear()
+  debugLog(`[invalidateProjectContextByRefreshToken] Cleared all project context cache due to refresh token invalidation`)
+}

src/auth/antigravity/request.ts

@@ -5,10 +5,10 @@
  */
 
 import {
-  ANTIGRAVITY_HEADERS,
-  ANTIGRAVITY_ENDPOINT_FALLBACKS,
-  ANTIGRAVITY_API_VERSION,
-  SKIP_THOUGHT_SIGNATURE_VALIDATOR,
+    ANTIGRAVITY_API_VERSION,
+    ANTIGRAVITY_ENDPOINT_FALLBACKS,
+    ANTIGRAVITY_HEADERS,
+    SKIP_THOUGHT_SIGNATURE_VALIDATOR,
 } from "./constants"
 import type { AntigravityRequestBody } from "./types"
 
@@ -262,7 +262,7 @@ export function transformRequest(options: TransformRequestOptions): TransformedR
   } = options
 
   const effectiveModel =
-    modelName || extractModelFromBody(body) || extractModelFromUrl(url) || "gemini-3-pro-preview"
+    modelName || extractModelFromBody(body) || extractModelFromUrl(url) || "gemini-3-pro-high"
 
   const streaming = isStreamingRequest(url, body)
   const action = streaming ? "streamGenerateContent" : "generateContent"

src/auth/antigravity/token.ts

@@ -1,8 +1,3 @@
-/**
- * Antigravity token management utilities.
- * Handles token expiration checking, refresh, and storage format parsing.
- */
-
 import {
   ANTIGRAVITY_CLIENT_ID,
   ANTIGRAVITY_CLIENT_SECRET,
@@ -13,33 +8,86 @@ import type {
   AntigravityRefreshParts,
   AntigravityTokenExchangeResult,
   AntigravityTokens,
+  OAuthErrorPayload,
+  ParsedOAuthError,
 } from "./types"
 
-/**
- * Check if the access token is expired.
- * Includes a 60-second safety buffer to refresh before actual expiration.
- *
- * @param tokens - The Antigravity tokens to check
- * @returns true if the token is expired or will expire within the buffer period
- */
-export function isTokenExpired(tokens: AntigravityTokens): boolean {
-  // Calculate when the token expires (timestamp + expires_in in ms)
-  // timestamp is in milliseconds, expires_in is in seconds
-  const expirationTime = tokens.timestamp + tokens.expires_in * 1000
+export class AntigravityTokenRefreshError extends Error {
+  code?: string
+  description?: string
+  status: number
+  statusText: string
+  responseBody?: string
 
-  // Check if current time is past (expiration - buffer)
+  constructor(options: {
+    message: string
+    code?: string
+    description?: string
+    status: number
+    statusText: string
+    responseBody?: string
+  }) {
+    super(options.message)
+    this.name = "AntigravityTokenRefreshError"
+    this.code = options.code
+    this.description = options.description
+    this.status = options.status
+    this.statusText = options.statusText
+    this.responseBody = options.responseBody
+  }
+
+  get isInvalidGrant(): boolean {
+    return this.code === "invalid_grant"
+  }
+
+  get isNetworkError(): boolean {
+    return this.status === 0
+  }
+}
+
+function parseOAuthErrorPayload(text: string | undefined): ParsedOAuthError {
+  if (!text) {
+    return {}
+  }
+
+  try {
+    const payload = JSON.parse(text) as OAuthErrorPayload
+    let code: string | undefined
+
+    if (typeof payload.error === "string") {
+      code = payload.error
+    } else if (payload.error && typeof payload.error === "object") {
+      code = payload.error.status ?? payload.error.code
+    }
+
+    return {
+      code,
+      description: payload.error_description,
+    }
+  } catch {
+    return { description: text }
+  }
+}
+
+export function isTokenExpired(tokens: AntigravityTokens): boolean {
+  const expirationTime = tokens.timestamp + tokens.expires_in * 1000
   return Date.now() >= expirationTime - ANTIGRAVITY_TOKEN_REFRESH_BUFFER_MS
 }
 
-/**
- * Refresh an access token using a refresh token.
- * Exchanges the refresh token for a new access token via Google's OAuth endpoint.
- *
- * @param refreshToken - The refresh token to use
- * @param clientId - Optional custom client ID (defaults to ANTIGRAVITY_CLIENT_ID)
- * @param clientSecret - Optional custom client secret (defaults to ANTIGRAVITY_CLIENT_SECRET)
- * @returns Token exchange result with new access token, or throws on error
- */
+const MAX_REFRESH_RETRIES = 3
+const INITIAL_RETRY_DELAY_MS = 1000
+
+function calculateRetryDelay(attempt: number): number {
+  return Math.min(INITIAL_RETRY_DELAY_MS * Math.pow(2, attempt), 10000)
+}
+
+function isRetryableError(status: number): boolean {
+  if (status === 0) return true
+  if (status === 429) return true
+  if (status >= 500 && status < 600) return true
+  return false
+}
+
 export async function refreshAccessToken(
   refreshToken: string,
   clientId: string = ANTIGRAVITY_CLIENT_ID,
@@ -52,35 +100,81 @@ export async function refreshAccessToken(
     client_secret: clientSecret,
   })
 
-  const response = await fetch(GOOGLE_TOKEN_URL, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/x-www-form-urlencoded",
-    },
-    body: params,
+  let lastError: AntigravityTokenRefreshError | undefined
+
+  for (let attempt = 0; attempt <= MAX_REFRESH_RETRIES; attempt++) {
+    try {
+      const response = await fetch(GOOGLE_TOKEN_URL, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params,
+      })
+
+      if (response.ok) {
+        const data = (await response.json()) as {
+          access_token: string
+          refresh_token?: string
+          expires_in: number
+          token_type: string
+        }
+
+        return {
+          access_token: data.access_token,
+          refresh_token: data.refresh_token || refreshToken,
+          expires_in: data.expires_in,
+          token_type: data.token_type,
+        }
+      }
+
+      const responseBody = await response.text().catch(() => undefined)
+      const parsed = parseOAuthErrorPayload(responseBody)
+
+      lastError = new AntigravityTokenRefreshError({
+        message: parsed.description || `Token refresh failed: ${response.status} ${response.statusText}`,
+        code: parsed.code,
+        description: parsed.description,
+        status: response.status,
+        statusText: response.statusText,
+        responseBody,
+      })
+
+      if (parsed.code === "invalid_grant") {
+        throw lastError
+      }
+
+      if (!isRetryableError(response.status)) {
+        throw lastError
+      }
+
+      if (attempt < MAX_REFRESH_RETRIES) {
+        const delay = calculateRetryDelay(attempt)
+        await new Promise((resolve) => setTimeout(resolve, delay))
+      }
+    } catch (error) {
+      if (error instanceof AntigravityTokenRefreshError) {
+        throw error
+      }
+
+      lastError = new AntigravityTokenRefreshError({
+        message: error instanceof Error ? error.message : "Network error during token refresh",
+        status: 0,
+        statusText: "Network Error",
+      })
+
+      if (attempt < MAX_REFRESH_RETRIES) {
+        const delay = calculateRetryDelay(attempt)
+        await new Promise((resolve) => setTimeout(resolve, delay))
+      }
+    }
+  }
+
+  throw lastError || new AntigravityTokenRefreshError({
+    message: "Token refresh failed after all retries",
+    status: 0,
+    statusText: "Max Retries Exceeded",
   })
-
-  if (!response.ok) {
-    const errorText = await response.text().catch(() => "Unknown error")
-    throw new Error(
-      `Token refresh failed: ${response.status} ${response.statusText} - ${errorText}`
-    )
-  }
-
-  const data = (await response.json()) as {
-    access_token: string
-    refresh_token?: string
-    expires_in: number
-    token_type: string
-  }
-
-  return {
-    access_token: data.access_token,
-    // Google may return a new refresh token, fall back to the original
-    refresh_token: data.refresh_token || refreshToken,
-    expires_in: data.expires_in,
-    token_type: data.token_type,
-  }
 }
 
 /**

src/auth/antigravity/types.ts

@@ -56,12 +56,23 @@ export interface AntigravityLoadCodeAssistRequest {
   metadata: AntigravityClientMetadata
 }
 
-/**
- * Response from loadCodeAssist API
- */
+export interface AntigravityUserTier {
+  id?: string
+  isDefault?: boolean
+  userDefinedCloudaicompanionProject?: boolean
+}
+
 export interface AntigravityLoadCodeAssistResponse {
-  /** Project ID - can be string or object with id field */
   cloudaicompanionProject?: string | { id: string }
+  currentTier?: { id?: string }
+  allowedTiers?: AntigravityUserTier[]
+}
+
+export interface AntigravityOnboardUserPayload {
+  done?: boolean
+  response?: {
+    cloudaicompanionProject?: { id?: string }
+  }
 }
 
 /**
@@ -183,3 +194,20 @@ export interface AntigravityRefreshParts {
   projectId?: string
   managedProjectId?: string
 }
+
+/**
+ * OAuth error payload from Google
+ * Google returns errors in multiple formats, this handles all of them
+ */
+export interface OAuthErrorPayload {
+  error?: string | { status?: string; code?: string; message?: string }
+  error_description?: string
+}
+
+/**
+ * Parsed OAuth error with normalized fields
+ */
+export interface ParsedOAuthError {
+  code?: string
+  description?: string
+}

src/cli/AGENTS.md

@@ -0,0 +1,68 @@
+# CLI KNOWLEDGE BASE
+
+## OVERVIEW
+
+CLI for oh-my-opencode: interactive installer, health diagnostics (doctor), runtime launcher. Entry: `bunx oh-my-opencode`.
+
+## STRUCTURE
+
+```
+cli/
+├── index.ts              # Commander.js entry, subcommand routing
+├── install.ts            # Interactive TUI installer (477 lines)
+├── config-manager.ts     # JSONC parsing, env detection (669 lines)
+├── types.ts              # CLI-specific types
+├── doctor/               # Health check system
+│   ├── index.ts          # Doctor command entry
+│   ├── constants.ts      # Check categories
+│   ├── types.ts          # Check result interfaces
+│   └── checks/           # 17+ individual checks
+├── get-local-version/    # Version detection
+└── run/                  # OpenCode session launcher
+```
+
+## CLI COMMANDS
+
+| Command | Purpose |
+|---------|---------|
+| `install` | Interactive setup wizard |
+| `doctor` | Environment health checks |
+| `run` | Launch OpenCode session |
+
+## DOCTOR CHECKS
+
+17+ checks in `doctor/checks/`:
+- version.ts (OpenCode >= 1.0.150)
+- config.ts (plugin registered)
+- bun.ts, node.ts, git.ts
+- anthropic-auth.ts, openai-auth.ts, google-auth.ts
+- lsp-*.ts, mcp-*.ts
+
+## CONFIG-MANAGER (669 lines)
+
+- JSONC support (comments, trailing commas)
+- Multi-source: User (~/.config/opencode/) + Project (.opencode/)
+- Zod validation
+- Legacy format migration
+- Error aggregation for doctor
+
+## HOW TO ADD CHECK
+
+1. Create `src/cli/doctor/checks/my-check.ts`:
+   ```typescript
+   export const myCheck: DoctorCheck = {
+     name: "my-check",
+     category: "environment",
+     check: async () => {
+       return { status: "pass" | "warn" | "fail", message: "..." }
+     }
+   }
+   ```
+2. Add to `src/cli/doctor/checks/index.ts`
+
+## ANTI-PATTERNS
+
+- Blocking prompts in non-TTY (check `process.stdout.isTTY`)
+- Hardcoded paths (use shared utilities)
+- JSON.parse for user files (use parseJsonc)
+- Silent failures in doctor checks

src/cli/config-manager.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test"
+
+import { ANTIGRAVITY_PROVIDER_CONFIG } from "./config-manager"
+
+describe("config-manager ANTIGRAVITY_PROVIDER_CONFIG", () => {
+  test("Gemini models include full spec (limit + modalities)", () => {
+    const google = (ANTIGRAVITY_PROVIDER_CONFIG as any).google
+    expect(google).toBeTruthy()
+
+    const models = google.models as Record<string, any>
+    expect(models).toBeTruthy()
+
+    const required = [
+      "gemini-3-pro-high",
+      "gemini-3-pro-medium",
+      "gemini-3-pro-low",
+      "gemini-3-flash",
+      "gemini-3-flash-lite",
+    ]
+
+    for (const key of required) {
+      const model = models[key]
+      expect(model).toBeTruthy()
+      expect(typeof model.name).toBe("string")
+      expect(model.name.includes("(Antigravity)")).toBe(true)
+
+      expect(model.limit).toBeTruthy()
+      expect(typeof model.limit.context).toBe("number")
+      expect(typeof model.limit.output).toBe("number")
+
+      expect(model.modalities).toBeTruthy()
+      expect(Array.isArray(model.modalities.input)).toBe(true)
+      expect(Array.isArray(model.modalities.output)).toBe(true)
+    }
+  })
+})

src/cli/config-manager.ts

@@ -0,0 +1,669 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { parseJsonc } from "../shared"
+import type { ConfigMergeResult, DetectedConfig, InstallConfig } from "./types"
+
+const OPENCODE_CONFIG_DIR = join(homedir(), ".config", "opencode")
+const OPENCODE_JSON = join(OPENCODE_CONFIG_DIR, "opencode.json")
+const OPENCODE_JSONC = join(OPENCODE_CONFIG_DIR, "opencode.jsonc")
+const OPENCODE_PACKAGE_JSON = join(OPENCODE_CONFIG_DIR, "package.json")
+const OMO_CONFIG = join(OPENCODE_CONFIG_DIR, "oh-my-opencode.json")
+
+const OPENCODE_BINARIES = ["opencode", "opencode-desktop"] as const
+
+const CHATGPT_HOTFIX_REPO = "code-yeongyu/opencode-openai-codex-auth#fix/orphaned-function-call-output-with-tools"
+
+const BUN_INSTALL_TIMEOUT_SECONDS = 60
+const BUN_INSTALL_TIMEOUT_MS = BUN_INSTALL_TIMEOUT_SECONDS * 1000
+
+interface NodeError extends Error {
+  code?: string
+}
+
+function isPermissionError(err: unknown): boolean {
+  const nodeErr = err as NodeError
+  return nodeErr?.code === "EACCES" || nodeErr?.code === "EPERM"
+}
+
+function isFileNotFoundError(err: unknown): boolean {
+  const nodeErr = err as NodeError
+  return nodeErr?.code === "ENOENT"
+}
+
+function formatErrorWithSuggestion(err: unknown, context: string): string {
+  if (isPermissionError(err)) {
+    return `Permission denied: Cannot ${context}. Try running with elevated permissions or check file ownership.`
+  }
+
+  if (isFileNotFoundError(err)) {
+    return `File not found while trying to ${context}. The file may have been deleted or moved.`
+  }
+
+  if (err instanceof SyntaxError) {
+    return `JSON syntax error while trying to ${context}: ${err.message}. Check for missing commas, brackets, or invalid characters.`
+  }
+
+  const message = err instanceof Error ? err.message : String(err)
+
+  if (message.includes("ENOSPC")) {
+    return `Disk full: Cannot ${context}. Free up disk space and try again.`
+  }
+
+  if (message.includes("EROFS")) {
+    return `Read-only filesystem: Cannot ${context}. Check if the filesystem is mounted read-only.`
+  }
+
+  return `Failed to ${context}: ${message}`
+}
+
+export async function fetchLatestVersion(packageName: string): Promise<string | null> {
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${packageName}/latest`)
+    if (!res.ok) return null
+    const data = await res.json() as { version: string }
+    return data.version
+  } catch {
+    return null
+  }
+}
+
+type ConfigFormat = "json" | "jsonc" | "none"
+
+interface OpenCodeConfig {
+  plugin?: string[]
+  [key: string]: unknown
+}
+
+export function detectConfigFormat(): { format: ConfigFormat; path: string } {
+  if (existsSync(OPENCODE_JSONC)) {
+    return { format: "jsonc", path: OPENCODE_JSONC }
+  }
+  if (existsSync(OPENCODE_JSON)) {
+    return { format: "json", path: OPENCODE_JSON }
+  }
+  return { format: "none", path: OPENCODE_JSON }
+}
+
+interface ParseConfigResult {
+  config: OpenCodeConfig | null
+  error?: string
+}
+
+function isEmptyOrWhitespace(content: string): boolean {
+  return content.trim().length === 0
+}
+
+function parseConfig(path: string, _isJsonc: boolean): OpenCodeConfig | null {
+  const result = parseConfigWithError(path)
+  return result.config
+}
+
+function parseConfigWithError(path: string): ParseConfigResult {
+  try {
+    const stat = statSync(path)
+    if (stat.size === 0) {
+      return { config: null, error: `Config file is empty: ${path}. Delete it or add valid JSON content.` }
+    }
+
+    const content = readFileSync(path, "utf-8")
+
+    if (isEmptyOrWhitespace(content)) {
+      return { config: null, error: `Config file contains only whitespace: ${path}. Delete it or add valid JSON content.` }
+    }
+
+    const config = parseJsonc<OpenCodeConfig>(content)
+
+    if (config === null || config === undefined) {
+      return { config: null, error: `Config file parsed to null/undefined: ${path}. Ensure it contains valid JSON.` }
+    }
+
+    if (typeof config !== "object" || Array.isArray(config)) {
+      return { config: null, error: `Config file must contain a JSON object, not ${Array.isArray(config) ? "an array" : typeof config}: ${path}` }
+    }
+
+    return { config }
+  } catch (err) {
+    return { config: null, error: formatErrorWithSuggestion(err, `parse config file ${path}`) }
+  }
+}
+
+function ensureConfigDir(): void {
+  if (!existsSync(OPENCODE_CONFIG_DIR)) {
+    mkdirSync(OPENCODE_CONFIG_DIR, { recursive: true })
+  }
+}
+
+export function addPluginToOpenCodeConfig(): ConfigMergeResult {
+  try {
+    ensureConfigDir()
+  } catch (err) {
+    return { success: false, configPath: OPENCODE_CONFIG_DIR, error: formatErrorWithSuggestion(err, "create config directory") }
+  }
+
+  const { format, path } = detectConfigFormat()
+  const pluginName = "oh-my-opencode"
+
+  try {
+    if (format === "none") {
+      const config: OpenCodeConfig = { plugin: [pluginName] }
+      writeFileSync(path, JSON.stringify(config, null, 2) + "\n")
+      return { success: true, configPath: path }
+    }
+
+    const parseResult = parseConfigWithError(path)
+    if (!parseResult.config) {
+      return { success: false, configPath: path, error: parseResult.error ?? "Failed to parse config file" }
+    }
+
+    const config = parseResult.config
+    const plugins = config.plugin ?? []
+    if (plugins.some((p) => p.startsWith(pluginName))) {
+      return { success: true, configPath: path }
+    }
+
+    config.plugin = [...plugins, pluginName]
+
+    if (format === "jsonc") {
+      const content = readFileSync(path, "utf-8")
+      const pluginArrayRegex = /"plugin"\s*:\s*\[([\s\S]*?)\]/
+      const match = content.match(pluginArrayRegex)
+
+      if (match) {
+        const arrayContent = match[1].trim()
+        const newArrayContent = arrayContent
+          ? `${arrayContent},\n    "${pluginName}"`
+          : `"${pluginName}"`
+        const newContent = content.replace(pluginArrayRegex, `"plugin": [\n    ${newArrayContent}\n  ]`)
+        writeFileSync(path, newContent)
+      } else {
+        const newContent = content.replace(/^(\s*\{)/, `$1\n  "plugin": ["${pluginName}"],`)
+        writeFileSync(path, newContent)
+      }
+    } else {
+      writeFileSync(path, JSON.stringify(config, null, 2) + "\n")
+    }
+
+    return { success: true, configPath: path }
+  } catch (err) {
+    return { success: false, configPath: path, error: formatErrorWithSuggestion(err, "update opencode config") }
+  }
+}
+
+function deepMerge<T extends Record<string, unknown>>(target: T, source: Partial<T>): T {
+  const result = { ...target }
+
+  for (const key of Object.keys(source) as Array<keyof T>) {
+    const sourceValue = source[key]
+    const targetValue = result[key]
+
+    if (
+      sourceValue !== null &&
+      typeof sourceValue === "object" &&
+      !Array.isArray(sourceValue) &&
+      targetValue !== null &&
+      typeof targetValue === "object" &&
+      !Array.isArray(targetValue)
+    ) {
+      result[key] = deepMerge(
+        targetValue as Record<string, unknown>,
+        sourceValue as Record<string, unknown>
+      ) as T[keyof T]
+    } else if (sourceValue !== undefined) {
+      result[key] = sourceValue as T[keyof T]
+    }
+  }
+
+  return result
+}
+
+export function generateOmoConfig(installConfig: InstallConfig): Record<string, unknown> {
+  const config: Record<string, unknown> = {
+    $schema: "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
+  }
+
+  if (installConfig.hasGemini) {
+    config.google_auth = false
+  }
+
+  const agents: Record<string, Record<string, unknown>> = {}
+
+  if (!installConfig.hasClaude) {
+    agents["Sisyphus"] = { model: "opencode/big-pickle" }
+  }
+
+  if (installConfig.hasGemini) {
+    agents["librarian"] = { model: "google/gemini-3-flash" }
+    agents["explore"] = { model: "google/gemini-3-flash" }
+  } else if (installConfig.hasClaude && installConfig.isMax20) {
+    agents["explore"] = { model: "anthropic/claude-haiku-4-5" }
+  } else {
+    agents["librarian"] = { model: "opencode/big-pickle" }
+    agents["explore"] = { model: "opencode/big-pickle" }
+  }
+
+  if (!installConfig.hasChatGPT) {
+    agents["oracle"] = {
+      model: installConfig.hasClaude ? "anthropic/claude-opus-4-5" : "opencode/big-pickle",
+    }
+  }
+
+  if (installConfig.hasGemini) {
+    agents["frontend-ui-ux-engineer"] = { model: "google/gemini-3-pro-high" }
+    agents["document-writer"] = { model: "google/gemini-3-flash" }
+    agents["multimodal-looker"] = { model: "google/gemini-3-flash" }
+  } else {
+    const fallbackModel = installConfig.hasClaude ? "anthropic/claude-opus-4-5" : "opencode/big-pickle"
+    agents["frontend-ui-ux-engineer"] = { model: fallbackModel }
+    agents["document-writer"] = { model: fallbackModel }
+    agents["multimodal-looker"] = { model: fallbackModel }
+  }
+
+  if (Object.keys(agents).length > 0) {
+    config.agents = agents
+  }
+
+  return config
+}
+
+export function writeOmoConfig(installConfig: InstallConfig): ConfigMergeResult {
+  try {
+    ensureConfigDir()
+  } catch (err) {
+    return { success: false, configPath: OPENCODE_CONFIG_DIR, error: formatErrorWithSuggestion(err, "create config directory") }
+  }
+
+  try {
+    const newConfig = generateOmoConfig(installConfig)
+
+    if (existsSync(OMO_CONFIG)) {
+      try {
+        const stat = statSync(OMO_CONFIG)
+        const content = readFileSync(OMO_CONFIG, "utf-8")
+
+        if (stat.size === 0 || isEmptyOrWhitespace(content)) {
+          writeFileSync(OMO_CONFIG, JSON.stringify(newConfig, null, 2) + "\n")
+          return { success: true, configPath: OMO_CONFIG }
+        }
+
+        const existing = parseJsonc<Record<string, unknown>>(content)
+        if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
+          writeFileSync(OMO_CONFIG, JSON.stringify(newConfig, null, 2) + "\n")
+          return { success: true, configPath: OMO_CONFIG }
+        }
+
+        delete existing.agents
+        const merged = deepMerge(existing, newConfig)
+        writeFileSync(OMO_CONFIG, JSON.stringify(merged, null, 2) + "\n")
+      } catch (parseErr) {
+        if (parseErr instanceof SyntaxError) {
+          writeFileSync(OMO_CONFIG, JSON.stringify(newConfig, null, 2) + "\n")
+          return { success: true, configPath: OMO_CONFIG }
+        }
+        throw parseErr
+      }
+    } else {
+      writeFileSync(OMO_CONFIG, JSON.stringify(newConfig, null, 2) + "\n")
+    }
+
+    return { success: true, configPath: OMO_CONFIG }
+  } catch (err) {
+    return { success: false, configPath: OMO_CONFIG, error: formatErrorWithSuggestion(err, "write oh-my-opencode config") }
+  }
+}
+
+interface OpenCodeBinaryResult {
+  binary: string
+  version: string
+}
+
+async function findOpenCodeBinaryWithVersion(): Promise<OpenCodeBinaryResult | null> {
+  for (const binary of OPENCODE_BINARIES) {
+    try {
+      const proc = Bun.spawn([binary, "--version"], {
+        stdout: "pipe",
+        stderr: "pipe",
+      })
+      const output = await new Response(proc.stdout).text()
+      await proc.exited
+      if (proc.exitCode === 0) {
+        return { binary, version: output.trim() }
+      }
+    } catch {
+      continue
+    }
+  }
+  return null
+}
+
+export async function isOpenCodeInstalled(): Promise<boolean> {
+  const result = await findOpenCodeBinaryWithVersion()
+  return result !== null
+}
+
+export async function getOpenCodeVersion(): Promise<string | null> {
+  const result = await findOpenCodeBinaryWithVersion()
+  return result?.version ?? null
+}
+
+export async function addAuthPlugins(config: InstallConfig): Promise<ConfigMergeResult> {
+  try {
+    ensureConfigDir()
+  } catch (err) {
+    return { success: false, configPath: OPENCODE_CONFIG_DIR, error: formatErrorWithSuggestion(err, "create config directory") }
+  }
+
+  const { format, path } = detectConfigFormat()
+
+  try {
+    let existingConfig: OpenCodeConfig | null = null
+    if (format !== "none") {
+      const parseResult = parseConfigWithError(path)
+      if (parseResult.error && !parseResult.config) {
+        existingConfig = {}
+      } else {
+        existingConfig = parseResult.config
+      }
+    }
+
+    const plugins: string[] = existingConfig?.plugin ?? []
+
+    if (config.hasGemini) {
+      const version = await fetchLatestVersion("opencode-antigravity-auth")
+      const pluginEntry = version ? `opencode-antigravity-auth@${version}` : "opencode-antigravity-auth"
+      if (!plugins.some((p) => p.startsWith("opencode-antigravity-auth"))) {
+        plugins.push(pluginEntry)
+      }
+    }
+
+    if (config.hasChatGPT) {
+      if (!plugins.some((p) => p.startsWith("opencode-openai-codex-auth"))) {
+        plugins.push("opencode-openai-codex-auth")
+      }
+    }
+
+    const newConfig = { ...(existingConfig ?? {}), plugin: plugins }
+    writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n")
+    return { success: true, configPath: path }
+  } catch (err) {
+    return { success: false, configPath: path, error: formatErrorWithSuggestion(err, "add auth plugins to config") }
+  }
+}
+
+export function setupChatGPTHotfix(): ConfigMergeResult {
+  try {
+    ensureConfigDir()
+  } catch (err) {
+    return { success: false, configPath: OPENCODE_CONFIG_DIR, error: formatErrorWithSuggestion(err, "create config directory") }
+  }
+
+  try {
+    let packageJson: Record<string, unknown> = {}
+    if (existsSync(OPENCODE_PACKAGE_JSON)) {
+      try {
+        const stat = statSync(OPENCODE_PACKAGE_JSON)
+        const content = readFileSync(OPENCODE_PACKAGE_JSON, "utf-8")
+
+        if (stat.size > 0 && !isEmptyOrWhitespace(content)) {
+          packageJson = JSON.parse(content)
+          if (typeof packageJson !== "object" || packageJson === null || Array.isArray(packageJson)) {
+            packageJson = {}
+          }
+        }
+      } catch (parseErr) {
+        if (parseErr instanceof SyntaxError) {
+          packageJson = {}
+        } else {
+          throw parseErr
+        }
+      }
+    }
+
+    const deps = (packageJson.dependencies ?? {}) as Record<string, string>
+    deps["opencode-openai-codex-auth"] = CHATGPT_HOTFIX_REPO
+    packageJson.dependencies = deps
+
+    writeFileSync(OPENCODE_PACKAGE_JSON, JSON.stringify(packageJson, null, 2) + "\n")
+    return { success: true, configPath: OPENCODE_PACKAGE_JSON }
+  } catch (err) {
+    return { success: false, configPath: OPENCODE_PACKAGE_JSON, error: formatErrorWithSuggestion(err, "setup ChatGPT hotfix in package.json") }
+  }
+}
+
+export interface BunInstallResult {
+  success: boolean
+  timedOut?: boolean
+  error?: string
+}
+
+export async function runBunInstall(): Promise<boolean> {
+  const result = await runBunInstallWithDetails()
+  return result.success
+}
+
+export async function runBunInstallWithDetails(): Promise<BunInstallResult> {
+  try {
+    const proc = Bun.spawn(["bun", "install"], {
+      cwd: OPENCODE_CONFIG_DIR,
+      stdout: "pipe",
+      stderr: "pipe",
+    })
+
+    const timeoutPromise = new Promise<"timeout">((resolve) =>
+      setTimeout(() => resolve("timeout"), BUN_INSTALL_TIMEOUT_MS)
+    )
+
+    const exitPromise = proc.exited.then(() => "completed" as const)
+
+    const result = await Promise.race([exitPromise, timeoutPromise])
+
+    if (result === "timeout") {
+      try {
+        proc.kill()
+      } catch {
+        /* intentionally empty - process may have already exited */
+      }
+      return {
+        success: false,
+        timedOut: true,
+        error: `bun install timed out after ${BUN_INSTALL_TIMEOUT_SECONDS} seconds. Try running manually: cd ~/.config/opencode && bun i`,
+      }
+    }
+
+    if (proc.exitCode !== 0) {
+      const stderr = await new Response(proc.stderr).text()
+      return {
+        success: false,
+        error: stderr.trim() || `bun install failed with exit code ${proc.exitCode}`,
+      }
+    }
+
+    return { success: true }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return {
+      success: false,
+      error: `bun install failed: ${message}. Is bun installed? Try: curl -fsSL https://bun.sh/install | bash`,
+    }
+  }
+}
+
+export const ANTIGRAVITY_PROVIDER_CONFIG = {
+  google: {
+    name: "Google",
+    // NOTE: opencode-antigravity-auth expects full model specs (name/limit/modalities).
+    // If these are incomplete, models may appear but fail at runtime (e.g. 404).
+    models: {
+      "gemini-3-pro-high": {
+        name: "Gemini 3 Pro High (Antigravity)",
+        thinking: true,
+        attachment: true,
+        limit: { context: 1048576, output: 65535 },
+        modalities: { input: ["text", "image", "pdf"], output: ["text"] },
+      },
+      "gemini-3-pro-medium": {
+        name: "Gemini 3 Pro Medium (Antigravity)",
+        thinking: true,
+        attachment: true,
+        limit: { context: 1048576, output: 65535 },
+        modalities: { input: ["text", "image", "pdf"], output: ["text"] },
+      },
+      "gemini-3-pro-low": {
+        name: "Gemini 3 Pro Low (Antigravity)",
+        thinking: true,
+        attachment: true,
+        limit: { context: 1048576, output: 65535 },
+        modalities: { input: ["text", "image", "pdf"], output: ["text"] },
+      },
+      "gemini-3-flash": {
+        name: "Gemini 3 Flash (Antigravity)",
+        attachment: true,
+        limit: { context: 1048576, output: 65536 },
+        modalities: { input: ["text", "image", "pdf"], output: ["text"] },
+      },
+      "gemini-3-flash-lite": {
+        name: "Gemini 3 Flash Lite (Antigravity)",
+        attachment: true,
+        limit: { context: 1048576, output: 65536 },
+        modalities: { input: ["text", "image", "pdf"], output: ["text"] },
+      },
+    },
+  },
+}
+
+const CODEX_PROVIDER_CONFIG = {
+  openai: {
+    name: "OpenAI",
+    api: "codex",
+    models: {
+      "gpt-5.2": { name: "GPT-5.2" },
+      "o3": { name: "o3", thinking: true },
+      "o4-mini": { name: "o4-mini", thinking: true },
+      "codex-1": { name: "Codex-1" },
+    },
+  },
+}
+
+export function addProviderConfig(config: InstallConfig): ConfigMergeResult {
+  try {
+    ensureConfigDir()
+  } catch (err) {
+    return { success: false, configPath: OPENCODE_CONFIG_DIR, error: formatErrorWithSuggestion(err, "create config directory") }
+  }
+
+  const { format, path } = detectConfigFormat()
+
+  try {
+    let existingConfig: OpenCodeConfig | null = null
+    if (format !== "none") {
+      const parseResult = parseConfigWithError(path)
+      if (parseResult.error && !parseResult.config) {
+        existingConfig = {}
+      } else {
+        existingConfig = parseResult.config
+      }
+    }
+
+    const newConfig = { ...(existingConfig ?? {}) }
+
+    const providers = (newConfig.provider ?? {}) as Record<string, unknown>
+
+    if (config.hasGemini) {
+      providers.google = ANTIGRAVITY_PROVIDER_CONFIG.google
+    }
+
+    if (config.hasChatGPT) {
+      providers.openai = CODEX_PROVIDER_CONFIG.openai
+    }
+
+    if (Object.keys(providers).length > 0) {
+      newConfig.provider = providers
+    }
+
+    writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n")
+    return { success: true, configPath: path }
+  } catch (err) {
+    return { success: false, configPath: path, error: formatErrorWithSuggestion(err, "add provider config") }
+  }
+}
+
+interface OmoConfigData {
+  google_auth?: boolean
+  agents?: Record<string, { model?: string }>
+}
+
+export function detectCurrentConfig(): DetectedConfig {
+  const result: DetectedConfig = {
+    isInstalled: false,
+    hasClaude: true,
+    isMax20: true,
+    hasChatGPT: true,
+    hasGemini: false,
+  }
+
+  const { format, path } = detectConfigFormat()
+  if (format === "none") {
+    return result
+  }
+
+  const parseResult = parseConfigWithError(path)
+  if (!parseResult.config) {
+    return result
+  }
+
+  const openCodeConfig = parseResult.config
+  const plugins = openCodeConfig.plugin ?? []
+  result.isInstalled = plugins.some((p) => p.startsWith("oh-my-opencode"))
+
+  if (!result.isInstalled) {
+    return result
+  }
+
+  result.hasGemini = plugins.some((p) => p.startsWith("opencode-antigravity-auth"))
+  result.hasChatGPT = plugins.some((p) => p.startsWith("opencode-openai-codex-auth"))
+
+  if (!existsSync(OMO_CONFIG)) {
+    return result
+  }
+
+  try {
+    const stat = statSync(OMO_CONFIG)
+    if (stat.size === 0) {
+      return result
+    }
+
+    const content = readFileSync(OMO_CONFIG, "utf-8")
+    if (isEmptyOrWhitespace(content)) {
+      return result
+    }
+
+    const omoConfig = parseJsonc<OmoConfigData>(content)
+    if (!omoConfig || typeof omoConfig !== "object") {
+      return result
+    }
+
+    const agents = omoConfig.agents ?? {}
+
+    if (agents["Sisyphus"]?.model === "opencode/big-pickle") {
+      result.hasClaude = false
+      result.isMax20 = false
+    } else if (agents["librarian"]?.model === "opencode/big-pickle") {
+      result.hasClaude = true
+      result.isMax20 = false
+    }
+
+    if (agents["oracle"]?.model?.startsWith("anthropic/")) {
+      result.hasChatGPT = false
+    } else if (agents["oracle"]?.model === "opencode/big-pickle") {
+      result.hasChatGPT = false
+    }
+
+    if (omoConfig.google_auth === false) {
+      result.hasGemini = plugins.some((p) => p.startsWith("opencode-antigravity-auth"))
+    }
+  } catch {
+    /* intentionally empty - malformed omo config returns defaults from opencode config detection */
+  }
+
+  return result
+}

src/cli/doctor/checks/auth.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as auth from "./auth"
+
+describe("auth check", () => {
+  describe("getAuthProviderInfo", () => {
+    it("returns anthropic as always available", () => {
+      // #given anthropic provider
+      // #when getting info
+      const info = auth.getAuthProviderInfo("anthropic")
+
+      // #then should show plugin installed (builtin)
+      expect(info.id).toBe("anthropic")
+      expect(info.pluginInstalled).toBe(true)
+    })
+
+    it("returns correct name for each provider", () => {
+      // #given each provider
+      // #when getting info
+      // #then should have correct names
+      expect(auth.getAuthProviderInfo("anthropic").name).toContain("Claude")
+      expect(auth.getAuthProviderInfo("openai").name).toContain("ChatGPT")
+      expect(auth.getAuthProviderInfo("google").name).toContain("Gemini")
+    })
+  })
+
+  describe("checkAuthProvider", () => {
+    let getInfoSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getInfoSpy?.mockRestore()
+    })
+
+    it("returns pass when plugin installed", async () => {
+      // #given plugin installed
+      getInfoSpy = spyOn(auth, "getAuthProviderInfo").mockReturnValue({
+        id: "anthropic",
+        name: "Anthropic (Claude)",
+        pluginInstalled: true,
+        configured: true,
+      })
+
+      // #when checking
+      const result = await auth.checkAuthProvider("anthropic")
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+    })
+
+    it("returns skip when plugin not installed", async () => {
+      // #given plugin not installed
+      getInfoSpy = spyOn(auth, "getAuthProviderInfo").mockReturnValue({
+        id: "openai",
+        name: "OpenAI (ChatGPT)",
+        pluginInstalled: false,
+        configured: false,
+      })
+
+      // #when checking
+      const result = await auth.checkAuthProvider("openai")
+
+      // #then should skip
+      expect(result.status).toBe("skip")
+      expect(result.message).toContain("not installed")
+    })
+  })
+
+  describe("checkAnthropicAuth", () => {
+    it("returns a check result", async () => {
+      // #given
+      // #when checking anthropic
+      const result = await auth.checkAnthropicAuth()
+
+      // #then should return valid result
+      expect(result.name).toBeDefined()
+      expect(["pass", "fail", "warn", "skip"]).toContain(result.status)
+    })
+  })
+
+  describe("checkOpenAIAuth", () => {
+    it("returns a check result", async () => {
+      // #given
+      // #when checking openai
+      const result = await auth.checkOpenAIAuth()
+
+      // #then should return valid result
+      expect(result.name).toBeDefined()
+      expect(["pass", "fail", "warn", "skip"]).toContain(result.status)
+    })
+  })
+
+  describe("checkGoogleAuth", () => {
+    it("returns a check result", async () => {
+      // #given
+      // #when checking google
+      const result = await auth.checkGoogleAuth()
+
+      // #then should return valid result
+      expect(result.name).toBeDefined()
+      expect(["pass", "fail", "warn", "skip"]).toContain(result.status)
+    })
+  })
+
+  describe("getAuthCheckDefinitions", () => {
+    it("returns definitions for all three providers", () => {
+      // #given
+      // #when getting definitions
+      const defs = auth.getAuthCheckDefinitions()
+
+      // #then should have 3 definitions
+      expect(defs.length).toBe(3)
+      expect(defs.every((d) => d.category === "authentication")).toBe(true)
+    })
+  })
+})

src/cli/doctor/checks/auth.ts

@@ -0,0 +1,115 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import type { CheckResult, CheckDefinition, AuthProviderInfo, AuthProviderId } from "../types"
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+import { parseJsonc } from "../../../shared"
+
+const OPENCODE_CONFIG_DIR = join(homedir(), ".config", "opencode")
+const OPENCODE_JSON = join(OPENCODE_CONFIG_DIR, "opencode.json")
+const OPENCODE_JSONC = join(OPENCODE_CONFIG_DIR, "opencode.jsonc")
+
+const AUTH_PLUGINS: Record<AuthProviderId, { plugin: string; name: string }> = {
+  anthropic: { plugin: "builtin", name: "Anthropic (Claude)" },
+  openai: { plugin: "opencode-openai-codex-auth", name: "OpenAI (ChatGPT)" },
+  google: { plugin: "opencode-antigravity-auth", name: "Google (Gemini)" },
+}
+
+function getOpenCodeConfig(): { plugin?: string[] } | null {
+  const configPath = existsSync(OPENCODE_JSONC) ? OPENCODE_JSONC : OPENCODE_JSON
+  if (!existsSync(configPath)) return null
+
+  try {
+    const content = readFileSync(configPath, "utf-8")
+    return parseJsonc<{ plugin?: string[] }>(content)
+  } catch {
+    return null
+  }
+}
+
+function isPluginInstalled(plugins: string[], pluginName: string): boolean {
+  if (pluginName === "builtin") return true
+  return plugins.some((p) => p === pluginName || p.startsWith(`${pluginName}@`))
+}
+
+export function getAuthProviderInfo(providerId: AuthProviderId): AuthProviderInfo {
+  const config = getOpenCodeConfig()
+  const plugins = config?.plugin ?? []
+  const authConfig = AUTH_PLUGINS[providerId]
+
+  const pluginInstalled = isPluginInstalled(plugins, authConfig.plugin)
+
+  return {
+    id: providerId,
+    name: authConfig.name,
+    pluginInstalled,
+    configured: pluginInstalled,
+  }
+}
+
+export async function checkAuthProvider(providerId: AuthProviderId): Promise<CheckResult> {
+  const info = getAuthProviderInfo(providerId)
+  const checkId = `auth-${providerId}` as keyof typeof CHECK_NAMES
+  const checkName = CHECK_NAMES[checkId] || info.name
+
+  if (!info.pluginInstalled) {
+    return {
+      name: checkName,
+      status: "skip",
+      message: "Auth plugin not installed",
+      details: [
+        `Plugin: ${AUTH_PLUGINS[providerId].plugin}`,
+        "Run: bunx oh-my-opencode install",
+      ],
+    }
+  }
+
+  return {
+    name: checkName,
+    status: "pass",
+    message: "Auth plugin available",
+    details: [
+      providerId === "anthropic"
+        ? "Run: opencode auth login (select Anthropic)"
+        : `Plugin: ${AUTH_PLUGINS[providerId].plugin}`,
+    ],
+  }
+}
+
+export async function checkAnthropicAuth(): Promise<CheckResult> {
+  return checkAuthProvider("anthropic")
+}
+
+export async function checkOpenAIAuth(): Promise<CheckResult> {
+  return checkAuthProvider("openai")
+}
+
+export async function checkGoogleAuth(): Promise<CheckResult> {
+  return checkAuthProvider("google")
+}
+
+export function getAuthCheckDefinitions(): CheckDefinition[] {
+  return [
+    {
+      id: CHECK_IDS.AUTH_ANTHROPIC,
+      name: CHECK_NAMES[CHECK_IDS.AUTH_ANTHROPIC],
+      category: "authentication",
+      check: checkAnthropicAuth,
+      critical: false,
+    },
+    {
+      id: CHECK_IDS.AUTH_OPENAI,
+      name: CHECK_NAMES[CHECK_IDS.AUTH_OPENAI],
+      category: "authentication",
+      check: checkOpenAIAuth,
+      critical: false,
+    },
+    {
+      id: CHECK_IDS.AUTH_GOOGLE,
+      name: CHECK_NAMES[CHECK_IDS.AUTH_GOOGLE],
+      category: "authentication",
+      check: checkGoogleAuth,
+      critical: false,
+    },
+  ]
+}

src/cli/doctor/checks/config.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as config from "./config"
+
+describe("config check", () => {
+  describe("validateConfig", () => {
+    it("returns valid: false for non-existent file", () => {
+      // #given non-existent file path
+      // #when validating
+      const result = config.validateConfig("/non/existent/path.json")
+
+      // #then should indicate invalid
+      expect(result.valid).toBe(false)
+      expect(result.errors.length).toBeGreaterThan(0)
+    })
+  })
+
+  describe("getConfigInfo", () => {
+    it("returns exists: false when no config found", () => {
+      // #given no config file exists
+      // #when getting config info
+      const info = config.getConfigInfo()
+
+      // #then should handle gracefully
+      expect(typeof info.exists).toBe("boolean")
+      expect(typeof info.valid).toBe("boolean")
+    })
+  })
+
+  describe("checkConfigValidity", () => {
+    let getInfoSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getInfoSpy?.mockRestore()
+    })
+
+    it("returns pass when no config exists (uses defaults)", async () => {
+      // #given no config file
+      getInfoSpy = spyOn(config, "getConfigInfo").mockReturnValue({
+        exists: false,
+        path: null,
+        format: null,
+        valid: true,
+        errors: [],
+      })
+
+      // #when checking validity
+      const result = await config.checkConfigValidity()
+
+      // #then should pass with default message
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("default")
+    })
+
+    it("returns pass when config is valid", async () => {
+      // #given valid config
+      getInfoSpy = spyOn(config, "getConfigInfo").mockReturnValue({
+        exists: true,
+        path: "/home/user/.config/opencode/oh-my-opencode.json",
+        format: "json",
+        valid: true,
+        errors: [],
+      })
+
+      // #when checking validity
+      const result = await config.checkConfigValidity()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("JSON")
+    })
+
+    it("returns fail when config has validation errors", async () => {
+      // #given invalid config
+      getInfoSpy = spyOn(config, "getConfigInfo").mockReturnValue({
+        exists: true,
+        path: "/home/user/.config/opencode/oh-my-opencode.json",
+        format: "json",
+        valid: false,
+        errors: ["agents.oracle: Invalid model format"],
+      })
+
+      // #when checking validity
+      const result = await config.checkConfigValidity()
+
+      // #then should fail with errors
+      expect(result.status).toBe("fail")
+      expect(result.details?.some((d) => d.includes("Error"))).toBe(true)
+    })
+  })
+
+  describe("getConfigCheckDefinition", () => {
+    it("returns valid check definition", () => {
+      // #given
+      // #when getting definition
+      const def = config.getConfigCheckDefinition()
+
+      // #then should have required properties
+      expect(def.id).toBe("config-validation")
+      expect(def.category).toBe("configuration")
+      expect(def.critical).toBe(false)
+    })
+  })
+})

src/cli/doctor/checks/config.ts

@@ -0,0 +1,123 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import type { CheckResult, CheckDefinition, ConfigInfo } from "../types"
+import { CHECK_IDS, CHECK_NAMES, PACKAGE_NAME } from "../constants"
+import { parseJsonc, detectConfigFile } from "../../../shared"
+import { OhMyOpenCodeConfigSchema } from "../../../config"
+
+const USER_CONFIG_DIR = join(homedir(), ".config", "opencode")
+const USER_CONFIG_BASE = join(USER_CONFIG_DIR, `${PACKAGE_NAME}`)
+const PROJECT_CONFIG_BASE = join(process.cwd(), ".opencode", PACKAGE_NAME)
+
+function findConfigPath(): { path: string; format: "json" | "jsonc" } | null {
+  const projectDetected = detectConfigFile(PROJECT_CONFIG_BASE)
+  if (projectDetected.format !== "none") {
+    return { path: projectDetected.path, format: projectDetected.format as "json" | "jsonc" }
+  }
+
+  const userDetected = detectConfigFile(USER_CONFIG_BASE)
+  if (userDetected.format !== "none") {
+    return { path: userDetected.path, format: userDetected.format as "json" | "jsonc" }
+  }
+
+  return null
+}
+
+export function validateConfig(configPath: string): { valid: boolean; errors: string[] } {
+  try {
+    const content = readFileSync(configPath, "utf-8")
+    const rawConfig = parseJsonc<Record<string, unknown>>(content)
+    const result = OhMyOpenCodeConfigSchema.safeParse(rawConfig)
+
+    if (!result.success) {
+      const errors = result.error.issues.map(
+        (i) => `${i.path.join(".")}: ${i.message}`
+      )
+      return { valid: false, errors }
+    }
+
+    return { valid: true, errors: [] }
+  } catch (err) {
+    return {
+      valid: false,
+      errors: [err instanceof Error ? err.message : "Failed to parse config"],
+    }
+  }
+}
+
+export function getConfigInfo(): ConfigInfo {
+  const configPath = findConfigPath()
+
+  if (!configPath) {
+    return {
+      exists: false,
+      path: null,
+      format: null,
+      valid: true,
+      errors: [],
+    }
+  }
+
+  if (!existsSync(configPath.path)) {
+    return {
+      exists: false,
+      path: configPath.path,
+      format: configPath.format,
+      valid: true,
+      errors: [],
+    }
+  }
+
+  const validation = validateConfig(configPath.path)
+
+  return {
+    exists: true,
+    path: configPath.path,
+    format: configPath.format,
+    valid: validation.valid,
+    errors: validation.errors,
+  }
+}
+
+export async function checkConfigValidity(): Promise<CheckResult> {
+  const info = getConfigInfo()
+
+  if (!info.exists) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.CONFIG_VALIDATION],
+      status: "pass",
+      message: "Using default configuration",
+      details: ["No custom config file found (optional)"],
+    }
+  }
+
+  if (!info.valid) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.CONFIG_VALIDATION],
+      status: "fail",
+      message: "Configuration has validation errors",
+      details: [
+        `Path: ${info.path}`,
+        ...info.errors.map((e) => `Error: ${e}`),
+      ],
+    }
+  }
+
+  return {
+    name: CHECK_NAMES[CHECK_IDS.CONFIG_VALIDATION],
+    status: "pass",
+    message: `Valid ${info.format?.toUpperCase()} config`,
+    details: [`Path: ${info.path}`],
+  }
+}
+
+export function getConfigCheckDefinition(): CheckDefinition {
+  return {
+    id: CHECK_IDS.CONFIG_VALIDATION,
+    name: CHECK_NAMES[CHECK_IDS.CONFIG_VALIDATION],
+    category: "configuration",
+    check: checkConfigValidity,
+    critical: false,
+  }
+}

src/cli/doctor/checks/dependencies.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as deps from "./dependencies"
+
+describe("dependencies check", () => {
+  describe("checkAstGrepCli", () => {
+    it("returns dependency info", async () => {
+      // #given
+      // #when checking ast-grep cli
+      const info = await deps.checkAstGrepCli()
+
+      // #then should return valid info
+      expect(info.name).toBe("AST-Grep CLI")
+      expect(info.required).toBe(false)
+      expect(typeof info.installed).toBe("boolean")
+    })
+  })
+
+  describe("checkAstGrepNapi", () => {
+    it("returns dependency info", () => {
+      // #given
+      // #when checking ast-grep napi
+      const info = deps.checkAstGrepNapi()
+
+      // #then should return valid info
+      expect(info.name).toBe("AST-Grep NAPI")
+      expect(info.required).toBe(false)
+      expect(typeof info.installed).toBe("boolean")
+    })
+  })
+
+  describe("checkCommentChecker", () => {
+    it("returns dependency info", async () => {
+      // #given
+      // #when checking comment checker
+      const info = await deps.checkCommentChecker()
+
+      // #then should return valid info
+      expect(info.name).toBe("Comment Checker")
+      expect(info.required).toBe(false)
+      expect(typeof info.installed).toBe("boolean")
+    })
+  })
+
+  describe("checkDependencyAstGrepCli", () => {
+    let checkSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      checkSpy?.mockRestore()
+    })
+
+    it("returns pass when installed", async () => {
+      // #given ast-grep installed
+      checkSpy = spyOn(deps, "checkAstGrepCli").mockResolvedValue({
+        name: "AST-Grep CLI",
+        required: false,
+        installed: true,
+        version: "0.25.0",
+        path: "/usr/local/bin/sg",
+      })
+
+      // #when checking
+      const result = await deps.checkDependencyAstGrepCli()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("0.25.0")
+    })
+
+    it("returns warn when not installed", async () => {
+      // #given ast-grep not installed
+      checkSpy = spyOn(deps, "checkAstGrepCli").mockResolvedValue({
+        name: "AST-Grep CLI",
+        required: false,
+        installed: false,
+        version: null,
+        path: null,
+        installHint: "Install: npm install -g @ast-grep/cli",
+      })
+
+      // #when checking
+      const result = await deps.checkDependencyAstGrepCli()
+
+      // #then should warn (optional)
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("optional")
+    })
+  })
+
+  describe("checkDependencyAstGrepNapi", () => {
+    let checkSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      checkSpy?.mockRestore()
+    })
+
+    it("returns pass when installed", async () => {
+      // #given napi installed
+      checkSpy = spyOn(deps, "checkAstGrepNapi").mockReturnValue({
+        name: "AST-Grep NAPI",
+        required: false,
+        installed: true,
+        version: null,
+        path: null,
+      })
+
+      // #when checking
+      const result = await deps.checkDependencyAstGrepNapi()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+    })
+  })
+
+  describe("checkDependencyCommentChecker", () => {
+    let checkSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      checkSpy?.mockRestore()
+    })
+
+    it("returns warn when not installed", async () => {
+      // #given comment checker not installed
+      checkSpy = spyOn(deps, "checkCommentChecker").mockResolvedValue({
+        name: "Comment Checker",
+        required: false,
+        installed: false,
+        version: null,
+        path: null,
+        installHint: "Hook will be disabled if not available",
+      })
+
+      // #when checking
+      const result = await deps.checkDependencyCommentChecker()
+
+      // #then should warn
+      expect(result.status).toBe("warn")
+    })
+  })
+
+  describe("getDependencyCheckDefinitions", () => {
+    it("returns definitions for all dependencies", () => {
+      // #given
+      // #when getting definitions
+      const defs = deps.getDependencyCheckDefinitions()
+
+      // #then should have 3 definitions
+      expect(defs.length).toBe(3)
+      expect(defs.every((d) => d.category === "dependencies")).toBe(true)
+      expect(defs.every((d) => d.critical === false)).toBe(true)
+    })
+  })
+})

src/cli/doctor/checks/dependencies.ts

@@ -0,0 +1,163 @@
+import type { CheckResult, CheckDefinition, DependencyInfo } from "../types"
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+
+async function checkBinaryExists(binary: string): Promise<{ exists: boolean; path: string | null }> {
+  try {
+    const proc = Bun.spawn(["which", binary], { stdout: "pipe", stderr: "pipe" })
+    const output = await new Response(proc.stdout).text()
+    await proc.exited
+    if (proc.exitCode === 0) {
+      return { exists: true, path: output.trim() }
+    }
+  } catch {
+    // intentionally empty - binary not found
+  }
+  return { exists: false, path: null }
+}
+
+async function getBinaryVersion(binary: string): Promise<string | null> {
+  try {
+    const proc = Bun.spawn([binary, "--version"], { stdout: "pipe", stderr: "pipe" })
+    const output = await new Response(proc.stdout).text()
+    await proc.exited
+    if (proc.exitCode === 0) {
+      return output.trim().split("\n")[0]
+    }
+  } catch {
+    // intentionally empty - version unavailable
+  }
+  return null
+}
+
+export async function checkAstGrepCli(): Promise<DependencyInfo> {
+  const binaryCheck = await checkBinaryExists("sg")
+  const altBinaryCheck = !binaryCheck.exists ? await checkBinaryExists("ast-grep") : null
+
+  const binary = binaryCheck.exists ? binaryCheck : altBinaryCheck
+  if (!binary || !binary.exists) {
+    return {
+      name: "AST-Grep CLI",
+      required: false,
+      installed: false,
+      version: null,
+      path: null,
+      installHint: "Install: npm install -g @ast-grep/cli",
+    }
+  }
+
+  const version = await getBinaryVersion(binary.path!)
+
+  return {
+    name: "AST-Grep CLI",
+    required: false,
+    installed: true,
+    version,
+    path: binary.path,
+  }
+}
+
+export function checkAstGrepNapi(): DependencyInfo {
+  try {
+    require.resolve("@ast-grep/napi")
+    return {
+      name: "AST-Grep NAPI",
+      required: false,
+      installed: true,
+      version: null,
+      path: null,
+    }
+  } catch {
+    return {
+      name: "AST-Grep NAPI",
+      required: false,
+      installed: false,
+      version: null,
+      path: null,
+      installHint: "Will use CLI fallback if available",
+    }
+  }
+}
+
+export async function checkCommentChecker(): Promise<DependencyInfo> {
+  const binaryCheck = await checkBinaryExists("comment-checker")
+
+  if (!binaryCheck.exists) {
+    return {
+      name: "Comment Checker",
+      required: false,
+      installed: false,
+      version: null,
+      path: null,
+      installHint: "Hook will be disabled if not available",
+    }
+  }
+
+  const version = await getBinaryVersion("comment-checker")
+
+  return {
+    name: "Comment Checker",
+    required: false,
+    installed: true,
+    version,
+    path: binaryCheck.path,
+  }
+}
+
+function dependencyToCheckResult(dep: DependencyInfo, checkName: string): CheckResult {
+  if (dep.installed) {
+    return {
+      name: checkName,
+      status: "pass",
+      message: dep.version ?? "installed",
+      details: dep.path ? [`Path: ${dep.path}`] : undefined,
+    }
+  }
+
+  return {
+    name: checkName,
+    status: "warn",
+    message: "Not installed (optional)",
+    details: dep.installHint ? [dep.installHint] : undefined,
+  }
+}
+
+export async function checkDependencyAstGrepCli(): Promise<CheckResult> {
+  const info = await checkAstGrepCli()
+  return dependencyToCheckResult(info, CHECK_NAMES[CHECK_IDS.DEP_AST_GREP_CLI])
+}
+
+export async function checkDependencyAstGrepNapi(): Promise<CheckResult> {
+  const info = checkAstGrepNapi()
+  return dependencyToCheckResult(info, CHECK_NAMES[CHECK_IDS.DEP_AST_GREP_NAPI])
+}
+
+export async function checkDependencyCommentChecker(): Promise<CheckResult> {
+  const info = await checkCommentChecker()
+  return dependencyToCheckResult(info, CHECK_NAMES[CHECK_IDS.DEP_COMMENT_CHECKER])
+}
+
+export function getDependencyCheckDefinitions(): CheckDefinition[] {
+  return [
+    {
+      id: CHECK_IDS.DEP_AST_GREP_CLI,
+      name: CHECK_NAMES[CHECK_IDS.DEP_AST_GREP_CLI],
+      category: "dependencies",
+      check: checkDependencyAstGrepCli,
+      critical: false,
+    },
+    {
+      id: CHECK_IDS.DEP_AST_GREP_NAPI,
+      name: CHECK_NAMES[CHECK_IDS.DEP_AST_GREP_NAPI],
+      category: "dependencies",
+      check: checkDependencyAstGrepNapi,
+      critical: false,
+    },
+    {
+      id: CHECK_IDS.DEP_COMMENT_CHECKER,
+      name: CHECK_NAMES[CHECK_IDS.DEP_COMMENT_CHECKER],
+      category: "dependencies",
+      check: checkDependencyCommentChecker,
+      critical: false,
+    },
+  ]
+}

src/cli/doctor/checks/gh.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as gh from "./gh"
+
+describe("gh cli check", () => {
+  describe("getGhCliInfo", () => {
+    it("returns gh cli info structure", async () => {
+      // #given
+      // #when checking gh cli info
+      const info = await gh.getGhCliInfo()
+
+      // #then should return valid info structure
+      expect(typeof info.installed).toBe("boolean")
+      expect(info.authenticated === true || info.authenticated === false).toBe(true)
+      expect(Array.isArray(info.scopes)).toBe(true)
+    })
+  })
+
+  describe("checkGhCli", () => {
+    let getInfoSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getInfoSpy?.mockRestore()
+    })
+
+    it("returns warn when gh is not installed", async () => {
+      // #given gh not installed
+      getInfoSpy = spyOn(gh, "getGhCliInfo").mockResolvedValue({
+        installed: false,
+        version: null,
+        path: null,
+        authenticated: false,
+        username: null,
+        scopes: [],
+        error: null,
+      })
+
+      // #when checking
+      const result = await gh.checkGhCli()
+
+      // #then should warn (optional)
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("Not installed")
+      expect(result.details).toContain("Install: https://cli.github.com/")
+    })
+
+    it("returns warn when gh is installed but not authenticated", async () => {
+      // #given gh installed but not authenticated
+      getInfoSpy = spyOn(gh, "getGhCliInfo").mockResolvedValue({
+        installed: true,
+        version: "2.40.0",
+        path: "/usr/local/bin/gh",
+        authenticated: false,
+        username: null,
+        scopes: [],
+        error: "not logged in",
+      })
+
+      // #when checking
+      const result = await gh.checkGhCli()
+
+      // #then should warn about auth
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("2.40.0")
+      expect(result.message).toContain("not authenticated")
+      expect(result.details).toContain("Authenticate: gh auth login")
+    })
+
+    it("returns pass when gh is installed and authenticated", async () => {
+      // #given gh installed and authenticated
+      getInfoSpy = spyOn(gh, "getGhCliInfo").mockResolvedValue({
+        installed: true,
+        version: "2.40.0",
+        path: "/usr/local/bin/gh",
+        authenticated: true,
+        username: "octocat",
+        scopes: ["repo", "read:org"],
+        error: null,
+      })
+
+      // #when checking
+      const result = await gh.checkGhCli()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("2.40.0")
+      expect(result.message).toContain("octocat")
+      expect(result.details).toContain("Account: octocat")
+      expect(result.details).toContain("Scopes: repo, read:org")
+    })
+  })
+
+  describe("getGhCliCheckDefinition", () => {
+    it("returns correct check definition", () => {
+      // #given
+      // #when getting definition
+      const def = gh.getGhCliCheckDefinition()
+
+      // #then should have correct properties
+      expect(def.id).toBe("gh-cli")
+      expect(def.name).toBe("GitHub CLI")
+      expect(def.category).toBe("tools")
+      expect(def.critical).toBe(false)
+      expect(typeof def.check).toBe("function")
+    })
+  })
+})

src/cli/doctor/checks/gh.ts

@@ -0,0 +1,171 @@
+import type { CheckResult, CheckDefinition } from "../types"
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+
+export interface GhCliInfo {
+  installed: boolean
+  version: string | null
+  path: string | null
+  authenticated: boolean
+  username: string | null
+  scopes: string[]
+  error: string | null
+}
+
+async function checkBinaryExists(binary: string): Promise<{ exists: boolean; path: string | null }> {
+  try {
+    const proc = Bun.spawn(["which", binary], { stdout: "pipe", stderr: "pipe" })
+    const output = await new Response(proc.stdout).text()
+    await proc.exited
+    if (proc.exitCode === 0) {
+      return { exists: true, path: output.trim() }
+    }
+  } catch {
+    // intentionally empty - binary not found
+  }
+  return { exists: false, path: null }
+}
+
+async function getGhVersion(): Promise<string | null> {
+  try {
+    const proc = Bun.spawn(["gh", "--version"], { stdout: "pipe", stderr: "pipe" })
+    const output = await new Response(proc.stdout).text()
+    await proc.exited
+    if (proc.exitCode === 0) {
+      const match = output.match(/gh version (\S+)/)
+      return match?.[1] ?? output.trim().split("\n")[0]
+    }
+  } catch {
+    // intentionally empty - version unavailable
+  }
+  return null
+}
+
+async function getGhAuthStatus(): Promise<{
+  authenticated: boolean
+  username: string | null
+  scopes: string[]
+  error: string | null
+}> {
+  try {
+    const proc = Bun.spawn(["gh", "auth", "status"], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...process.env, GH_NO_UPDATE_NOTIFIER: "1" },
+    })
+    const stdout = await new Response(proc.stdout).text()
+    const stderr = await new Response(proc.stderr).text()
+    await proc.exited
+
+    const output = stderr || stdout
+
+    if (proc.exitCode === 0) {
+      const usernameMatch = output.match(/Logged in to github\.com account (\S+)/)
+      const username = usernameMatch?.[1]?.replace(/[()]/g, "") ?? null
+
+      const scopesMatch = output.match(/Token scopes?:\s*(.+)/i)
+      const scopes = scopesMatch?.[1]
+        ? scopesMatch[1]
+            .split(/,\s*/)
+            .map((s) => s.replace(/['"]/g, "").trim())
+            .filter(Boolean)
+        : []
+
+      return { authenticated: true, username, scopes, error: null }
+    }
+
+    const errorMatch = output.match(/error[:\s]+(.+)/i)
+    return {
+      authenticated: false,
+      username: null,
+      scopes: [],
+      error: errorMatch?.[1]?.trim() ?? "Not authenticated",
+    }
+  } catch (err) {
+    return {
+      authenticated: false,
+      username: null,
+      scopes: [],
+      error: err instanceof Error ? err.message : "Failed to check auth status",
+    }
+  }
+}
+
+export async function getGhCliInfo(): Promise<GhCliInfo> {
+  const binaryCheck = await checkBinaryExists("gh")
+
+  if (!binaryCheck.exists) {
+    return {
+      installed: false,
+      version: null,
+      path: null,
+      authenticated: false,
+      username: null,
+      scopes: [],
+      error: null,
+    }
+  }
+
+  const [version, authStatus] = await Promise.all([getGhVersion(), getGhAuthStatus()])
+
+  return {
+    installed: true,
+    version,
+    path: binaryCheck.path,
+    authenticated: authStatus.authenticated,
+    username: authStatus.username,
+    scopes: authStatus.scopes,
+    error: authStatus.error,
+  }
+}
+
+export async function checkGhCli(): Promise<CheckResult> {
+  const info = await getGhCliInfo()
+  const name = CHECK_NAMES[CHECK_IDS.GH_CLI]
+
+  if (!info.installed) {
+    return {
+      name,
+      status: "warn",
+      message: "Not installed (optional)",
+      details: [
+        "GitHub CLI is used by librarian agent and scripts",
+        "Install: https://cli.github.com/",
+      ],
+    }
+  }
+
+  if (!info.authenticated) {
+    return {
+      name,
+      status: "warn",
+      message: `${info.version ?? "installed"} - not authenticated`,
+      details: [
+        info.path ? `Path: ${info.path}` : null,
+        "Authenticate: gh auth login",
+        info.error ? `Error: ${info.error}` : null,
+      ].filter((d): d is string => d !== null),
+    }
+  }
+
+  const details: string[] = []
+  if (info.path) details.push(`Path: ${info.path}`)
+  if (info.username) details.push(`Account: ${info.username}`)
+  if (info.scopes.length > 0) details.push(`Scopes: ${info.scopes.join(", ")}`)
+
+  return {
+    name,
+    status: "pass",
+    message: `${info.version ?? "installed"} - authenticated as ${info.username ?? "unknown"}`,
+    details: details.length > 0 ? details : undefined,
+  }
+}
+
+export function getGhCliCheckDefinition(): CheckDefinition {
+  return {
+    id: CHECK_IDS.GH_CLI,
+    name: CHECK_NAMES[CHECK_IDS.GH_CLI],
+    category: "tools",
+    check: checkGhCli,
+    critical: false,
+  }
+}

src/cli/doctor/checks/index.ts

@@ -0,0 +1,34 @@
+import type { CheckDefinition } from "../types"
+import { getOpenCodeCheckDefinition } from "./opencode"
+import { getPluginCheckDefinition } from "./plugin"
+import { getConfigCheckDefinition } from "./config"
+import { getAuthCheckDefinitions } from "./auth"
+import { getDependencyCheckDefinitions } from "./dependencies"
+import { getGhCliCheckDefinition } from "./gh"
+import { getLspCheckDefinition } from "./lsp"
+import { getMcpCheckDefinitions } from "./mcp"
+import { getVersionCheckDefinition } from "./version"
+
+export * from "./opencode"
+export * from "./plugin"
+export * from "./config"
+export * from "./auth"
+export * from "./dependencies"
+export * from "./gh"
+export * from "./lsp"
+export * from "./mcp"
+export * from "./version"
+
+export function getAllCheckDefinitions(): CheckDefinition[] {
+  return [
+    getOpenCodeCheckDefinition(),
+    getPluginCheckDefinition(),
+    getConfigCheckDefinition(),
+    ...getAuthCheckDefinitions(),
+    ...getDependencyCheckDefinitions(),
+    getGhCliCheckDefinition(),
+    getLspCheckDefinition(),
+    ...getMcpCheckDefinitions(),
+    getVersionCheckDefinition(),
+  ]
+}

src/cli/doctor/checks/lsp.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as lsp from "./lsp"
+import type { LspServerInfo } from "../types"
+
+describe("lsp check", () => {
+  describe("getLspServersInfo", () => {
+    it("returns array of server info", async () => {
+      // #given
+      // #when getting servers info
+      const servers = await lsp.getLspServersInfo()
+
+      // #then should return array with expected structure
+      expect(Array.isArray(servers)).toBe(true)
+      servers.forEach((s) => {
+        expect(s.id).toBeDefined()
+        expect(typeof s.installed).toBe("boolean")
+        expect(Array.isArray(s.extensions)).toBe(true)
+      })
+    })
+  })
+
+  describe("getLspServerStats", () => {
+    it("counts installed servers correctly", () => {
+      // #given servers with mixed installation status
+      const servers = [
+        { id: "ts", installed: true, extensions: [".ts"], source: "builtin" as const },
+        { id: "py", installed: false, extensions: [".py"], source: "builtin" as const },
+        { id: "go", installed: true, extensions: [".go"], source: "builtin" as const },
+      ]
+
+      // #when getting stats
+      const stats = lsp.getLspServerStats(servers)
+
+      // #then should count correctly
+      expect(stats.installed).toBe(2)
+      expect(stats.total).toBe(3)
+    })
+
+    it("handles empty array", () => {
+      // #given no servers
+      const servers: LspServerInfo[] = []
+
+      // #when getting stats
+      const stats = lsp.getLspServerStats(servers)
+
+      // #then should return zeros
+      expect(stats.installed).toBe(0)
+      expect(stats.total).toBe(0)
+    })
+  })
+
+  describe("checkLspServers", () => {
+    let getServersSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getServersSpy?.mockRestore()
+    })
+
+    it("returns warn when no servers installed", async () => {
+      // #given no servers installed
+      getServersSpy = spyOn(lsp, "getLspServersInfo").mockResolvedValue([
+        { id: "typescript-language-server", installed: false, extensions: [".ts"], source: "builtin" },
+        { id: "pyright", installed: false, extensions: [".py"], source: "builtin" },
+      ])
+
+      // #when checking
+      const result = await lsp.checkLspServers()
+
+      // #then should warn
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("No LSP servers")
+    })
+
+    it("returns pass when servers installed", async () => {
+      // #given some servers installed
+      getServersSpy = spyOn(lsp, "getLspServersInfo").mockResolvedValue([
+        { id: "typescript-language-server", installed: true, extensions: [".ts"], source: "builtin" },
+        { id: "pyright", installed: false, extensions: [".py"], source: "builtin" },
+      ])
+
+      // #when checking
+      const result = await lsp.checkLspServers()
+
+      // #then should pass with count
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("1/2")
+    })
+
+    it("lists installed and missing servers in details", async () => {
+      // #given mixed installation
+      getServersSpy = spyOn(lsp, "getLspServersInfo").mockResolvedValue([
+        { id: "typescript-language-server", installed: true, extensions: [".ts"], source: "builtin" },
+        { id: "pyright", installed: false, extensions: [".py"], source: "builtin" },
+      ])
+
+      // #when checking
+      const result = await lsp.checkLspServers()
+
+      // #then should list both
+      expect(result.details?.some((d) => d.includes("Installed"))).toBe(true)
+      expect(result.details?.some((d) => d.includes("Not found"))).toBe(true)
+    })
+  })
+
+  describe("getLspCheckDefinition", () => {
+    it("returns valid check definition", () => {
+      // #given
+      // #when getting definition
+      const def = lsp.getLspCheckDefinition()
+
+      // #then should have required properties
+      expect(def.id).toBe("lsp-servers")
+      expect(def.category).toBe("tools")
+      expect(def.critical).toBe(false)
+    })
+  })
+})

src/cli/doctor/checks/lsp.ts

@@ -0,0 +1,85 @@
+import type { CheckResult, CheckDefinition, LspServerInfo } from "../types"
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+
+const DEFAULT_LSP_SERVERS: Array<{
+  id: string
+  binary: string
+  extensions: string[]
+}> = [
+  { id: "typescript-language-server", binary: "typescript-language-server", extensions: [".ts", ".tsx", ".js", ".jsx"] },
+  { id: "pyright", binary: "pyright-langserver", extensions: [".py"] },
+  { id: "rust-analyzer", binary: "rust-analyzer", extensions: [".rs"] },
+  { id: "gopls", binary: "gopls", extensions: [".go"] },
+]
+
+async function checkBinaryExists(binary: string): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(["which", binary], { stdout: "pipe", stderr: "pipe" })
+    await proc.exited
+    return proc.exitCode === 0
+  } catch {
+    return false
+  }
+}
+
+export async function getLspServersInfo(): Promise<LspServerInfo[]> {
+  const servers: LspServerInfo[] = []
+
+  for (const server of DEFAULT_LSP_SERVERS) {
+    const installed = await checkBinaryExists(server.binary)
+    servers.push({
+      id: server.id,
+      installed,
+      extensions: server.extensions,
+      source: "builtin",
+    })
+  }
+
+  return servers
+}
+
+export function getLspServerStats(servers: LspServerInfo[]): { installed: number; total: number } {
+  const installed = servers.filter((s) => s.installed).length
+  return { installed, total: servers.length }
+}
+
+export async function checkLspServers(): Promise<CheckResult> {
+  const servers = await getLspServersInfo()
+  const stats = getLspServerStats(servers)
+  const installedServers = servers.filter((s) => s.installed)
+  const missingServers = servers.filter((s) => !s.installed)
+
+  if (stats.installed === 0) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.LSP_SERVERS],
+      status: "warn",
+      message: "No LSP servers detected",
+      details: [
+        "LSP tools will have limited functionality",
+        ...missingServers.map((s) => `Missing: ${s.id}`),
+      ],
+    }
+  }
+
+  const details = [
+    ...installedServers.map((s) => `Installed: ${s.id}`),
+    ...missingServers.map((s) => `Not found: ${s.id} (optional)`),
+  ]
+
+  return {
+    name: CHECK_NAMES[CHECK_IDS.LSP_SERVERS],
+    status: "pass",
+    message: `${stats.installed}/${stats.total} servers available`,
+    details,
+  }
+}
+
+export function getLspCheckDefinition(): CheckDefinition {
+  return {
+    id: CHECK_IDS.LSP_SERVERS,
+    name: CHECK_NAMES[CHECK_IDS.LSP_SERVERS],
+    category: "tools",
+    check: checkLspServers,
+    critical: false,
+  }
+}

src/cli/doctor/checks/mcp.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as mcp from "./mcp"
+
+describe("mcp check", () => {
+  describe("getBuiltinMcpInfo", () => {
+    it("returns builtin servers", () => {
+      // #given
+      // #when getting builtin info
+      const servers = mcp.getBuiltinMcpInfo()
+
+      // #then should include expected servers
+      expect(servers.length).toBe(3)
+      expect(servers.every((s) => s.type === "builtin")).toBe(true)
+      expect(servers.every((s) => s.enabled === true)).toBe(true)
+      expect(servers.map((s) => s.id)).toContain("context7")
+      expect(servers.map((s) => s.id)).toContain("websearch_exa")
+      expect(servers.map((s) => s.id)).toContain("grep_app")
+    })
+  })
+
+  describe("getUserMcpInfo", () => {
+    it("returns empty array when no user config", () => {
+      // #given no user config exists
+      // #when getting user info
+      const servers = mcp.getUserMcpInfo()
+
+      // #then should return array (may be empty)
+      expect(Array.isArray(servers)).toBe(true)
+    })
+  })
+
+  describe("checkBuiltinMcpServers", () => {
+    it("returns pass with server count", async () => {
+      // #given
+      // #when checking builtin servers
+      const result = await mcp.checkBuiltinMcpServers()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("3")
+      expect(result.message).toContain("enabled")
+    })
+
+    it("lists enabled servers in details", async () => {
+      // #given
+      // #when checking builtin servers
+      const result = await mcp.checkBuiltinMcpServers()
+
+      // #then should list servers
+      expect(result.details?.some((d) => d.includes("context7"))).toBe(true)
+      expect(result.details?.some((d) => d.includes("websearch_exa"))).toBe(true)
+      expect(result.details?.some((d) => d.includes("grep_app"))).toBe(true)
+    })
+  })
+
+  describe("checkUserMcpServers", () => {
+    let getUserSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getUserSpy?.mockRestore()
+    })
+
+    it("returns skip when no user config", async () => {
+      // #given no user servers
+      getUserSpy = spyOn(mcp, "getUserMcpInfo").mockReturnValue([])
+
+      // #when checking
+      const result = await mcp.checkUserMcpServers()
+
+      // #then should skip
+      expect(result.status).toBe("skip")
+      expect(result.message).toContain("No user MCP")
+    })
+
+    it("returns pass when valid user servers", async () => {
+      // #given valid user servers
+      getUserSpy = spyOn(mcp, "getUserMcpInfo").mockReturnValue([
+        { id: "custom-mcp", type: "user", enabled: true, valid: true },
+      ])
+
+      // #when checking
+      const result = await mcp.checkUserMcpServers()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("1")
+    })
+
+    it("returns warn when servers have issues", async () => {
+      // #given invalid server config
+      getUserSpy = spyOn(mcp, "getUserMcpInfo").mockReturnValue([
+        { id: "bad-mcp", type: "user", enabled: true, valid: false, error: "Missing command" },
+      ])
+
+      // #when checking
+      const result = await mcp.checkUserMcpServers()
+
+      // #then should warn
+      expect(result.status).toBe("warn")
+      expect(result.details?.some((d) => d.includes("Invalid"))).toBe(true)
+    })
+  })
+
+  describe("getMcpCheckDefinitions", () => {
+    it("returns definitions for builtin and user", () => {
+      // #given
+      // #when getting definitions
+      const defs = mcp.getMcpCheckDefinitions()
+
+      // #then should have 2 definitions
+      expect(defs.length).toBe(2)
+      expect(defs.every((d) => d.category === "tools")).toBe(true)
+      expect(defs.map((d) => d.id)).toContain("mcp-builtin")
+      expect(defs.map((d) => d.id)).toContain("mcp-user")
+    })
+  })
+})

src/cli/doctor/checks/mcp.ts

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import type { CheckResult, CheckDefinition, McpServerInfo } from "../types"
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+import { parseJsonc } from "../../../shared"
+
+const BUILTIN_MCP_SERVERS = ["context7", "websearch_exa", "grep_app"]
+
+const MCP_CONFIG_PATHS = [
+  join(homedir(), ".claude", ".mcp.json"),
+  join(process.cwd(), ".mcp.json"),
+  join(process.cwd(), ".claude", ".mcp.json"),
+]
+
+interface McpConfig {
+  mcpServers?: Record<string, unknown>
+}
+
+function loadUserMcpConfig(): Record<string, unknown> {
+  const servers: Record<string, unknown> = {}
+
+  for (const configPath of MCP_CONFIG_PATHS) {
+    if (!existsSync(configPath)) continue
+
+    try {
+      const content = readFileSync(configPath, "utf-8")
+      const config = parseJsonc<McpConfig>(content)
+      if (config.mcpServers) {
+        Object.assign(servers, config.mcpServers)
+      }
+    } catch {
+      // intentionally empty - skip invalid configs
+    }
+  }
+
+  return servers
+}
+
+export function getBuiltinMcpInfo(): McpServerInfo[] {
+  return BUILTIN_MCP_SERVERS.map((id) => ({
+    id,
+    type: "builtin" as const,
+    enabled: true,
+    valid: true,
+  }))
+}
+
+export function getUserMcpInfo(): McpServerInfo[] {
+  const userServers = loadUserMcpConfig()
+  const servers: McpServerInfo[] = []
+
+  for (const [id, config] of Object.entries(userServers)) {
+    const isValid = typeof config === "object" && config !== null
+    servers.push({
+      id,
+      type: "user",
+      enabled: true,
+      valid: isValid,
+      error: isValid ? undefined : "Invalid configuration format",
+    })
+  }
+
+  return servers
+}
+
+export async function checkBuiltinMcpServers(): Promise<CheckResult> {
+  const servers = getBuiltinMcpInfo()
+
+  return {
+    name: CHECK_NAMES[CHECK_IDS.MCP_BUILTIN],
+    status: "pass",
+    message: `${servers.length} built-in servers enabled`,
+    details: servers.map((s) => `Enabled: ${s.id}`),
+  }
+}
+
+export async function checkUserMcpServers(): Promise<CheckResult> {
+  const servers = getUserMcpInfo()
+
+  if (servers.length === 0) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.MCP_USER],
+      status: "skip",
+      message: "No user MCP configuration found",
+      details: ["Optional: Add .mcp.json for custom MCP servers"],
+    }
+  }
+
+  const invalidServers = servers.filter((s) => !s.valid)
+  if (invalidServers.length > 0) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.MCP_USER],
+      status: "warn",
+      message: `${invalidServers.length} server(s) have configuration issues`,
+      details: [
+        ...servers.filter((s) => s.valid).map((s) => `Valid: ${s.id}`),
+        ...invalidServers.map((s) => `Invalid: ${s.id} - ${s.error}`),
+      ],
+    }
+  }
+
+  return {
+    name: CHECK_NAMES[CHECK_IDS.MCP_USER],
+    status: "pass",
+    message: `${servers.length} user server(s) configured`,
+    details: servers.map((s) => `Configured: ${s.id}`),
+  }
+}
+
+export function getMcpCheckDefinitions(): CheckDefinition[] {
+  return [
+    {
+      id: CHECK_IDS.MCP_BUILTIN,
+      name: CHECK_NAMES[CHECK_IDS.MCP_BUILTIN],
+      category: "tools",
+      check: checkBuiltinMcpServers,
+      critical: false,
+    },
+    {
+      id: CHECK_IDS.MCP_USER,
+      name: CHECK_NAMES[CHECK_IDS.MCP_USER],
+      category: "tools",
+      check: checkUserMcpServers,
+      critical: false,
+    },
+  ]
+}

src/cli/doctor/checks/opencode.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect, spyOn, beforeEach, afterEach } from "bun:test"
+import * as opencode from "./opencode"
+import { MIN_OPENCODE_VERSION } from "../constants"
+
+describe("opencode check", () => {
+  describe("compareVersions", () => {
+    it("returns true when current >= minimum", () => {
+      // #given versions where current is greater
+      // #when comparing
+      // #then should return true
+      expect(opencode.compareVersions("1.0.200", "1.0.150")).toBe(true)
+      expect(opencode.compareVersions("1.1.0", "1.0.150")).toBe(true)
+      expect(opencode.compareVersions("2.0.0", "1.0.150")).toBe(true)
+    })
+
+    it("returns true when versions are equal", () => {
+      // #given equal versions
+      // #when comparing
+      // #then should return true
+      expect(opencode.compareVersions("1.0.150", "1.0.150")).toBe(true)
+    })
+
+    it("returns false when current < minimum", () => {
+      // #given version below minimum
+      // #when comparing
+      // #then should return false
+      expect(opencode.compareVersions("1.0.100", "1.0.150")).toBe(false)
+      expect(opencode.compareVersions("0.9.0", "1.0.150")).toBe(false)
+    })
+
+    it("handles version prefixes", () => {
+      // #given version with v prefix
+      // #when comparing
+      // #then should strip prefix and compare correctly
+      expect(opencode.compareVersions("v1.0.200", "1.0.150")).toBe(true)
+    })
+
+    it("handles prerelease versions", () => {
+      // #given prerelease version
+      // #when comparing
+      // #then should use base version
+      expect(opencode.compareVersions("1.0.200-beta.1", "1.0.150")).toBe(true)
+    })
+  })
+
+  describe("getOpenCodeInfo", () => {
+    it("returns installed: false when binary not found", async () => {
+      // #given no opencode binary
+      const spy = spyOn(opencode, "findOpenCodeBinary").mockResolvedValue(null)
+
+      // #when getting info
+      const info = await opencode.getOpenCodeInfo()
+
+      // #then should indicate not installed
+      expect(info.installed).toBe(false)
+      expect(info.version).toBeNull()
+      expect(info.path).toBeNull()
+      expect(info.binary).toBeNull()
+
+      spy.mockRestore()
+    })
+  })
+
+  describe("checkOpenCodeInstallation", () => {
+    let getInfoSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getInfoSpy?.mockRestore()
+    })
+
+    it("returns fail when not installed", async () => {
+      // #given opencode not installed
+      getInfoSpy = spyOn(opencode, "getOpenCodeInfo").mockResolvedValue({
+        installed: false,
+        version: null,
+        path: null,
+        binary: null,
+      })
+
+      // #when checking installation
+      const result = await opencode.checkOpenCodeInstallation()
+
+      // #then should fail with installation hint
+      expect(result.status).toBe("fail")
+      expect(result.message).toContain("not installed")
+      expect(result.details).toBeDefined()
+      expect(result.details?.some((d) => d.includes("opencode.ai"))).toBe(true)
+    })
+
+    it("returns warn when version below minimum", async () => {
+      // #given old version installed
+      getInfoSpy = spyOn(opencode, "getOpenCodeInfo").mockResolvedValue({
+        installed: true,
+        version: "1.0.100",
+        path: "/usr/local/bin/opencode",
+        binary: "opencode",
+      })
+
+      // #when checking installation
+      const result = await opencode.checkOpenCodeInstallation()
+
+      // #then should warn about old version
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("below minimum")
+      expect(result.details?.some((d) => d.includes(MIN_OPENCODE_VERSION))).toBe(true)
+    })
+
+    it("returns pass when properly installed", async () => {
+      // #given current version installed
+      getInfoSpy = spyOn(opencode, "getOpenCodeInfo").mockResolvedValue({
+        installed: true,
+        version: "1.0.200",
+        path: "/usr/local/bin/opencode",
+        binary: "opencode",
+      })
+
+      // #when checking installation
+      const result = await opencode.checkOpenCodeInstallation()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("1.0.200")
+    })
+  })
+
+  describe("getOpenCodeCheckDefinition", () => {
+    it("returns valid check definition", () => {
+      // #given
+      // #when getting definition
+      const def = opencode.getOpenCodeCheckDefinition()
+
+      // #then should have required properties
+      expect(def.id).toBe("opencode-installation")
+      expect(def.category).toBe("installation")
+      expect(def.critical).toBe(true)
+      expect(typeof def.check).toBe("function")
+    })
+  })
+})

src/cli/doctor/checks/opencode.ts

@@ -0,0 +1,118 @@
+import type { CheckResult, CheckDefinition, OpenCodeInfo } from "../types"
+import { CHECK_IDS, CHECK_NAMES, MIN_OPENCODE_VERSION, OPENCODE_BINARIES } from "../constants"
+
+export async function findOpenCodeBinary(): Promise<{ binary: string; path: string } | null> {
+  for (const binary of OPENCODE_BINARIES) {
+    try {
+      const proc = Bun.spawn(["which", binary], { stdout: "pipe", stderr: "pipe" })
+      const output = await new Response(proc.stdout).text()
+      await proc.exited
+      if (proc.exitCode === 0) {
+        return { binary, path: output.trim() }
+      }
+    } catch {
+      continue
+    }
+  }
+  return null
+}
+
+export async function getOpenCodeVersion(binary: string): Promise<string | null> {
+  try {
+    const proc = Bun.spawn([binary, "--version"], { stdout: "pipe", stderr: "pipe" })
+    const output = await new Response(proc.stdout).text()
+    await proc.exited
+    if (proc.exitCode === 0) {
+      return output.trim()
+    }
+  } catch {
+    return null
+  }
+  return null
+}
+
+export function compareVersions(current: string, minimum: string): boolean {
+  const parseVersion = (v: string): number[] => {
+    const cleaned = v.replace(/^v/, "").split("-")[0]
+    return cleaned.split(".").map((n) => parseInt(n, 10) || 0)
+  }
+
+  const curr = parseVersion(current)
+  const min = parseVersion(minimum)
+
+  for (let i = 0; i < Math.max(curr.length, min.length); i++) {
+    const c = curr[i] ?? 0
+    const m = min[i] ?? 0
+    if (c > m) return true
+    if (c < m) return false
+  }
+  return true
+}
+
+export async function getOpenCodeInfo(): Promise<OpenCodeInfo> {
+  const binaryInfo = await findOpenCodeBinary()
+
+  if (!binaryInfo) {
+    return {
+      installed: false,
+      version: null,
+      path: null,
+      binary: null,
+    }
+  }
+
+  const version = await getOpenCodeVersion(binaryInfo.binary)
+
+  return {
+    installed: true,
+    version,
+    path: binaryInfo.path,
+    binary: binaryInfo.binary as "opencode" | "opencode-desktop",
+  }
+}
+
+export async function checkOpenCodeInstallation(): Promise<CheckResult> {
+  const info = await getOpenCodeInfo()
+
+  if (!info.installed) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.OPENCODE_INSTALLATION],
+      status: "fail",
+      message: "OpenCode is not installed",
+      details: [
+        "Visit: https://opencode.ai/docs for installation instructions",
+        "Run: npm install -g opencode",
+      ],
+    }
+  }
+
+  if (info.version && !compareVersions(info.version, MIN_OPENCODE_VERSION)) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.OPENCODE_INSTALLATION],
+      status: "warn",
+      message: `Version ${info.version} is below minimum ${MIN_OPENCODE_VERSION}`,
+      details: [
+        `Current: ${info.version}`,
+        `Required: >= ${MIN_OPENCODE_VERSION}`,
+        "Run: npm update -g opencode",
+      ],
+    }
+  }
+
+  return {
+    name: CHECK_NAMES[CHECK_IDS.OPENCODE_INSTALLATION],
+    status: "pass",
+    message: info.version ?? "installed",
+    details: info.path ? [`Path: ${info.path}`] : undefined,
+  }
+}
+
+export function getOpenCodeCheckDefinition(): CheckDefinition {
+  return {
+    id: CHECK_IDS.OPENCODE_INSTALLATION,
+    name: CHECK_NAMES[CHECK_IDS.OPENCODE_INSTALLATION],
+    category: "installation",
+    check: checkOpenCodeInstallation,
+    critical: true,
+  }
+}

src/cli/doctor/checks/plugin.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as plugin from "./plugin"
+
+describe("plugin check", () => {
+  describe("getPluginInfo", () => {
+    it("returns registered: false when config not found", () => {
+      // #given no config file exists
+      // #when getting plugin info
+      // #then should indicate not registered
+      const info = plugin.getPluginInfo()
+      expect(typeof info.registered).toBe("boolean")
+      expect(typeof info.isPinned).toBe("boolean")
+    })
+  })
+
+  describe("checkPluginRegistration", () => {
+    let getInfoSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getInfoSpy?.mockRestore()
+    })
+
+    it("returns fail when config file not found", async () => {
+      // #given no config file
+      getInfoSpy = spyOn(plugin, "getPluginInfo").mockReturnValue({
+        registered: false,
+        configPath: null,
+        entry: null,
+        isPinned: false,
+        pinnedVersion: null,
+      })
+
+      // #when checking registration
+      const result = await plugin.checkPluginRegistration()
+
+      // #then should fail with hint
+      expect(result.status).toBe("fail")
+      expect(result.message).toContain("not found")
+    })
+
+    it("returns fail when plugin not registered", async () => {
+      // #given config exists but plugin not registered
+      getInfoSpy = spyOn(plugin, "getPluginInfo").mockReturnValue({
+        registered: false,
+        configPath: "/home/user/.config/opencode/opencode.json",
+        entry: null,
+        isPinned: false,
+        pinnedVersion: null,
+      })
+
+      // #when checking registration
+      const result = await plugin.checkPluginRegistration()
+
+      // #then should fail
+      expect(result.status).toBe("fail")
+      expect(result.message).toContain("not registered")
+    })
+
+    it("returns pass when plugin registered", async () => {
+      // #given plugin registered
+      getInfoSpy = spyOn(plugin, "getPluginInfo").mockReturnValue({
+        registered: true,
+        configPath: "/home/user/.config/opencode/opencode.json",
+        entry: "oh-my-opencode",
+        isPinned: false,
+        pinnedVersion: null,
+      })
+
+      // #when checking registration
+      const result = await plugin.checkPluginRegistration()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("Registered")
+    })
+
+    it("indicates pinned version when applicable", async () => {
+      // #given plugin pinned to version
+      getInfoSpy = spyOn(plugin, "getPluginInfo").mockReturnValue({
+        registered: true,
+        configPath: "/home/user/.config/opencode/opencode.json",
+        entry: "oh-my-opencode@2.7.0",
+        isPinned: true,
+        pinnedVersion: "2.7.0",
+      })
+
+      // #when checking registration
+      const result = await plugin.checkPluginRegistration()
+
+      // #then should show pinned version
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("pinned")
+      expect(result.message).toContain("2.7.0")
+    })
+  })
+
+  describe("getPluginCheckDefinition", () => {
+    it("returns valid check definition", () => {
+      // #given
+      // #when getting definition
+      const def = plugin.getPluginCheckDefinition()
+
+      // #then should have required properties
+      expect(def.id).toBe("plugin-registration")
+      expect(def.category).toBe("installation")
+      expect(def.critical).toBe(true)
+    })
+  })
+})

src/cli/doctor/checks/plugin.ts

@@ -0,0 +1,127 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import type { CheckResult, CheckDefinition, PluginInfo } from "../types"
+import { CHECK_IDS, CHECK_NAMES, PACKAGE_NAME } from "../constants"
+import { parseJsonc } from "../../../shared"
+
+const OPENCODE_CONFIG_DIR = join(homedir(), ".config", "opencode")
+const OPENCODE_JSON = join(OPENCODE_CONFIG_DIR, "opencode.json")
+const OPENCODE_JSONC = join(OPENCODE_CONFIG_DIR, "opencode.jsonc")
+
+function detectConfigPath(): { path: string; format: "json" | "jsonc" } | null {
+  if (existsSync(OPENCODE_JSONC)) {
+    return { path: OPENCODE_JSONC, format: "jsonc" }
+  }
+  if (existsSync(OPENCODE_JSON)) {
+    return { path: OPENCODE_JSON, format: "json" }
+  }
+  return null
+}
+
+function findPluginEntry(plugins: string[]): { entry: string; isPinned: boolean; version: string | null } | null {
+  for (const plugin of plugins) {
+    if (plugin === PACKAGE_NAME || plugin.startsWith(`${PACKAGE_NAME}@`)) {
+      const isPinned = plugin.includes("@")
+      const version = isPinned ? plugin.split("@")[1] : null
+      return { entry: plugin, isPinned, version }
+    }
+  }
+  return null
+}
+
+export function getPluginInfo(): PluginInfo {
+  const configInfo = detectConfigPath()
+
+  if (!configInfo) {
+    return {
+      registered: false,
+      configPath: null,
+      entry: null,
+      isPinned: false,
+      pinnedVersion: null,
+    }
+  }
+
+  try {
+    const content = readFileSync(configInfo.path, "utf-8")
+    const config = parseJsonc<{ plugin?: string[] }>(content)
+    const plugins = config.plugin ?? []
+    const pluginEntry = findPluginEntry(plugins)
+
+    if (!pluginEntry) {
+      return {
+        registered: false,
+        configPath: configInfo.path,
+        entry: null,
+        isPinned: false,
+        pinnedVersion: null,
+      }
+    }
+
+    return {
+      registered: true,
+      configPath: configInfo.path,
+      entry: pluginEntry.entry,
+      isPinned: pluginEntry.isPinned,
+      pinnedVersion: pluginEntry.version,
+    }
+  } catch {
+    return {
+      registered: false,
+      configPath: configInfo.path,
+      entry: null,
+      isPinned: false,
+      pinnedVersion: null,
+    }
+  }
+}
+
+export async function checkPluginRegistration(): Promise<CheckResult> {
+  const info = getPluginInfo()
+
+  if (!info.configPath) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.PLUGIN_REGISTRATION],
+      status: "fail",
+      message: "OpenCode config file not found",
+      details: [
+        "Run: bunx oh-my-opencode install",
+        `Expected: ${OPENCODE_JSON} or ${OPENCODE_JSONC}`,
+      ],
+    }
+  }
+
+  if (!info.registered) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.PLUGIN_REGISTRATION],
+      status: "fail",
+      message: "Plugin not registered in config",
+      details: [
+        "Run: bunx oh-my-opencode install",
+        `Config: ${info.configPath}`,
+      ],
+    }
+  }
+
+  const message = info.isPinned
+    ? `Registered (pinned: ${info.pinnedVersion})`
+    : "Registered"
+
+  return {
+    name: CHECK_NAMES[CHECK_IDS.PLUGIN_REGISTRATION],
+    status: "pass",
+    message,
+    details: [`Config: ${info.configPath}`],
+  }
+}
+
+export function getPluginCheckDefinition(): CheckDefinition {
+  return {
+    id: CHECK_IDS.PLUGIN_REGISTRATION,
+    name: CHECK_NAMES[CHECK_IDS.PLUGIN_REGISTRATION],
+    category: "installation",
+    check: checkPluginRegistration,
+    critical: true,
+  }
+}

src/cli/doctor/checks/version.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as version from "./version"
+
+describe("version check", () => {
+  describe("getVersionInfo", () => {
+    it("returns version check info structure", async () => {
+      // #given
+      // #when getting version info
+      const info = await version.getVersionInfo()
+
+      // #then should have expected structure
+      expect(typeof info.isUpToDate).toBe("boolean")
+      expect(typeof info.isLocalDev).toBe("boolean")
+      expect(typeof info.isPinned).toBe("boolean")
+    })
+  })
+
+  describe("checkVersionStatus", () => {
+    let getInfoSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getInfoSpy?.mockRestore()
+    })
+
+    it("returns pass when in local dev mode", async () => {
+      // #given local dev mode
+      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
+        currentVersion: "local-dev",
+        latestVersion: "2.7.0",
+        isUpToDate: true,
+        isLocalDev: true,
+        isPinned: false,
+      })
+
+      // #when checking
+      const result = await version.checkVersionStatus()
+
+      // #then should pass with dev message
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("local development")
+    })
+
+    it("returns pass when pinned", async () => {
+      // #given pinned version
+      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
+        currentVersion: "2.6.0",
+        latestVersion: "2.7.0",
+        isUpToDate: true,
+        isLocalDev: false,
+        isPinned: true,
+      })
+
+      // #when checking
+      const result = await version.checkVersionStatus()
+
+      // #then should pass with pinned message
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("Pinned")
+    })
+
+    it("returns warn when unable to determine version", async () => {
+      // #given no version info
+      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
+        currentVersion: null,
+        latestVersion: "2.7.0",
+        isUpToDate: false,
+        isLocalDev: false,
+        isPinned: false,
+      })
+
+      // #when checking
+      const result = await version.checkVersionStatus()
+
+      // #then should warn
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("Unable to determine")
+    })
+
+    it("returns warn when network error", async () => {
+      // #given network error
+      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
+        currentVersion: "2.6.0",
+        latestVersion: null,
+        isUpToDate: true,
+        isLocalDev: false,
+        isPinned: false,
+      })
+
+      // #when checking
+      const result = await version.checkVersionStatus()
+
+      // #then should warn
+      expect(result.status).toBe("warn")
+      expect(result.details?.some((d) => d.includes("network"))).toBe(true)
+    })
+
+    it("returns warn when update available", async () => {
+      // #given update available
+      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
+        currentVersion: "2.6.0",
+        latestVersion: "2.7.0",
+        isUpToDate: false,
+        isLocalDev: false,
+        isPinned: false,
+      })
+
+      // #when checking
+      const result = await version.checkVersionStatus()
+
+      // #then should warn with update info
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("Update available")
+      expect(result.message).toContain("2.6.0")
+      expect(result.message).toContain("2.7.0")
+    })
+
+    it("returns pass when up to date", async () => {
+      // #given up to date
+      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
+        currentVersion: "2.7.0",
+        latestVersion: "2.7.0",
+        isUpToDate: true,
+        isLocalDev: false,
+        isPinned: false,
+      })
+
+      // #when checking
+      const result = await version.checkVersionStatus()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("Up to date")
+    })
+  })
+
+  describe("getVersionCheckDefinition", () => {
+    it("returns valid check definition", () => {
+      // #given
+      // #when getting definition
+      const def = version.getVersionCheckDefinition()
+
+      // #then should have required properties
+      expect(def.id).toBe("version-status")
+      expect(def.category).toBe("updates")
+      expect(def.critical).toBe(false)
+    })
+  })
+})

src/cli/doctor/checks/version.ts

@@ -0,0 +1,133 @@
+import type { CheckResult, CheckDefinition, VersionCheckInfo } from "../types"
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+import {
+  getCachedVersion,
+  getLatestVersion,
+  isLocalDevMode,
+  findPluginEntry,
+} from "../../../hooks/auto-update-checker/checker"
+
+function compareVersions(current: string, latest: string): boolean {
+  const parseVersion = (v: string): number[] => {
+    const cleaned = v.replace(/^v/, "").split("-")[0]
+    return cleaned.split(".").map((n) => parseInt(n, 10) || 0)
+  }
+
+  const curr = parseVersion(current)
+  const lat = parseVersion(latest)
+
+  for (let i = 0; i < Math.max(curr.length, lat.length); i++) {
+    const c = curr[i] ?? 0
+    const l = lat[i] ?? 0
+    if (c < l) return false
+    if (c > l) return true
+  }
+  return true
+}
+
+export async function getVersionInfo(): Promise<VersionCheckInfo> {
+  const cwd = process.cwd()
+
+  if (isLocalDevMode(cwd)) {
+    return {
+      currentVersion: "local-dev",
+      latestVersion: null,
+      isUpToDate: true,
+      isLocalDev: true,
+      isPinned: false,
+    }
+  }
+
+  const pluginInfo = findPluginEntry(cwd)
+  if (pluginInfo?.isPinned) {
+    return {
+      currentVersion: pluginInfo.pinnedVersion,
+      latestVersion: null,
+      isUpToDate: true,
+      isLocalDev: false,
+      isPinned: true,
+    }
+  }
+
+  const currentVersion = getCachedVersion()
+  const latestVersion = await getLatestVersion()
+
+  const isUpToDate =
+    !currentVersion ||
+    !latestVersion ||
+    compareVersions(currentVersion, latestVersion)
+
+  return {
+    currentVersion,
+    latestVersion,
+    isUpToDate,
+    isLocalDev: false,
+    isPinned: false,
+  }
+}
+
+export async function checkVersionStatus(): Promise<CheckResult> {
+  const info = await getVersionInfo()
+
+  if (info.isLocalDev) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
+      status: "pass",
+      message: "Running in local development mode",
+      details: ["Using file:// protocol from config"],
+    }
+  }
+
+  if (info.isPinned) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
+      status: "pass",
+      message: `Pinned to version ${info.currentVersion}`,
+      details: ["Update check skipped for pinned versions"],
+    }
+  }
+
+  if (!info.currentVersion) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
+      status: "warn",
+      message: "Unable to determine current version",
+      details: ["Run: bunx oh-my-opencode get-local-version"],
+    }
+  }
+
+  if (!info.latestVersion) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
+      status: "warn",
+      message: `Current: ${info.currentVersion}`,
+      details: ["Unable to check for updates (network error)"],
+    }
+  }
+
+  if (!info.isUpToDate) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
+      status: "warn",
+      message: `Update available: ${info.currentVersion} -> ${info.latestVersion}`,
+      details: ["Run: cd ~/.config/opencode && bun update oh-my-opencode"],
+    }
+  }
+
+  return {
+    name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
+    status: "pass",
+    message: `Up to date (${info.currentVersion})`,
+    details: info.latestVersion ? [`Latest: ${info.latestVersion}`] : undefined,
+  }
+}
+
+export function getVersionCheckDefinition(): CheckDefinition {
+  return {
+    id: CHECK_IDS.VERSION_STATUS,
+    name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
+    category: "updates",
+    check: checkVersionStatus,
+    critical: false,
+  }
+}

src/cli/doctor/constants.ts

@@ -0,0 +1,72 @@
+import color from "picocolors"
+
+export const SYMBOLS = {
+  check: color.green("\u2713"),
+  cross: color.red("\u2717"),
+  warn: color.yellow("\u26A0"),
+  info: color.blue("\u2139"),
+  arrow: color.cyan("\u2192"),
+  bullet: color.dim("\u2022"),
+  skip: color.dim("\u25CB"),
+} as const
+
+export const STATUS_COLORS = {
+  pass: color.green,
+  fail: color.red,
+  warn: color.yellow,
+  skip: color.dim,
+} as const
+
+export const CHECK_IDS = {
+  OPENCODE_INSTALLATION: "opencode-installation",
+  PLUGIN_REGISTRATION: "plugin-registration",
+  CONFIG_VALIDATION: "config-validation",
+  AUTH_ANTHROPIC: "auth-anthropic",
+  AUTH_OPENAI: "auth-openai",
+  AUTH_GOOGLE: "auth-google",
+  DEP_AST_GREP_CLI: "dep-ast-grep-cli",
+  DEP_AST_GREP_NAPI: "dep-ast-grep-napi",
+  DEP_COMMENT_CHECKER: "dep-comment-checker",
+  GH_CLI: "gh-cli",
+  LSP_SERVERS: "lsp-servers",
+  MCP_BUILTIN: "mcp-builtin",
+  MCP_USER: "mcp-user",
+  VERSION_STATUS: "version-status",
+} as const
+
+export const CHECK_NAMES: Record<string, string> = {
+  [CHECK_IDS.OPENCODE_INSTALLATION]: "OpenCode Installation",
+  [CHECK_IDS.PLUGIN_REGISTRATION]: "Plugin Registration",
+  [CHECK_IDS.CONFIG_VALIDATION]: "Configuration Validity",
+  [CHECK_IDS.AUTH_ANTHROPIC]: "Anthropic (Claude) Auth",
+  [CHECK_IDS.AUTH_OPENAI]: "OpenAI (ChatGPT) Auth",
+  [CHECK_IDS.AUTH_GOOGLE]: "Google (Gemini) Auth",
+  [CHECK_IDS.DEP_AST_GREP_CLI]: "AST-Grep CLI",
+  [CHECK_IDS.DEP_AST_GREP_NAPI]: "AST-Grep NAPI",
+  [CHECK_IDS.DEP_COMMENT_CHECKER]: "Comment Checker",
+  [CHECK_IDS.GH_CLI]: "GitHub CLI",
+  [CHECK_IDS.LSP_SERVERS]: "LSP Servers",
+  [CHECK_IDS.MCP_BUILTIN]: "Built-in MCP Servers",
+  [CHECK_IDS.MCP_USER]: "User MCP Configuration",
+  [CHECK_IDS.VERSION_STATUS]: "Version Status",
+} as const
+
+export const CATEGORY_NAMES: Record<string, string> = {
+  installation: "Installation",
+  configuration: "Configuration",
+  authentication: "Authentication",
+  dependencies: "Dependencies",
+  tools: "Tools & Servers",
+  updates: "Updates",
+} as const
+
+export const EXIT_CODES = {
+  SUCCESS: 0,
+  FAILURE: 1,
+} as const
+
+export const MIN_OPENCODE_VERSION = "1.0.150"
+
+export const PACKAGE_NAME = "oh-my-opencode"
+
+export const OPENCODE_BINARIES = ["opencode", "opencode-desktop"] as const

src/cli/doctor/formatter.test.ts

@@ -0,0 +1,218 @@
+import { describe, it, expect } from "bun:test"
+import {
+  formatStatusSymbol,
+  formatCheckResult,
+  formatCategoryHeader,
+  formatSummary,
+  formatHeader,
+  formatFooter,
+  formatJsonOutput,
+  formatBox,
+  formatHelpSuggestions,
+} from "./formatter"
+import type { CheckResult, DoctorSummary, DoctorResult } from "./types"
+
+describe("formatter", () => {
+  describe("formatStatusSymbol", () => {
+    it("returns green check for pass", () => {
+      const symbol = formatStatusSymbol("pass")
+      expect(symbol).toContain("\u2713")
+    })
+
+    it("returns red cross for fail", () => {
+      const symbol = formatStatusSymbol("fail")
+      expect(symbol).toContain("\u2717")
+    })
+
+    it("returns yellow warning for warn", () => {
+      const symbol = formatStatusSymbol("warn")
+      expect(symbol).toContain("\u26A0")
+    })
+
+    it("returns dim circle for skip", () => {
+      const symbol = formatStatusSymbol("skip")
+      expect(symbol).toContain("\u25CB")
+    })
+  })
+
+  describe("formatCheckResult", () => {
+    it("includes name and message", () => {
+      const result: CheckResult = {
+        name: "Test Check",
+        status: "pass",
+        message: "All good",
+      }
+
+      const output = formatCheckResult(result, false)
+
+      expect(output).toContain("Test Check")
+      expect(output).toContain("All good")
+    })
+
+    it("includes details when verbose", () => {
+      const result: CheckResult = {
+        name: "Test Check",
+        status: "pass",
+        message: "OK",
+        details: ["Detail 1", "Detail 2"],
+      }
+
+      const output = formatCheckResult(result, true)
+
+      expect(output).toContain("Detail 1")
+      expect(output).toContain("Detail 2")
+    })
+
+    it("hides details when not verbose", () => {
+      const result: CheckResult = {
+        name: "Test Check",
+        status: "pass",
+        message: "OK",
+        details: ["Detail 1"],
+      }
+
+      const output = formatCheckResult(result, false)
+
+      expect(output).not.toContain("Detail 1")
+    })
+  })
+
+  describe("formatCategoryHeader", () => {
+    it("formats category name with styling", () => {
+      const header = formatCategoryHeader("installation")
+
+      expect(header).toContain("Installation")
+    })
+  })
+
+  describe("formatSummary", () => {
+    it("shows all counts", () => {
+      const summary: DoctorSummary = {
+        total: 10,
+        passed: 7,
+        failed: 1,
+        warnings: 2,
+        skipped: 0,
+        duration: 150,
+      }
+
+      const output = formatSummary(summary)
+
+      expect(output).toContain("7 passed")
+      expect(output).toContain("1 failed")
+      expect(output).toContain("2 warnings")
+      expect(output).toContain("10 checks")
+      expect(output).toContain("150ms")
+    })
+  })
+
+  describe("formatHeader", () => {
+    it("includes doctor branding", () => {
+      const header = formatHeader()
+
+      expect(header).toContain("Doctor")
+    })
+  })
+
+  describe("formatFooter", () => {
+    it("shows error message when failures", () => {
+      const summary: DoctorSummary = {
+        total: 5,
+        passed: 4,
+        failed: 1,
+        warnings: 0,
+        skipped: 0,
+        duration: 100,
+      }
+
+      const footer = formatFooter(summary)
+
+      expect(footer).toContain("Issues detected")
+    })
+
+    it("shows warning message when warnings only", () => {
+      const summary: DoctorSummary = {
+        total: 5,
+        passed: 4,
+        failed: 0,
+        warnings: 1,
+        skipped: 0,
+        duration: 100,
+      }
+
+      const footer = formatFooter(summary)
+
+      expect(footer).toContain("warnings")
+    })
+
+    it("shows success message when all pass", () => {
+      const summary: DoctorSummary = {
+        total: 5,
+        passed: 5,
+        failed: 0,
+        warnings: 0,
+        skipped: 0,
+        duration: 100,
+      }
+
+      const footer = formatFooter(summary)
+
+      expect(footer).toContain("operational")
+    })
+  })
+
+  describe("formatJsonOutput", () => {
+    it("returns valid JSON", () => {
+      const result: DoctorResult = {
+        results: [{ name: "Test", status: "pass", message: "OK" }],
+        summary: { total: 1, passed: 1, failed: 0, warnings: 0, skipped: 0, duration: 50 },
+        exitCode: 0,
+      }
+
+      const output = formatJsonOutput(result)
+      const parsed = JSON.parse(output)
+
+      expect(parsed.results.length).toBe(1)
+      expect(parsed.summary.total).toBe(1)
+      expect(parsed.exitCode).toBe(0)
+    })
+  })
+
+  describe("formatBox", () => {
+    it("wraps content in box", () => {
+      const box = formatBox("Test content")
+
+      expect(box).toContain("Test content")
+      expect(box).toContain("\u2500")
+    })
+
+    it("includes title when provided", () => {
+      const box = formatBox("Content", "My Title")
+
+      expect(box).toContain("My Title")
+    })
+  })
+
+  describe("formatHelpSuggestions", () => {
+    it("extracts suggestions from failed checks", () => {
+      const results: CheckResult[] = [
+        { name: "Test", status: "fail", message: "Error", details: ["Run: fix-command"] },
+        { name: "OK", status: "pass", message: "Good" },
+      ]
+
+      const suggestions = formatHelpSuggestions(results)
+
+      expect(suggestions).toContain("Run: fix-command")
+    })
+
+    it("returns empty array when no failures", () => {
+      const results: CheckResult[] = [
+        { name: "OK", status: "pass", message: "Good" },
+      ]
+
+      const suggestions = formatHelpSuggestions(results)
+
+      expect(suggestions.length).toBe(0)
+    })
+  })
+})

src/cli/doctor/formatter.ts

@@ -0,0 +1,140 @@
+import color from "picocolors"
+import type { CheckResult, DoctorSummary, CheckCategory, DoctorResult } from "./types"
+import { SYMBOLS, STATUS_COLORS, CATEGORY_NAMES } from "./constants"
+
+export function formatStatusSymbol(status: CheckResult["status"]): string {
+  switch (status) {
+    case "pass":
+      return SYMBOLS.check
+    case "fail":
+      return SYMBOLS.cross
+    case "warn":
+      return SYMBOLS.warn
+    case "skip":
+      return SYMBOLS.skip
+  }
+}
+
+export function formatCheckResult(result: CheckResult, verbose: boolean): string {
+  const symbol = formatStatusSymbol(result.status)
+  const colorFn = STATUS_COLORS[result.status]
+  const name = colorFn(result.name)
+  const message = color.dim(result.message)
+
+  let line = `  ${symbol} ${name}`
+  if (result.message) {
+    line += ` ${SYMBOLS.arrow} ${message}`
+  }
+
+  if (verbose && result.details && result.details.length > 0) {
+    const detailLines = result.details.map((d) => `      ${SYMBOLS.bullet} ${color.dim(d)}`).join("\n")
+    line += "\n" + detailLines
+  }
+
+  return line
+}
+
+export function formatCategoryHeader(category: CheckCategory): string {
+  const name = CATEGORY_NAMES[category] || category
+  return `\n${color.bold(color.white(name))}\n${color.dim("\u2500".repeat(40))}`
+}
+
+export function formatSummary(summary: DoctorSummary): string {
+  const lines: string[] = []
+
+  lines.push(color.bold(color.white("Summary")))
+  lines.push(color.dim("\u2500".repeat(40)))
+  lines.push("")
+
+  const passText = summary.passed > 0 ? color.green(`${summary.passed} passed`) : color.dim("0 passed")
+  const failText = summary.failed > 0 ? color.red(`${summary.failed} failed`) : color.dim("0 failed")
+  const warnText = summary.warnings > 0 ? color.yellow(`${summary.warnings} warnings`) : color.dim("0 warnings")
+  const skipText = summary.skipped > 0 ? color.dim(`${summary.skipped} skipped`) : ""
+
+  const parts = [passText, failText, warnText]
+  if (skipText) parts.push(skipText)
+
+  lines.push(`  ${parts.join(", ")}`)
+  lines.push(`  ${color.dim(`Total: ${summary.total} checks in ${summary.duration}ms`)}`)
+
+  return lines.join("\n")
+}
+
+export function formatHeader(): string {
+  return `\n${color.bgMagenta(color.white(" oMoMoMoMo... Doctor "))}\n`
+}
+
+export function formatFooter(summary: DoctorSummary): string {
+  if (summary.failed > 0) {
+    return `\n${SYMBOLS.cross} ${color.red("Issues detected. Please review the errors above.")}\n`
+  }
+  if (summary.warnings > 0) {
+    return `\n${SYMBOLS.warn} ${color.yellow("All systems operational with warnings.")}\n`
+  }
+  return `\n${SYMBOLS.check} ${color.green("All systems operational!")}\n`
+}
+
+export function formatProgress(current: number, total: number, name: string): string {
+  const progress = color.dim(`[${current}/${total}]`)
+  return `${progress} Checking ${name}...`
+}
+
+export function formatJsonOutput(result: DoctorResult): string {
+  return JSON.stringify(result, null, 2)
+}
+
+export function formatDetails(details: string[]): string {
+  return details.map((d) => `      ${SYMBOLS.bullet} ${color.dim(d)}`).join("\n")
+}
+
+function stripAnsi(str: string): string {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[0-9;]*m/g, "")
+}
+
+export function formatBox(content: string, title?: string): string {
+  const lines = content.split("\n")
+  const maxWidth = Math.max(...lines.map((l) => stripAnsi(l).length), title?.length ?? 0) + 4
+  const border = color.dim("\u2500".repeat(maxWidth))
+
+  const output: string[] = []
+  output.push("")
+
+  if (title) {
+    output.push(
+      color.dim("\u250C\u2500") +
+        color.bold(` ${title} `) +
+        color.dim("\u2500".repeat(maxWidth - title.length - 4)) +
+        color.dim("\u2510")
+    )
+  } else {
+    output.push(color.dim("\u250C") + border + color.dim("\u2510"))
+  }
+
+  for (const line of lines) {
+    const stripped = stripAnsi(line)
+    const padding = maxWidth - stripped.length
+    output.push(color.dim("\u2502") + ` ${line}${" ".repeat(padding - 1)}` + color.dim("\u2502"))
+  }
+
+  output.push(color.dim("\u2514") + border + color.dim("\u2518"))
+  output.push("")
+
+  return output.join("\n")
+}
+
+export function formatHelpSuggestions(results: CheckResult[]): string[] {
+  const suggestions: string[] = []
+
+  for (const result of results) {
+    if (result.status === "fail" && result.details) {
+      for (const detail of result.details) {
+        if (detail.includes("Run:") || detail.includes("Install:") || detail.includes("Visit:")) {
+          suggestions.push(detail)
+        }
+      }
+    }
+  }
+
+  return suggestions
+}

src/cli/doctor/index.ts

@@ -0,0 +1,11 @@
+import type { DoctorOptions } from "./types"
+import { runDoctor } from "./runner"
+
+export async function doctor(options: DoctorOptions = {}): Promise<number> {
+  const result = await runDoctor(options)
+  return result.exitCode
+}
+
+export * from "./types"
+export { runDoctor } from "./runner"
+export { formatJsonOutput } from "./formatter"

src/cli/doctor/runner.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import {
+  runCheck,
+  calculateSummary,
+  determineExitCode,
+  filterChecksByCategory,
+  groupChecksByCategory,
+} from "./runner"
+import type { CheckResult, CheckDefinition, CheckCategory } from "./types"
+
+describe("runner", () => {
+  describe("runCheck", () => {
+    it("returns result from check function", async () => {
+      const check: CheckDefinition = {
+        id: "test",
+        name: "Test Check",
+        category: "installation",
+        check: async () => ({ name: "Test Check", status: "pass", message: "OK" }),
+      }
+
+      const result = await runCheck(check)
+
+      expect(result.name).toBe("Test Check")
+      expect(result.status).toBe("pass")
+    })
+
+    it("measures duration", async () => {
+      const check: CheckDefinition = {
+        id: "test",
+        name: "Test Check",
+        category: "installation",
+        check: async () => {
+          await new Promise((r) => setTimeout(r, 10))
+          return { name: "Test", status: "pass", message: "OK" }
+        },
+      }
+
+      const result = await runCheck(check)
+
+      expect(result.duration).toBeGreaterThanOrEqual(10)
+    })
+
+    it("returns fail on error", async () => {
+      const check: CheckDefinition = {
+        id: "test",
+        name: "Test Check",
+        category: "installation",
+        check: async () => {
+          throw new Error("Test error")
+        },
+      }
+
+      const result = await runCheck(check)
+
+      expect(result.status).toBe("fail")
+      expect(result.message).toContain("Test error")
+    })
+  })
+
+  describe("calculateSummary", () => {
+    it("counts each status correctly", () => {
+      const results: CheckResult[] = [
+        { name: "1", status: "pass", message: "" },
+        { name: "2", status: "pass", message: "" },
+        { name: "3", status: "fail", message: "" },
+        { name: "4", status: "warn", message: "" },
+        { name: "5", status: "skip", message: "" },
+      ]
+
+      const summary = calculateSummary(results, 100)
+
+      expect(summary.total).toBe(5)
+      expect(summary.passed).toBe(2)
+      expect(summary.failed).toBe(1)
+      expect(summary.warnings).toBe(1)
+      expect(summary.skipped).toBe(1)
+      expect(summary.duration).toBe(100)
+    })
+  })
+
+  describe("determineExitCode", () => {
+    it("returns 0 when all pass", () => {
+      const results: CheckResult[] = [
+        { name: "1", status: "pass", message: "" },
+        { name: "2", status: "pass", message: "" },
+      ]
+
+      expect(determineExitCode(results)).toBe(0)
+    })
+
+    it("returns 0 when only warnings", () => {
+      const results: CheckResult[] = [
+        { name: "1", status: "pass", message: "" },
+        { name: "2", status: "warn", message: "" },
+      ]
+
+      expect(determineExitCode(results)).toBe(0)
+    })
+
+    it("returns 1 when any failures", () => {
+      const results: CheckResult[] = [
+        { name: "1", status: "pass", message: "" },
+        { name: "2", status: "fail", message: "" },
+      ]
+
+      expect(determineExitCode(results)).toBe(1)
+    })
+  })
+
+  describe("filterChecksByCategory", () => {
+    const checks: CheckDefinition[] = [
+      { id: "1", name: "Install", category: "installation", check: async () => ({ name: "", status: "pass", message: "" }) },
+      { id: "2", name: "Config", category: "configuration", check: async () => ({ name: "", status: "pass", message: "" }) },
+      { id: "3", name: "Auth", category: "authentication", check: async () => ({ name: "", status: "pass", message: "" }) },
+    ]
+
+    it("returns all checks when no category", () => {
+      const filtered = filterChecksByCategory(checks)
+
+      expect(filtered.length).toBe(3)
+    })
+
+    it("filters to specific category", () => {
+      const filtered = filterChecksByCategory(checks, "installation")
+
+      expect(filtered.length).toBe(1)
+      expect(filtered[0].name).toBe("Install")
+    })
+  })
+
+  describe("groupChecksByCategory", () => {
+    const checks: CheckDefinition[] = [
+      { id: "1", name: "Install1", category: "installation", check: async () => ({ name: "", status: "pass", message: "" }) },
+      { id: "2", name: "Install2", category: "installation", check: async () => ({ name: "", status: "pass", message: "" }) },
+      { id: "3", name: "Config", category: "configuration", check: async () => ({ name: "", status: "pass", message: "" }) },
+    ]
+
+    it("groups checks by category", () => {
+      const groups = groupChecksByCategory(checks)
+
+      expect(groups.get("installation")?.length).toBe(2)
+      expect(groups.get("configuration")?.length).toBe(1)
+    })
+
+    it("maintains order within categories", () => {
+      const groups = groupChecksByCategory(checks)
+      const installChecks = groups.get("installation")!
+
+      expect(installChecks[0].name).toBe("Install1")
+      expect(installChecks[1].name).toBe("Install2")
+    })
+  })
+})

src/cli/doctor/runner.ts

@@ -0,0 +1,132 @@
+import type {
+  DoctorOptions,
+  DoctorResult,
+  CheckDefinition,
+  CheckResult,
+  DoctorSummary,
+  CheckCategory,
+} from "./types"
+import { getAllCheckDefinitions } from "./checks"
+import { EXIT_CODES, CATEGORY_NAMES } from "./constants"
+import {
+  formatHeader,
+  formatCategoryHeader,
+  formatCheckResult,
+  formatSummary,
+  formatFooter,
+  formatJsonOutput,
+} from "./formatter"
+
+export async function runCheck(check: CheckDefinition): Promise<CheckResult> {
+  const start = performance.now()
+  try {
+    const result = await check.check()
+    result.duration = Math.round(performance.now() - start)
+    return result
+  } catch (err) {
+    return {
+      name: check.name,
+      status: "fail",
+      message: err instanceof Error ? err.message : "Unknown error",
+      duration: Math.round(performance.now() - start),
+    }
+  }
+}
+
+export function calculateSummary(results: CheckResult[], duration: number): DoctorSummary {
+  return {
+    total: results.length,
+    passed: results.filter((r) => r.status === "pass").length,
+    failed: results.filter((r) => r.status === "fail").length,
+    warnings: results.filter((r) => r.status === "warn").length,
+    skipped: results.filter((r) => r.status === "skip").length,
+    duration: Math.round(duration),
+  }
+}
+
+export function determineExitCode(results: CheckResult[]): number {
+  const hasFailures = results.some((r) => r.status === "fail")
+  return hasFailures ? EXIT_CODES.FAILURE : EXIT_CODES.SUCCESS
+}
+
+export function filterChecksByCategory(
+  checks: CheckDefinition[],
+  category?: CheckCategory
+): CheckDefinition[] {
+  if (!category) return checks
+  return checks.filter((c) => c.category === category)
+}
+
+export function groupChecksByCategory(
+  checks: CheckDefinition[]
+): Map<CheckCategory, CheckDefinition[]> {
+  const groups = new Map<CheckCategory, CheckDefinition[]>()
+
+  for (const check of checks) {
+    const existing = groups.get(check.category) ?? []
+    existing.push(check)
+    groups.set(check.category, existing)
+  }
+
+  return groups
+}
+
+const CATEGORY_ORDER: CheckCategory[] = [
+  "installation",
+  "configuration",
+  "authentication",
+  "dependencies",
+  "tools",
+  "updates",
+]
+
+export async function runDoctor(options: DoctorOptions): Promise<DoctorResult> {
+  const start = performance.now()
+  const allChecks = getAllCheckDefinitions()
+  const filteredChecks = filterChecksByCategory(allChecks, options.category)
+  const groupedChecks = groupChecksByCategory(filteredChecks)
+
+  const results: CheckResult[] = []
+
+  if (!options.json) {
+    console.log(formatHeader())
+  }
+
+  for (const category of CATEGORY_ORDER) {
+    const checks = groupedChecks.get(category)
+    if (!checks || checks.length === 0) continue
+
+    if (!options.json) {
+      console.log(formatCategoryHeader(category))
+    }
+
+    for (const check of checks) {
+      const result = await runCheck(check)
+      results.push(result)
+
+      if (!options.json) {
+        console.log(formatCheckResult(result, options.verbose ?? false))
+      }
+    }
+  }
+
+  const duration = performance.now() - start
+  const summary = calculateSummary(results, duration)
+  const exitCode = determineExitCode(results)
+
+  const doctorResult: DoctorResult = {
+    results,
+    summary,
+    exitCode,
+  }
+
+  if (options.json) {
+    console.log(formatJsonOutput(doctorResult))
+  } else {
+    console.log("")
+    console.log(formatSummary(summary))
+    console.log(formatFooter(summary))
+  }
+
+  return doctorResult
+}

src/cli/doctor/types.ts

@@ -0,0 +1,113 @@
+export type CheckStatus = "pass" | "fail" | "warn" | "skip"
+
+export interface CheckResult {
+  name: string
+  status: CheckStatus
+  message: string
+  details?: string[]
+  duration?: number
+}
+
+export type CheckFunction = () => Promise<CheckResult>
+
+export type CheckCategory =
+  | "installation"
+  | "configuration"
+  | "authentication"
+  | "dependencies"
+  | "tools"
+  | "updates"
+
+export interface CheckDefinition {
+  id: string
+  name: string
+  category: CheckCategory
+  check: CheckFunction
+  critical?: boolean
+}
+
+export interface DoctorOptions {
+  verbose?: boolean
+  json?: boolean
+  category?: CheckCategory
+}
+
+export interface DoctorSummary {
+  total: number
+  passed: number
+  failed: number
+  warnings: number
+  skipped: number
+  duration: number
+}
+
+export interface DoctorResult {
+  results: CheckResult[]
+  summary: DoctorSummary
+  exitCode: number
+}
+
+export interface OpenCodeInfo {
+  installed: boolean
+  version: string | null
+  path: string | null
+  binary: "opencode" | "opencode-desktop" | null
+}
+
+export interface PluginInfo {
+  registered: boolean
+  configPath: string | null
+  entry: string | null
+  isPinned: boolean
+  pinnedVersion: string | null
+}
+
+export interface ConfigInfo {
+  exists: boolean
+  path: string | null
+  format: "json" | "jsonc" | null
+  valid: boolean
+  errors: string[]
+}
+
+export type AuthProviderId = "anthropic" | "openai" | "google"
+
+export interface AuthProviderInfo {
+  id: AuthProviderId
+  name: string
+  pluginInstalled: boolean
+  configured: boolean
+  error?: string
+}
+
+export interface DependencyInfo {
+  name: string
+  required: boolean
+  installed: boolean
+  version: string | null
+  path: string | null
+  installHint?: string
+}
+
+export interface LspServerInfo {
+  id: string
+  installed: boolean
+  extensions: string[]
+  source: "builtin" | "config" | "plugin"
+}
+
+export interface McpServerInfo {
+  id: string
+  type: "builtin" | "user"
+  enabled: boolean
+  valid: boolean
+  error?: string
+}
+
+export interface VersionCheckInfo {
+  currentVersion: string | null
+  latestVersion: string | null
+  isUpToDate: boolean
+  isLocalDev: boolean
+  isPinned: boolean
+}

src/cli/get-local-version/formatter.ts

@@ -0,0 +1,66 @@
+import color from "picocolors"
+import type { VersionInfo } from "./types"
+
+const SYMBOLS = {
+  check: color.green("✓"),
+  cross: color.red("✗"),
+  arrow: color.cyan("→"),
+  info: color.blue("ℹ"),
+  warn: color.yellow("⚠"),
+  pin: color.magenta("📌"),
+  dev: color.cyan("🔧"),
+}
+
+export function formatVersionOutput(info: VersionInfo): string {
+  const lines: string[] = []
+
+  lines.push("")
+  lines.push(color.bold(color.white("oh-my-opencode Version Information")))
+  lines.push(color.dim("─".repeat(50)))
+  lines.push("")
+
+  if (info.currentVersion) {
+    lines.push(`  Current Version: ${color.cyan(info.currentVersion)}`)
+  } else {
+    lines.push(`  Current Version: ${color.dim("unknown")}`)
+  }
+
+  if (!info.isLocalDev && info.latestVersion) {
+    lines.push(`  Latest Version:  ${color.cyan(info.latestVersion)}`)
+  }
+
+  lines.push("")
+
+  switch (info.status) {
+    case "up-to-date":
+      lines.push(`  ${SYMBOLS.check} ${color.green("You're up to date!")}`)
+      break
+    case "outdated":
+      lines.push(`  ${SYMBOLS.warn} ${color.yellow("Update available")}`)
+      lines.push(`  ${color.dim("Run:")} ${color.cyan("cd ~/.config/opencode && bun update oh-my-opencode")}`)
+      break
+    case "local-dev":
+      lines.push(`  ${SYMBOLS.dev} ${color.cyan("Running in local development mode")}`)
+      lines.push(`  ${color.dim("Using file:// protocol from config")}`)
+      break
+    case "pinned":
+      lines.push(`  ${SYMBOLS.pin} ${color.magenta(`Version pinned to ${info.pinnedVersion}`)}`)
+      lines.push(`  ${color.dim("Update check skipped for pinned versions")}`)
+      break
+    case "error":
+      lines.push(`  ${SYMBOLS.cross} ${color.red("Unable to check for updates")}`)
+      lines.push(`  ${color.dim("Network error or npm registry unavailable")}`)
+      break
+    case "unknown":
+      lines.push(`  ${SYMBOLS.info} ${color.yellow("Version information unavailable")}`)
+      break
+  }
+
+  lines.push("")
+
+  return lines.join("\n")
+}
+
+export function formatJsonOutput(info: VersionInfo): string {
+  return JSON.stringify(info, null, 2)
+}

src/cli/get-local-version/index.ts

@@ -0,0 +1,104 @@
+import { getCachedVersion, getLatestVersion, isLocalDevMode, findPluginEntry } from "../../hooks/auto-update-checker/checker"
+import type { GetLocalVersionOptions, VersionInfo } from "./types"
+import { formatVersionOutput, formatJsonOutput } from "./formatter"
+
+export async function getLocalVersion(options: GetLocalVersionOptions = {}): Promise<number> {
+  const directory = options.directory ?? process.cwd()
+  
+  try {
+    if (isLocalDevMode(directory)) {
+      const currentVersion = getCachedVersion()
+      const info: VersionInfo = {
+        currentVersion,
+        latestVersion: null,
+        isUpToDate: false,
+        isLocalDev: true,
+        isPinned: false,
+        pinnedVersion: null,
+        status: "local-dev",
+      }
+      
+      console.log(options.json ? formatJsonOutput(info) : formatVersionOutput(info))
+      return 0
+    }
+
+    const pluginInfo = findPluginEntry(directory)
+    if (pluginInfo?.isPinned) {
+      const info: VersionInfo = {
+        currentVersion: pluginInfo.pinnedVersion,
+        latestVersion: null,
+        isUpToDate: false,
+        isLocalDev: false,
+        isPinned: true,
+        pinnedVersion: pluginInfo.pinnedVersion,
+        status: "pinned",
+      }
+      
+      console.log(options.json ? formatJsonOutput(info) : formatVersionOutput(info))
+      return 0
+    }
+
+    const currentVersion = getCachedVersion()
+    if (!currentVersion) {
+      const info: VersionInfo = {
+        currentVersion: null,
+        latestVersion: null,
+        isUpToDate: false,
+        isLocalDev: false,
+        isPinned: false,
+        pinnedVersion: null,
+        status: "unknown",
+      }
+      
+      console.log(options.json ? formatJsonOutput(info) : formatVersionOutput(info))
+      return 1
+    }
+
+    const latestVersion = await getLatestVersion()
+    
+    if (!latestVersion) {
+      const info: VersionInfo = {
+        currentVersion,
+        latestVersion: null,
+        isUpToDate: false,
+        isLocalDev: false,
+        isPinned: false,
+        pinnedVersion: null,
+        status: "error",
+      }
+      
+      console.log(options.json ? formatJsonOutput(info) : formatVersionOutput(info))
+      return 0
+    }
+
+    const isUpToDate = currentVersion === latestVersion
+    const info: VersionInfo = {
+      currentVersion,
+      latestVersion,
+      isUpToDate,
+      isLocalDev: false,
+      isPinned: false,
+      pinnedVersion: null,
+      status: isUpToDate ? "up-to-date" : "outdated",
+    }
+
+    console.log(options.json ? formatJsonOutput(info) : formatVersionOutput(info))
+    return 0
+
+  } catch (error) {
+    const info: VersionInfo = {
+      currentVersion: null,
+      latestVersion: null,
+      isUpToDate: false,
+      isLocalDev: false,
+      isPinned: false,
+      pinnedVersion: null,
+      status: "error",
+    }
+    
+    console.log(options.json ? formatJsonOutput(info) : formatVersionOutput(info))
+    return 1
+  }
+}
+
+export * from "./types"

src/cli/get-local-version/types.ts

@@ -0,0 +1,14 @@
+export interface VersionInfo {
+  currentVersion: string | null
+  latestVersion: string | null
+  isUpToDate: boolean
+  isLocalDev: boolean
+  isPinned: boolean
+  pinnedVersion: string | null
+  status: "up-to-date" | "outdated" | "local-dev" | "pinned" | "error" | "unknown"
+}
+
+export interface GetLocalVersionOptions {
+  directory?: string
+  json?: boolean
+}

src/cli/index.ts

@@ -0,0 +1,144 @@
+#!/usr/bin/env bun
+import { Command } from "commander"
+import { install } from "./install"
+import { run } from "./run"
+import { getLocalVersion } from "./get-local-version"
+import { doctor } from "./doctor"
+import type { InstallArgs } from "./types"
+import type { RunOptions } from "./run"
+import type { GetLocalVersionOptions } from "./get-local-version/types"
+import type { DoctorOptions } from "./doctor"
+
+const packageJson = await import("../../package.json")
+const VERSION = packageJson.version
+
+const program = new Command()
+
+program
+  .name("oh-my-opencode")
+  .description("The ultimate OpenCode plugin - multi-model orchestration, LSP tools, and more")
+  .version(VERSION, "-v, --version", "Show version number")
+
+program
+  .command("install")
+  .description("Install and configure oh-my-opencode with interactive setup")
+  .option("--no-tui", "Run in non-interactive mode (requires all options)")
+  .option("--claude <value>", "Claude subscription: no, yes, max20")
+  .option("--chatgpt <value>", "ChatGPT subscription: no, yes")
+  .option("--gemini <value>", "Gemini integration: no, yes")
+  .option("--skip-auth", "Skip authentication setup hints")
+  .addHelpText("after", `
+Examples:
+  $ bunx oh-my-opencode install
+  $ bunx oh-my-opencode install --no-tui --claude=max20 --chatgpt=yes --gemini=yes
+  $ bunx oh-my-opencode install --no-tui --claude=no --chatgpt=no --gemini=no
+
+Model Providers:
+  Claude      Required for Sisyphus (main orchestrator) and Librarian agents
+  ChatGPT     Powers the Oracle agent for debugging and architecture
+  Gemini      Powers frontend, documentation, and multimodal agents
+`)
+  .action(async (options) => {
+    const args: InstallArgs = {
+      tui: options.tui !== false,
+      claude: options.claude,
+      chatgpt: options.chatgpt,
+      gemini: options.gemini,
+      skipAuth: options.skipAuth ?? false,
+    }
+    const exitCode = await install(args)
+    process.exit(exitCode)
+  })
+
+program
+  .command("run <message>")
+  .description("Run opencode with todo/background task completion enforcement")
+  .option("-a, --agent <name>", "Agent to use (default: Sisyphus)")
+  .option("-d, --directory <path>", "Working directory")
+  .option("-t, --timeout <ms>", "Timeout in milliseconds (default: 30 minutes)", parseInt)
+  .addHelpText("after", `
+Examples:
+  $ bunx oh-my-opencode run "Fix the bug in index.ts"
+  $ bunx oh-my-opencode run --agent Sisyphus "Implement feature X"
+  $ bunx oh-my-opencode run --timeout 3600000 "Large refactoring task"
+
+Unlike 'opencode run', this command waits until:
+  - All todos are completed or cancelled
+  - All child sessions (background tasks) are idle
+`)
+  .action(async (message: string, options) => {
+    const runOptions: RunOptions = {
+      message,
+      agent: options.agent,
+      directory: options.directory,
+      timeout: options.timeout,
+    }
+    const exitCode = await run(runOptions)
+    process.exit(exitCode)
+  })
+
+program
+  .command("get-local-version")
+  .description("Show current installed version and check for updates")
+  .option("-d, --directory <path>", "Working directory to check config from")
+  .option("--json", "Output in JSON format for scripting")
+  .addHelpText("after", `
+Examples:
+  $ bunx oh-my-opencode get-local-version
+  $ bunx oh-my-opencode get-local-version --json
+  $ bunx oh-my-opencode get-local-version --directory /path/to/project
+
+This command shows:
+  - Current installed version
+  - Latest available version on npm
+  - Whether you're up to date
+  - Special modes (local dev, pinned version)
+`)
+  .action(async (options) => {
+    const versionOptions: GetLocalVersionOptions = {
+      directory: options.directory,
+      json: options.json ?? false,
+    }
+    const exitCode = await getLocalVersion(versionOptions)
+    process.exit(exitCode)
+  })
+
+program
+  .command("doctor")
+  .description("Check oh-my-opencode installation health and diagnose issues")
+  .option("--verbose", "Show detailed diagnostic information")
+  .option("--json", "Output results in JSON format")
+  .option("--category <category>", "Run only specific category")
+  .addHelpText("after", `
+Examples:
+  $ bunx oh-my-opencode doctor
+  $ bunx oh-my-opencode doctor --verbose
+  $ bunx oh-my-opencode doctor --json
+  $ bunx oh-my-opencode doctor --category authentication
+
+Categories:
+  installation     Check OpenCode and plugin installation
+  configuration    Validate configuration files
+  authentication   Check auth provider status
+  dependencies     Check external dependencies
+  tools            Check LSP and MCP servers
+  updates          Check for version updates
+`)
+  .action(async (options) => {
+    const doctorOptions: DoctorOptions = {
+      verbose: options.verbose ?? false,
+      json: options.json ?? false,
+      category: options.category,
+    }
+    const exitCode = await doctor(doctorOptions)
+    process.exit(exitCode)
+  })
+
+program
+  .command("version")
+  .description("Show version information")
+  .action(() => {
+    console.log(`oh-my-opencode v${VERSION}`)
+  })
+
+program.parse()

src/cli/install.ts

@@ -0,0 +1,477 @@
+import * as p from "@clack/prompts"
+import color from "picocolors"
+import type { InstallArgs, InstallConfig, ClaudeSubscription, BooleanArg, DetectedConfig } from "./types"
+import {
+  addPluginToOpenCodeConfig,
+  writeOmoConfig,
+  isOpenCodeInstalled,
+  getOpenCodeVersion,
+  addAuthPlugins,
+  setupChatGPTHotfix,
+  runBunInstall,
+  addProviderConfig,
+  detectCurrentConfig,
+} from "./config-manager"
+
+const SYMBOLS = {
+  check: color.green("✓"),
+  cross: color.red("✗"),
+  arrow: color.cyan("→"),
+  bullet: color.dim("•"),
+  info: color.blue("ℹ"),
+  warn: color.yellow("⚠"),
+  star: color.yellow("★"),
+}
+
+function formatProvider(name: string, enabled: boolean, detail?: string): string {
+  const status = enabled ? SYMBOLS.check : color.dim("○")
+  const label = enabled ? color.white(name) : color.dim(name)
+  const suffix = detail ? color.dim(` (${detail})`) : ""
+  return `  ${status} ${label}${suffix}`
+}
+
+function formatConfigSummary(config: InstallConfig): string {
+  const lines: string[] = []
+
+  lines.push(color.bold(color.white("Configuration Summary")))
+  lines.push("")
+
+  const claudeDetail = config.hasClaude ? (config.isMax20 ? "max20" : "standard") : undefined
+  lines.push(formatProvider("Claude", config.hasClaude, claudeDetail))
+  lines.push(formatProvider("ChatGPT", config.hasChatGPT))
+  lines.push(formatProvider("Gemini", config.hasGemini))
+
+  lines.push("")
+  lines.push(color.dim("─".repeat(40)))
+  lines.push("")
+
+  lines.push(color.bold(color.white("Agent Configuration")))
+  lines.push("")
+
+  const sisyphusModel = config.hasClaude ? "claude-opus-4-5" : "big-pickle"
+  const oracleModel = config.hasChatGPT ? "gpt-5.2" : (config.hasClaude ? "claude-opus-4-5" : "big-pickle")
+  const librarianModel = config.hasClaude && config.isMax20 ? "claude-sonnet-4-5" : "big-pickle"
+  const frontendModel = config.hasGemini ? "gemini-3-pro-high" : (config.hasClaude ? "claude-opus-4-5" : "big-pickle")
+
+  lines.push(`  ${SYMBOLS.bullet} Sisyphus     ${SYMBOLS.arrow} ${color.cyan(sisyphusModel)}`)
+  lines.push(`  ${SYMBOLS.bullet} Oracle       ${SYMBOLS.arrow} ${color.cyan(oracleModel)}`)
+  lines.push(`  ${SYMBOLS.bullet} Librarian    ${SYMBOLS.arrow} ${color.cyan(librarianModel)}`)
+  lines.push(`  ${SYMBOLS.bullet} Frontend     ${SYMBOLS.arrow} ${color.cyan(frontendModel)}`)
+
+  return lines.join("\n")
+}
+
+function printHeader(isUpdate: boolean): void {
+  const mode = isUpdate ? "Update" : "Install"
+  console.log()
+  console.log(color.bgMagenta(color.white(` oMoMoMoMo... ${mode} `)))
+  console.log()
+}
+
+function printStep(step: number, total: number, message: string): void {
+  const progress = color.dim(`[${step}/${total}]`)
+  console.log(`${progress} ${message}`)
+}
+
+function printSuccess(message: string): void {
+  console.log(`${SYMBOLS.check} ${message}`)
+}
+
+function printError(message: string): void {
+  console.log(`${SYMBOLS.cross} ${color.red(message)}`)
+}
+
+function printInfo(message: string): void {
+  console.log(`${SYMBOLS.info} ${message}`)
+}
+
+function printWarning(message: string): void {
+  console.log(`${SYMBOLS.warn} ${color.yellow(message)}`)
+}
+
+function printBox(content: string, title?: string): void {
+  const lines = content.split("\n")
+  const maxWidth = Math.max(...lines.map(l => l.replace(/\x1b\[[0-9;]*m/g, "").length), title?.length ?? 0) + 4
+  const border = color.dim("─".repeat(maxWidth))
+
+  console.log()
+  if (title) {
+    console.log(color.dim("┌─") + color.bold(` ${title} `) + color.dim("─".repeat(maxWidth - title.length - 4)) + color.dim("┐"))
+  } else {
+    console.log(color.dim("┌") + border + color.dim("┐"))
+  }
+
+  for (const line of lines) {
+    const stripped = line.replace(/\x1b\[[0-9;]*m/g, "")
+    const padding = maxWidth - stripped.length
+    console.log(color.dim("│") + ` ${line}${" ".repeat(padding - 1)}` + color.dim("│"))
+  }
+
+  console.log(color.dim("└") + border + color.dim("┘"))
+  console.log()
+}
+
+function validateNonTuiArgs(args: InstallArgs): { valid: boolean; errors: string[] } {
+  const errors: string[] = []
+
+  if (args.claude === undefined) {
+    errors.push("--claude is required (values: no, yes, max20)")
+  } else if (!["no", "yes", "max20"].includes(args.claude)) {
+    errors.push(`Invalid --claude value: ${args.claude} (expected: no, yes, max20)`)
+  }
+
+  if (args.chatgpt === undefined) {
+    errors.push("--chatgpt is required (values: no, yes)")
+  } else if (!["no", "yes"].includes(args.chatgpt)) {
+    errors.push(`Invalid --chatgpt value: ${args.chatgpt} (expected: no, yes)`)
+  }
+
+  if (args.gemini === undefined) {
+    errors.push("--gemini is required (values: no, yes)")
+  } else if (!["no", "yes"].includes(args.gemini)) {
+    errors.push(`Invalid --gemini value: ${args.gemini} (expected: no, yes)`)
+  }
+
+  return { valid: errors.length === 0, errors }
+}
+
+function argsToConfig(args: InstallArgs): InstallConfig {
+  return {
+    hasClaude: args.claude !== "no",
+    isMax20: args.claude === "max20",
+    hasChatGPT: args.chatgpt === "yes",
+    hasGemini: args.gemini === "yes",
+  }
+}
+
+function detectedToInitialValues(detected: DetectedConfig): { claude: ClaudeSubscription; chatgpt: BooleanArg; gemini: BooleanArg } {
+  let claude: ClaudeSubscription = "no"
+  if (detected.hasClaude) {
+    claude = detected.isMax20 ? "max20" : "yes"
+  }
+
+  return {
+    claude,
+    chatgpt: detected.hasChatGPT ? "yes" : "no",
+    gemini: detected.hasGemini ? "yes" : "no",
+  }
+}
+
+async function runTuiMode(detected: DetectedConfig): Promise<InstallConfig | null> {
+  const initial = detectedToInitialValues(detected)
+
+  const claude = await p.select({
+    message: "Do you have a Claude Pro/Max subscription?",
+    options: [
+      { value: "no" as const, label: "No", hint: "Will use opencode/big-pickle as fallback" },
+      { value: "yes" as const, label: "Yes (standard)", hint: "Claude Opus 4.5 for orchestration" },
+      { value: "max20" as const, label: "Yes (max20 mode)", hint: "Full power with Claude Sonnet 4.5 for Librarian" },
+    ],
+    initialValue: initial.claude,
+  })
+
+  if (p.isCancel(claude)) {
+    p.cancel("Installation cancelled.")
+    return null
+  }
+
+  const chatgpt = await p.select({
+    message: "Do you have a ChatGPT Plus/Pro subscription?",
+    options: [
+      { value: "no" as const, label: "No", hint: "Oracle will use fallback model" },
+      { value: "yes" as const, label: "Yes", hint: "GPT-5.2 for debugging and architecture" },
+    ],
+    initialValue: initial.chatgpt,
+  })
+
+  if (p.isCancel(chatgpt)) {
+    p.cancel("Installation cancelled.")
+    return null
+  }
+
+  const gemini = await p.select({
+    message: "Will you integrate Google Gemini?",
+    options: [
+      { value: "no" as const, label: "No", hint: "Frontend/docs agents will use fallback" },
+      { value: "yes" as const, label: "Yes", hint: "Beautiful UI generation with Gemini 3 Pro" },
+    ],
+    initialValue: initial.gemini,
+  })
+
+  if (p.isCancel(gemini)) {
+    p.cancel("Installation cancelled.")
+    return null
+  }
+
+  return {
+    hasClaude: claude !== "no",
+    isMax20: claude === "max20",
+    hasChatGPT: chatgpt === "yes",
+    hasGemini: gemini === "yes",
+  }
+}
+
+async function runNonTuiInstall(args: InstallArgs): Promise<number> {
+  const validation = validateNonTuiArgs(args)
+  if (!validation.valid) {
+    printHeader(false)
+    printError("Validation failed:")
+    for (const err of validation.errors) {
+      console.log(`  ${SYMBOLS.bullet} ${err}`)
+    }
+    console.log()
+    printInfo("Usage: bunx oh-my-opencode install --no-tui --claude=<no|yes|max20> --chatgpt=<no|yes> --gemini=<no|yes>")
+    console.log()
+    return 1
+  }
+
+  const detected = detectCurrentConfig()
+  const isUpdate = detected.isInstalled
+
+  printHeader(isUpdate)
+
+  const totalSteps = 6
+  let step = 1
+
+  printStep(step++, totalSteps, "Checking OpenCode installation...")
+  const installed = await isOpenCodeInstalled()
+  if (!installed) {
+    printError("OpenCode is not installed on this system.")
+    printInfo("Visit https://opencode.ai/docs for installation instructions")
+    return 1
+  }
+
+  const version = await getOpenCodeVersion()
+  printSuccess(`OpenCode ${version ?? ""} detected`)
+
+  if (isUpdate) {
+    const initial = detectedToInitialValues(detected)
+    printInfo(`Current config: Claude=${initial.claude}, ChatGPT=${initial.chatgpt}, Gemini=${initial.gemini}`)
+  }
+
+  const config = argsToConfig(args)
+
+  printStep(step++, totalSteps, "Adding oh-my-opencode plugin...")
+  const pluginResult = addPluginToOpenCodeConfig()
+  if (!pluginResult.success) {
+    printError(`Failed: ${pluginResult.error}`)
+    return 1
+  }
+  printSuccess(`Plugin ${isUpdate ? "verified" : "added"} ${SYMBOLS.arrow} ${color.dim(pluginResult.configPath)}`)
+
+  if (config.hasGemini || config.hasChatGPT) {
+    printStep(step++, totalSteps, "Adding auth plugins...")
+    const authResult = await addAuthPlugins(config)
+    if (!authResult.success) {
+      printError(`Failed: ${authResult.error}`)
+      return 1
+    }
+    printSuccess(`Auth plugins configured ${SYMBOLS.arrow} ${color.dim(authResult.configPath)}`)
+
+    printStep(step++, totalSteps, "Adding provider configurations...")
+    const providerResult = addProviderConfig(config)
+    if (!providerResult.success) {
+      printError(`Failed: ${providerResult.error}`)
+      return 1
+    }
+    printSuccess(`Providers configured ${SYMBOLS.arrow} ${color.dim(providerResult.configPath)}`)
+  } else {
+    step += 2
+  }
+
+  if (config.hasChatGPT) {
+    printStep(step++, totalSteps, "Setting up ChatGPT hotfix...")
+    const hotfixResult = setupChatGPTHotfix()
+    if (!hotfixResult.success) {
+      printError(`Failed: ${hotfixResult.error}`)
+      return 1
+    }
+    printSuccess(`Hotfix configured ${SYMBOLS.arrow} ${color.dim(hotfixResult.configPath)}`)
+
+    printInfo("Installing dependencies with bun...")
+    const bunSuccess = await runBunInstall()
+    if (bunSuccess) {
+      printSuccess("Dependencies installed")
+    } else {
+      printWarning("bun install failed - run manually: cd ~/.config/opencode && bun i")
+    }
+  } else {
+    step++
+  }
+
+  printStep(step++, totalSteps, "Writing oh-my-opencode configuration...")
+  const omoResult = writeOmoConfig(config)
+  if (!omoResult.success) {
+    printError(`Failed: ${omoResult.error}`)
+    return 1
+  }
+  printSuccess(`Config written ${SYMBOLS.arrow} ${color.dim(omoResult.configPath)}`)
+
+  printBox(formatConfigSummary(config), isUpdate ? "Updated Configuration" : "Installation Complete")
+
+  if (!config.hasClaude && !config.hasChatGPT && !config.hasGemini) {
+    printWarning("No model providers configured. Using opencode/big-pickle as fallback.")
+  }
+
+  if ((config.hasClaude || config.hasChatGPT || config.hasGemini) && !args.skipAuth) {
+    console.log(color.bold("Next Steps - Authenticate your providers:"))
+    console.log()
+    if (config.hasClaude) {
+      console.log(`  ${SYMBOLS.arrow} ${color.dim("opencode auth login")} ${color.gray("(select Anthropic → Claude Pro/Max)")}`)
+    }
+    if (config.hasChatGPT) {
+      console.log(`  ${SYMBOLS.arrow} ${color.dim("opencode auth login")} ${color.gray("(select OpenAI → ChatGPT Plus/Pro)")}`)
+    }
+    if (config.hasGemini) {
+      console.log(`  ${SYMBOLS.arrow} ${color.dim("opencode auth login")} ${color.gray("(select Google → OAuth with Antigravity)")}`)
+    }
+    console.log()
+  }
+
+  console.log(`${SYMBOLS.star} ${color.bold(color.green(isUpdate ? "Configuration updated!" : "Installation complete!"))}`)
+  console.log(`  Run ${color.cyan("opencode")} to start!`)
+  console.log()
+
+  printBox(
+    `${color.bold("Pro Tip:")} Include ${color.cyan("ultrawork")} (or ${color.cyan("ulw")}) in your prompt.\n` +
+    `All features work like magic—parallel agents, background tasks,\n` +
+    `deep exploration, and relentless execution until completion.`,
+    "🪄 The Magic Word"
+  )
+
+  console.log(`${SYMBOLS.star} ${color.yellow("If you found this helpful, consider starring the repo!")}`)
+  console.log(`  ${color.dim("gh repo star code-yeongyu/oh-my-opencode")}`)
+  console.log()
+  console.log(color.dim("oMoMoMoMo... Enjoy!"))
+  console.log()
+
+  return 0
+}
+
+export async function install(args: InstallArgs): Promise<number> {
+  if (!args.tui) {
+    return runNonTuiInstall(args)
+  }
+
+  const detected = detectCurrentConfig()
+  const isUpdate = detected.isInstalled
+
+  p.intro(color.bgMagenta(color.white(isUpdate ? " oMoMoMoMo... Update " : " oMoMoMoMo... ")))
+
+  if (isUpdate) {
+    const initial = detectedToInitialValues(detected)
+    p.log.info(`Existing configuration detected: Claude=${initial.claude}, ChatGPT=${initial.chatgpt}, Gemini=${initial.gemini}`)
+  }
+
+  const s = p.spinner()
+  s.start("Checking OpenCode installation")
+
+  const installed = await isOpenCodeInstalled()
+  if (!installed) {
+    s.stop("OpenCode is not installed")
+    p.log.error("OpenCode is not installed on this system.")
+    p.note("Visit https://opencode.ai/docs for installation instructions", "Installation Guide")
+    p.outro(color.red("Please install OpenCode first."))
+    return 1
+  }
+
+  const version = await getOpenCodeVersion()
+  s.stop(`OpenCode ${version ?? "installed"} ${color.green("✓")}`)
+
+  const config = await runTuiMode(detected)
+  if (!config) return 1
+
+  s.start("Adding oh-my-opencode to OpenCode config")
+  const pluginResult = addPluginToOpenCodeConfig()
+  if (!pluginResult.success) {
+    s.stop(`Failed to add plugin: ${pluginResult.error}`)
+    p.outro(color.red("Installation failed."))
+    return 1
+  }
+  s.stop(`Plugin added to ${color.cyan(pluginResult.configPath)}`)
+
+  if (config.hasGemini || config.hasChatGPT) {
+    s.start("Adding auth plugins (fetching latest versions)")
+    const authResult = await addAuthPlugins(config)
+    if (!authResult.success) {
+      s.stop(`Failed to add auth plugins: ${authResult.error}`)
+      p.outro(color.red("Installation failed."))
+      return 1
+    }
+    s.stop(`Auth plugins added to ${color.cyan(authResult.configPath)}`)
+
+    s.start("Adding provider configurations")
+    const providerResult = addProviderConfig(config)
+    if (!providerResult.success) {
+      s.stop(`Failed to add provider config: ${providerResult.error}`)
+      p.outro(color.red("Installation failed."))
+      return 1
+    }
+    s.stop(`Provider config added to ${color.cyan(providerResult.configPath)}`)
+  }
+
+  if (config.hasChatGPT) {
+    s.start("Setting up ChatGPT hotfix")
+    const hotfixResult = setupChatGPTHotfix()
+    if (!hotfixResult.success) {
+      s.stop(`Failed to setup hotfix: ${hotfixResult.error}`)
+      p.outro(color.red("Installation failed."))
+      return 1
+    }
+    s.stop(`Hotfix configured in ${color.cyan(hotfixResult.configPath)}`)
+
+    s.start("Installing dependencies with bun")
+    const bunSuccess = await runBunInstall()
+    if (bunSuccess) {
+      s.stop("Dependencies installed")
+    } else {
+      s.stop(color.yellow("bun install failed - run manually: cd ~/.config/opencode && bun i"))
+    }
+  }
+
+  s.start("Writing oh-my-opencode configuration")
+  const omoResult = writeOmoConfig(config)
+  if (!omoResult.success) {
+    s.stop(`Failed to write config: ${omoResult.error}`)
+    p.outro(color.red("Installation failed."))
+    return 1
+  }
+  s.stop(`Config written to ${color.cyan(omoResult.configPath)}`)
+
+  if (!config.hasClaude && !config.hasChatGPT && !config.hasGemini) {
+    p.log.warn("No model providers configured. Using opencode/big-pickle as fallback.")
+  }
+
+  p.note(formatConfigSummary(config), isUpdate ? "Updated Configuration" : "Installation Complete")
+
+  if ((config.hasClaude || config.hasChatGPT || config.hasGemini) && !args.skipAuth) {
+    const steps: string[] = []
+    if (config.hasClaude) {
+      steps.push(`${color.dim("opencode auth login")} ${color.gray("(select Anthropic → Claude Pro/Max)")}`)
+    }
+    if (config.hasChatGPT) {
+      steps.push(`${color.dim("opencode auth login")} ${color.gray("(select OpenAI → ChatGPT Plus/Pro)")}`)
+    }
+    if (config.hasGemini) {
+      steps.push(`${color.dim("opencode auth login")} ${color.gray("(select Google → OAuth with Antigravity)")}`)
+    }
+    p.note(steps.join("\n"), "Next Steps - Authenticate your providers")
+  }
+
+  p.log.success(color.bold(isUpdate ? "Configuration updated!" : "Installation complete!"))
+  p.log.message(`Run ${color.cyan("opencode")} to start!`)
+
+  p.note(
+    `Include ${color.cyan("ultrawork")} (or ${color.cyan("ulw")}) in your prompt.\n` +
+    `All features work like magic—parallel agents, background tasks,\n` +
+    `deep exploration, and relentless execution until completion.`,
+    "🪄 The Magic Word"
+  )
+
+  p.log.message(`${color.yellow("★")} If you found this helpful, consider starring the repo!`)
+  p.log.message(`  ${color.dim("gh repo star code-yeongyu/oh-my-opencode")}`)
+
+  p.outro(color.green("oMoMoMoMo... Enjoy!"))
+
+  return 0
+}

src/cli/run/completion.test.ts

@@ -0,0 +1,170 @@
+import { describe, it, expect, mock, spyOn } from "bun:test"
+import type { RunContext, Todo, ChildSession, SessionStatus } from "./types"
+
+const createMockContext = (overrides: {
+  todo?: Todo[]
+  childrenBySession?: Record<string, ChildSession[]>
+  statuses?: Record<string, SessionStatus>
+} = {}): RunContext => {
+  const {
+    todo = [],
+    childrenBySession = { "test-session": [] },
+    statuses = {},
+  } = overrides
+
+  return {
+    client: {
+      session: {
+        todo: mock(() => Promise.resolve({ data: todo })),
+        children: mock((opts: { path: { id: string } }) =>
+          Promise.resolve({ data: childrenBySession[opts.path.id] ?? [] })
+        ),
+        status: mock(() => Promise.resolve({ data: statuses })),
+      },
+    } as unknown as RunContext["client"],
+    sessionID: "test-session",
+    directory: "/test",
+    abortController: new AbortController(),
+  }
+}
+
+describe("checkCompletionConditions", () => {
+  it("returns true when no todos and no children", async () => {
+    // #given
+    spyOn(console, "log").mockImplementation(() => {})
+    const ctx = createMockContext()
+    const { checkCompletionConditions } = await import("./completion")
+
+    // #when
+    const result = await checkCompletionConditions(ctx)
+
+    // #then
+    expect(result).toBe(true)
+  })
+
+  it("returns false when incomplete todos exist", async () => {
+    // #given
+    spyOn(console, "log").mockImplementation(() => {})
+    const ctx = createMockContext({
+      todo: [
+        { id: "1", content: "Done", status: "completed", priority: "high" },
+        { id: "2", content: "WIP", status: "in_progress", priority: "high" },
+      ],
+    })
+    const { checkCompletionConditions } = await import("./completion")
+
+    // #when
+    const result = await checkCompletionConditions(ctx)
+
+    // #then
+    expect(result).toBe(false)
+  })
+
+  it("returns true when all todos completed or cancelled", async () => {
+    // #given
+    spyOn(console, "log").mockImplementation(() => {})
+    const ctx = createMockContext({
+      todo: [
+        { id: "1", content: "Done", status: "completed", priority: "high" },
+        { id: "2", content: "Skip", status: "cancelled", priority: "medium" },
+      ],
+    })
+    const { checkCompletionConditions } = await import("./completion")
+
+    // #when
+    const result = await checkCompletionConditions(ctx)
+
+    // #then
+    expect(result).toBe(true)
+  })
+
+  it("returns false when child session is busy", async () => {
+    // #given
+    spyOn(console, "log").mockImplementation(() => {})
+    const ctx = createMockContext({
+      childrenBySession: {
+        "test-session": [{ id: "child-1" }],
+        "child-1": [],
+      },
+      statuses: { "child-1": { type: "busy" } },
+    })
+    const { checkCompletionConditions } = await import("./completion")
+
+    // #when
+    const result = await checkCompletionConditions(ctx)
+
+    // #then
+    expect(result).toBe(false)
+  })
+
+  it("returns true when all children idle", async () => {
+    // #given
+    spyOn(console, "log").mockImplementation(() => {})
+    const ctx = createMockContext({
+      childrenBySession: {
+        "test-session": [{ id: "child-1" }, { id: "child-2" }],
+        "child-1": [],
+        "child-2": [],
+      },
+      statuses: {
+        "child-1": { type: "idle" },
+        "child-2": { type: "idle" },
+      },
+    })
+    const { checkCompletionConditions } = await import("./completion")
+
+    // #when
+    const result = await checkCompletionConditions(ctx)
+
+    // #then
+    expect(result).toBe(true)
+  })
+
+  it("returns false when grandchild is busy (recursive)", async () => {
+    // #given
+    spyOn(console, "log").mockImplementation(() => {})
+    const ctx = createMockContext({
+      childrenBySession: {
+        "test-session": [{ id: "child-1" }],
+        "child-1": [{ id: "grandchild-1" }],
+        "grandchild-1": [],
+      },
+      statuses: {
+        "child-1": { type: "idle" },
+        "grandchild-1": { type: "busy" },
+      },
+    })
+    const { checkCompletionConditions } = await import("./completion")
+
+    // #when
+    const result = await checkCompletionConditions(ctx)
+
+    // #then
+    expect(result).toBe(false)
+  })
+
+  it("returns true when all descendants idle (recursive)", async () => {
+    // #given
+    spyOn(console, "log").mockImplementation(() => {})
+    const ctx = createMockContext({
+      childrenBySession: {
+        "test-session": [{ id: "child-1" }],
+        "child-1": [{ id: "grandchild-1" }],
+        "grandchild-1": [{ id: "great-grandchild-1" }],
+        "great-grandchild-1": [],
+      },
+      statuses: {
+        "child-1": { type: "idle" },
+        "grandchild-1": { type: "idle" },
+        "great-grandchild-1": { type: "idle" },
+      },
+    })
+    const { checkCompletionConditions } = await import("./completion")
+
+    // #when
+    const result = await checkCompletionConditions(ctx)
+
+    // #then
+    expect(result).toBe(true)
+  })
+})

src/cli/run/completion.ts

@@ -0,0 +1,79 @@
+import pc from "picocolors"
+import type { RunContext, Todo, ChildSession, SessionStatus } from "./types"
+
+export async function checkCompletionConditions(ctx: RunContext): Promise<boolean> {
+  try {
+    if (!await areAllTodosComplete(ctx)) {
+      return false
+    }
+
+    if (!await areAllChildrenIdle(ctx)) {
+      return false
+    }
+
+    return true
+  } catch (err) {
+    console.error(pc.red(`[completion] API error: ${err}`))
+    return false
+  }
+}
+
+async function areAllTodosComplete(ctx: RunContext): Promise<boolean> {
+  const todosRes = await ctx.client.session.todo({ path: { id: ctx.sessionID } })
+  const todos = (todosRes.data ?? []) as Todo[]
+
+  const incompleteTodos = todos.filter(
+    (t) => t.status !== "completed" && t.status !== "cancelled"
+  )
+
+  if (incompleteTodos.length > 0) {
+    console.log(pc.dim(`  Waiting: ${incompleteTodos.length} todos remaining`))
+    return false
+  }
+
+  return true
+}
+
+async function areAllChildrenIdle(ctx: RunContext): Promise<boolean> {
+  const allStatuses = await fetchAllStatuses(ctx)
+  return areAllDescendantsIdle(ctx, ctx.sessionID, allStatuses)
+}
+
+async function fetchAllStatuses(
+  ctx: RunContext
+): Promise<Record<string, SessionStatus>> {
+  const statusRes = await ctx.client.session.status()
+  return (statusRes.data ?? {}) as Record<string, SessionStatus>
+}
+
+async function areAllDescendantsIdle(
+  ctx: RunContext,
+  sessionID: string,
+  allStatuses: Record<string, SessionStatus>
+): Promise<boolean> {
+  const childrenRes = await ctx.client.session.children({
+    path: { id: sessionID },
+  })
+  const children = (childrenRes.data ?? []) as ChildSession[]
+
+  for (const child of children) {
+    const status = allStatuses[child.id]
+    if (status && status.type !== "idle") {
+      console.log(
+        pc.dim(`  Waiting: session ${child.id.slice(0, 8)}... is ${status.type}`)
+      )
+      return false
+    }
+
+    const descendantsIdle = await areAllDescendantsIdle(
+      ctx,
+      child.id,
+      allStatuses
+    )
+    if (!descendantsIdle) {
+      return false
+    }
+  }
+
+  return true
+}

src/cli/run/events.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect } from "bun:test"
+import { createEventState, type EventState } from "./events"
+import type { RunContext, EventPayload } from "./types"
+
+const createMockContext = (sessionID: string = "test-session"): RunContext => ({
+  client: {} as RunContext["client"],
+  sessionID,
+  directory: "/test",
+  abortController: new AbortController(),
+})
+
+async function* toAsyncIterable<T>(items: T[]): AsyncIterable<T> {
+  for (const item of items) {
+    yield item
+  }
+}
+
+describe("createEventState", () => {
+  it("creates initial state with correct defaults", () => {
+    // #given / #when
+    const state = createEventState()
+
+    // #then
+    expect(state.mainSessionIdle).toBe(false)
+    expect(state.lastOutput).toBe("")
+    expect(state.lastPartText).toBe("")
+    expect(state.currentTool).toBe(null)
+  })
+})
+
+describe("event handling", () => {
+  it("session.idle sets mainSessionIdle to true for matching session", async () => {
+    // #given
+    const ctx = createMockContext("my-session")
+    const state = createEventState()
+
+    const payload: EventPayload = {
+      type: "session.idle",
+      properties: { sessionID: "my-session" },
+    }
+
+    const events = toAsyncIterable([payload])
+    const { processEvents } = await import("./events")
+
+    // #when
+    await processEvents(ctx, events, state)
+
+    // #then
+    expect(state.mainSessionIdle).toBe(true)
+  })
+
+  it("session.idle does not affect state for different session", async () => {
+    // #given
+    const ctx = createMockContext("my-session")
+    const state = createEventState()
+
+    const payload: EventPayload = {
+      type: "session.idle",
+      properties: { sessionID: "other-session" },
+    }
+
+    const events = toAsyncIterable([payload])
+    const { processEvents } = await import("./events")
+
+    // #when
+    await processEvents(ctx, events, state)
+
+    // #then
+    expect(state.mainSessionIdle).toBe(false)
+  })
+
+  it("session.status with busy type sets mainSessionIdle to false", async () => {
+    // #given
+    const ctx = createMockContext("my-session")
+    const state: EventState = {
+      mainSessionIdle: true,
+      mainSessionError: false,
+      lastError: null,
+      lastOutput: "",
+      lastPartText: "",
+      currentTool: null,
+    }
+
+    const payload: EventPayload = {
+      type: "session.status",
+      properties: { sessionID: "my-session", status: { type: "busy" } },
+    }
+
+    const events = toAsyncIterable([payload])
+    const { processEvents } = await import("./events")
+
+    // #when
+    await processEvents(ctx, events, state)
+
+    // #then
+    expect(state.mainSessionIdle).toBe(false)
+  })
+})

src/cli/run/events.ts

@@ -0,0 +1,275 @@
+import pc from "picocolors"
+import type {
+  RunContext,
+  EventPayload,
+  SessionIdleProps,
+  SessionStatusProps,
+  SessionErrorProps,
+  MessageUpdatedProps,
+  MessagePartUpdatedProps,
+  ToolExecuteProps,
+  ToolResultProps,
+} from "./types"
+
+export interface EventState {
+  mainSessionIdle: boolean
+  mainSessionError: boolean
+  lastError: string | null
+  lastOutput: string
+  lastPartText: string
+  currentTool: string | null
+}
+
+export function createEventState(): EventState {
+  return {
+    mainSessionIdle: false,
+    mainSessionError: false,
+    lastError: null,
+    lastOutput: "",
+    lastPartText: "",
+    currentTool: null,
+  }
+}
+
+export async function processEvents(
+  ctx: RunContext,
+  stream: AsyncIterable<unknown>,
+  state: EventState
+): Promise<void> {
+  for await (const event of stream) {
+    if (ctx.abortController.signal.aborted) break
+
+    try {
+      const payload = event as EventPayload
+      if (!payload?.type) {
+        console.error(pc.dim(`[event] no type: ${JSON.stringify(event)}`))
+        continue
+      }
+
+      logEventVerbose(ctx, payload)
+
+      handleSessionError(ctx, payload, state)
+      handleSessionIdle(ctx, payload, state)
+      handleSessionStatus(ctx, payload, state)
+      handleMessagePartUpdated(ctx, payload, state)
+      handleMessageUpdated(ctx, payload, state)
+      handleToolExecute(ctx, payload, state)
+      handleToolResult(ctx, payload, state)
+    } catch (err) {
+      console.error(pc.red(`[event error] ${err}`))
+    }
+  }
+}
+
+function logEventVerbose(ctx: RunContext, payload: EventPayload): void {
+  const props = payload.properties as Record<string, unknown> | undefined
+  const info = props?.info as Record<string, unknown> | undefined
+  const sessionID = props?.sessionID ?? info?.sessionID
+  const isMainSession = sessionID === ctx.sessionID
+  const sessionTag = isMainSession
+    ? pc.green("[MAIN]")
+    : pc.yellow(`[${String(sessionID).slice(0, 8)}]`)
+
+  switch (payload.type) {
+    case "session.idle":
+    case "session.status": {
+      const status = (props?.status as { type?: string })?.type ?? "idle"
+      console.error(pc.dim(`${sessionTag} ${payload.type}: ${status}`))
+      break
+    }
+
+    case "message.part.updated": {
+      // Skip verbose logging for partial message updates
+      // Only log tool invocation state changes, not text streaming
+      const partProps = props as MessagePartUpdatedProps | undefined
+      const part = partProps?.part
+      if (part?.type === "tool-invocation") {
+        const toolPart = part as { toolName?: string; state?: string }
+        console.error(
+          pc.dim(`${sessionTag} message.part (tool): ${toolPart.toolName} [${toolPart.state}]`)
+        )
+      }
+      break
+    }
+
+    case "message.updated": {
+      const msgProps = props as MessageUpdatedProps | undefined
+      const role = msgProps?.info?.role ?? "unknown"
+      const content = msgProps?.content ?? ""
+      const preview = content.slice(0, 100).replace(/\n/g, "\\n")
+      console.error(
+        pc.dim(`${sessionTag} message.updated (${role}): "${preview}${content.length > 100 ? "..." : ""}"`)
+      )
+      break
+    }
+
+    case "tool.execute": {
+      const toolProps = props as ToolExecuteProps | undefined
+      const toolName = toolProps?.name ?? "unknown"
+      const input = toolProps?.input ?? {}
+      const inputStr = JSON.stringify(input).slice(0, 150)
+      console.error(
+        pc.cyan(`${sessionTag} ⚡ TOOL.EXECUTE: ${pc.bold(toolName)}`)
+      )
+      console.error(pc.dim(`   input: ${inputStr}${inputStr.length >= 150 ? "..." : ""}`))
+      break
+    }
+
+    case "tool.result": {
+      const resultProps = props as ToolResultProps | undefined
+      const output = resultProps?.output ?? ""
+      const preview = output.slice(0, 200).replace(/\n/g, "\\n")
+      console.error(
+        pc.green(`${sessionTag} ✓ TOOL.RESULT: "${preview}${output.length > 200 ? "..." : ""}"`)
+      )
+      break
+    }
+
+    default:
+      console.error(pc.dim(`${sessionTag} ${payload.type}`))
+  }
+}
+
+function handleSessionIdle(
+  ctx: RunContext,
+  payload: EventPayload,
+  state: EventState
+): void {
+  if (payload.type !== "session.idle") return
+
+  const props = payload.properties as SessionIdleProps | undefined
+  if (props?.sessionID === ctx.sessionID) {
+    state.mainSessionIdle = true
+  }
+}
+
+function handleSessionStatus(
+  ctx: RunContext,
+  payload: EventPayload,
+  state: EventState
+): void {
+  if (payload.type !== "session.status") return
+
+  const props = payload.properties as SessionStatusProps | undefined
+  if (props?.sessionID === ctx.sessionID && props?.status?.type === "busy") {
+    state.mainSessionIdle = false
+  }
+}
+
+function handleSessionError(
+  ctx: RunContext,
+  payload: EventPayload,
+  state: EventState
+): void {
+  if (payload.type !== "session.error") return
+
+  const props = payload.properties as SessionErrorProps | undefined
+  if (props?.sessionID === ctx.sessionID) {
+    state.mainSessionError = true
+    state.lastError = props?.error
+      ? String(props.error instanceof Error ? props.error.message : props.error)
+      : "Unknown error"
+    console.error(pc.red(`\n[session.error] ${state.lastError}`))
+  }
+}
+
+function handleMessagePartUpdated(
+  ctx: RunContext,
+  payload: EventPayload,
+  state: EventState
+): void {
+  if (payload.type !== "message.part.updated") return
+
+  const props = payload.properties as MessagePartUpdatedProps | undefined
+  if (props?.info?.sessionID !== ctx.sessionID) return
+  if (props?.info?.role !== "assistant") return
+
+  const part = props.part
+  if (!part) return
+
+  if (part.type === "text" && part.text) {
+    const newText = part.text.slice(state.lastPartText.length)
+    if (newText) {
+      process.stdout.write(newText)
+    }
+    state.lastPartText = part.text
+  }
+}
+
+function handleMessageUpdated(
+  ctx: RunContext,
+  payload: EventPayload,
+  state: EventState
+): void {
+  if (payload.type !== "message.updated") return
+
+  const props = payload.properties as MessageUpdatedProps | undefined
+  if (props?.info?.sessionID !== ctx.sessionID) return
+  if (props?.info?.role !== "assistant") return
+
+  const content = props.content
+  if (!content || content === state.lastOutput) return
+
+  if (state.lastPartText.length === 0) {
+    const newContent = content.slice(state.lastOutput.length)
+    if (newContent) {
+      process.stdout.write(newContent)
+    }
+  }
+  state.lastOutput = content
+}
+
+function handleToolExecute(
+  ctx: RunContext,
+  payload: EventPayload,
+  state: EventState
+): void {
+  if (payload.type !== "tool.execute") return
+
+  const props = payload.properties as ToolExecuteProps | undefined
+  if (props?.sessionID !== ctx.sessionID) return
+
+  const toolName = props?.name || "unknown"
+  state.currentTool = toolName
+
+  let inputPreview = ""
+  if (props?.input) {
+    const input = props.input
+    if (input.command) {
+      inputPreview = ` ${pc.dim(String(input.command).slice(0, 60))}`
+    } else if (input.pattern) {
+      inputPreview = ` ${pc.dim(String(input.pattern).slice(0, 40))}`
+    } else if (input.filePath) {
+      inputPreview = ` ${pc.dim(String(input.filePath))}`
+    } else if (input.query) {
+      inputPreview = ` ${pc.dim(String(input.query).slice(0, 40))}`
+    }
+  }
+
+  process.stdout.write(`\n${pc.cyan("⚡")} ${pc.bold(toolName)}${inputPreview}\n`)
+}
+
+function handleToolResult(
+  ctx: RunContext,
+  payload: EventPayload,
+  state: EventState
+): void {
+  if (payload.type !== "tool.result") return
+
+  const props = payload.properties as ToolResultProps | undefined
+  if (props?.sessionID !== ctx.sessionID) return
+
+  const output = props?.output || ""
+  const maxLen = 200
+  const preview = output.length > maxLen 
+    ? output.slice(0, maxLen) + "..." 
+    : output
+  
+  if (preview.trim()) {
+    const lines = preview.split("\n").slice(0, 3)
+    process.stdout.write(pc.dim(`   └─ ${lines.join("\n      ")}\n`))
+  }
+
+  state.currentTool = null
+  state.lastPartText = ""
+}

src/cli/run/index.ts

@@ -0,0 +1,2 @@
+export { run } from "./runner"
+export type { RunOptions, RunContext } from "./types"

src/cli/run/runner.ts

@@ -0,0 +1,121 @@
+import { createOpencode } from "@opencode-ai/sdk"
+import pc from "picocolors"
+import type { RunOptions, RunContext } from "./types"
+import { checkCompletionConditions } from "./completion"
+import { createEventState, processEvents } from "./events"
+
+const POLL_INTERVAL_MS = 500
+const DEFAULT_TIMEOUT_MS = 0
+
+export async function run(options: RunOptions): Promise<number> {
+  const {
+    message,
+    agent,
+    directory = process.cwd(),
+    timeout = DEFAULT_TIMEOUT_MS,
+  } = options
+
+  console.log(pc.cyan("Starting opencode server..."))
+
+  const abortController = new AbortController()
+  let timeoutId: ReturnType<typeof setTimeout> | null = null
+
+  // timeout=0 means no timeout (run until completion)
+  if (timeout > 0) {
+    timeoutId = setTimeout(() => {
+      console.log(pc.yellow("\nTimeout reached. Aborting..."))
+      abortController.abort()
+    }, timeout)
+  }
+
+  try {
+    const { client, server } = await createOpencode({
+      signal: abortController.signal,
+    })
+
+    const cleanup = () => {
+      if (timeoutId) clearTimeout(timeoutId)
+      server.close()
+    }
+
+    process.on("SIGINT", () => {
+      console.log(pc.yellow("\nInterrupted. Shutting down..."))
+      cleanup()
+      process.exit(130)
+    })
+
+    try {
+      const sessionRes = await client.session.create({
+        body: { title: "oh-my-opencode run" },
+      })
+
+      const sessionID = sessionRes.data?.id
+      if (!sessionID) {
+        console.error(pc.red("Failed to create session"))
+        return 1
+      }
+
+      console.log(pc.dim(`Session: ${sessionID}`))
+
+      const ctx: RunContext = {
+        client,
+        sessionID,
+        directory,
+        abortController,
+      }
+
+      const events = await client.event.subscribe()
+      const eventState = createEventState()
+      const eventProcessor = processEvents(ctx, events.stream, eventState)
+
+      console.log(pc.dim("\nSending prompt..."))
+      await client.session.promptAsync({
+        path: { id: sessionID },
+        body: {
+          agent,
+          parts: [{ type: "text", text: message }],
+        },
+        query: { directory },
+      })
+
+      console.log(pc.dim("Waiting for completion...\n"))
+
+      while (!abortController.signal.aborted) {
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS))
+
+        if (!eventState.mainSessionIdle) {
+          continue
+        }
+
+        // Check if session errored - exit with failure if so
+        if (eventState.mainSessionError) {
+          console.error(pc.red(`\n\nSession ended with error: ${eventState.lastError}`))
+          console.error(pc.yellow("Check if todos were completed before the error."))
+          cleanup()
+          process.exit(1)
+        }
+
+        const shouldExit = await checkCompletionConditions(ctx)
+        if (shouldExit) {
+          console.log(pc.green("\n\nAll tasks completed."))
+          cleanup()
+          process.exit(0)
+        }
+      }
+
+      await eventProcessor.catch(() => {})
+      cleanup()
+      return 130
+    } catch (err) {
+      cleanup()
+      throw err
+    }
+  } catch (err) {
+    if (timeoutId) clearTimeout(timeoutId)
+    if (err instanceof Error && err.name === "AbortError") {
+      return 130
+    }
+    console.error(pc.red(`Error: ${err}`))
+    return 1
+  }
+}

src/cli/run/types.ts

@@ -0,0 +1,76 @@
+import type { OpencodeClient } from "@opencode-ai/sdk"
+
+export interface RunOptions {
+  message: string
+  agent?: string
+  directory?: string
+  timeout?: number
+}
+
+export interface RunContext {
+  client: OpencodeClient
+  sessionID: string
+  directory: string
+  abortController: AbortController
+}
+
+export interface Todo {
+  id: string
+  content: string
+  status: string
+  priority: string
+}
+
+export interface SessionStatus {
+  type: "idle" | "busy" | "retry"
+}
+
+export interface ChildSession {
+  id: string
+}
+
+export interface EventPayload {
+  type: string
+  properties?: Record<string, unknown>
+}
+
+export interface SessionIdleProps {
+  sessionID?: string
+}
+
+export interface SessionStatusProps {
+  sessionID?: string
+  status?: { type?: string }
+}
+
+export interface MessageUpdatedProps {
+  info?: { sessionID?: string; role?: string }
+  content?: string
+}
+
+export interface MessagePartUpdatedProps {
+  info?: { sessionID?: string; role?: string }
+  part?: {
+    type?: string
+    text?: string
+    name?: string
+    input?: unknown
+  }
+}
+
+export interface ToolExecuteProps {
+  sessionID?: string
+  name?: string
+  input?: Record<string, unknown>
+}
+
+export interface ToolResultProps {
+  sessionID?: string
+  name?: string
+  output?: string
+}
+
+export interface SessionErrorProps {
+  sessionID?: string
+  error?: unknown
+}

src/cli/types.ts

@@ -0,0 +1,31 @@
+export type ClaudeSubscription = "no" | "yes" | "max20"
+export type BooleanArg = "no" | "yes"
+
+export interface InstallArgs {
+  tui: boolean
+  claude?: ClaudeSubscription
+  chatgpt?: BooleanArg
+  gemini?: BooleanArg
+  skipAuth?: boolean
+}
+
+export interface InstallConfig {
+  hasClaude: boolean
+  isMax20: boolean
+  hasChatGPT: boolean
+  hasGemini: boolean
+}
+
+export interface ConfigMergeResult {
+  success: boolean
+  configPath: string
+  error?: string
+}
+
+export interface DetectedConfig {
+  isInstalled: boolean
+  hasClaude: boolean
+  isMax20: boolean
+  hasChatGPT: boolean
+  hasGemini: boolean
+}

src/config/index.ts

@@ -5,6 +5,10 @@ export {
   McpNameSchema,
   AgentNameSchema,
   HookNameSchema,
+  BuiltinCommandNameSchema,
+  SisyphusAgentConfigSchema,
+  ExperimentalConfigSchema,
+  RalphLoopConfigSchema,
 } from "./schema"
 
 export type {
@@ -14,4 +18,9 @@ export type {
   McpName,
   AgentName,
   HookName,
+  BuiltinCommandName,
+  SisyphusAgentConfig,
+  ExperimentalConfig,
+  DynamicContextPruningConfig,
+  RalphLoopConfig,
 } from "./schema"

src/config/schema.ts

@@ -16,14 +16,36 @@ const AgentPermissionSchema = z.object({
   external_directory: PermissionValue.optional(),
 })
 
-export const AgentNameSchema = z.enum([
+export const BuiltinAgentNameSchema = z.enum([
+  "Sisyphus",
   "oracle",
   "librarian",
   "explore",
   "frontend-ui-ux-engineer",
   "document-writer",
+  "multimodal-looker",
 ])
 
+export const BuiltinSkillNameSchema = z.enum([
+  "playwright",
+])
+
+export const OverridableAgentNameSchema = z.enum([
+  "build",
+  "plan",
+  "Sisyphus",
+  "OpenCode-Builder",
+  "Planner-Sisyphus",
+  "oracle",
+  "librarian",
+  "explore",
+  "frontend-ui-ux-engineer",
+  "document-writer",
+  "multimodal-looker",
+])
+
+export const AgentNameSchema = BuiltinAgentNameSchema
+
 export const HookNameSchema = z.enum([
   "todo-continuation-enforcer",
   "context-window-monitor",
@@ -31,15 +53,32 @@ export const HookNameSchema = z.enum([
   "session-notification",
   "comment-checker",
   "grep-output-truncator",
+  "tool-output-truncator",
   "directory-agents-injector",
   "directory-readme-injector",
   "empty-task-response-detector",
   "think-mode",
-  "anthropic-auto-compact",
+  "anthropic-context-window-limit-recovery",
   "rules-injector",
   "background-notification",
   "auto-update-checker",
-  "ultrawork-mode",
+  "startup-toast",
+  "keyword-detector",
+  "agent-usage-reminder",
+  "non-interactive-env",
+  "interactive-bash-session",
+  "empty-message-sanitizer",
+  "thinking-block-validator",
+  "ralph-loop",
+  "preemptive-compaction",
+  "compaction-context-injector",
+  "claude-code-hooks",
+  "auto-slash-command",
+  "edit-error-recovery",
+])
+
+export const BuiltinCommandNameSchema = z.enum([
+  "init-deep",
 ])
 
 export const AgentOverrideConfigSchema = z.object({
@@ -47,6 +86,7 @@ export const AgentOverrideConfigSchema = z.object({
   temperature: z.number().min(0).max(2).optional(),
   top_p: z.number().min(0).max(1).optional(),
   prompt: z.string().optional(),
+  prompt_append: z.string().optional(),
   tools: z.record(z.string(), z.boolean()).optional(),
   disable: z.boolean().optional(),
   description: z.string().optional(),
@@ -58,15 +98,19 @@ export const AgentOverrideConfigSchema = z.object({
   permission: AgentPermissionSchema.optional(),
 })
 
-export const AgentOverridesSchema = z
-  .object({
-    oracle: AgentOverrideConfigSchema.optional(),
-    librarian: AgentOverrideConfigSchema.optional(),
-    explore: AgentOverrideConfigSchema.optional(),
-    "frontend-ui-ux-engineer": AgentOverrideConfigSchema.optional(),
-    "document-writer": AgentOverrideConfigSchema.optional(),
-  })
-  .partial()
+export const AgentOverridesSchema = z.object({
+  build: AgentOverrideConfigSchema.optional(),
+  plan: AgentOverrideConfigSchema.optional(),
+  Sisyphus: AgentOverrideConfigSchema.optional(),
+  "OpenCode-Builder": AgentOverrideConfigSchema.optional(),
+  "Planner-Sisyphus": AgentOverrideConfigSchema.optional(),
+  oracle: AgentOverrideConfigSchema.optional(),
+  librarian: AgentOverrideConfigSchema.optional(),
+  explore: AgentOverrideConfigSchema.optional(),
+  "frontend-ui-ux-engineer": AgentOverrideConfigSchema.optional(),
+  "document-writer": AgentOverrideConfigSchema.optional(),
+  "multimodal-looker": AgentOverrideConfigSchema.optional(),
+})
 
 export const ClaudeCodeConfigSchema = z.object({
   mcp: z.boolean().optional(),
@@ -74,16 +118,136 @@ export const ClaudeCodeConfigSchema = z.object({
   skills: z.boolean().optional(),
   agents: z.boolean().optional(),
   hooks: z.boolean().optional(),
+  plugins: z.boolean().optional(),
+  plugins_override: z.record(z.string(), z.boolean()).optional(),
+})
+
+export const SisyphusAgentConfigSchema = z.object({
+  disabled: z.boolean().optional(),
+  default_builder_enabled: z.boolean().optional(),
+  planner_enabled: z.boolean().optional(),
+  replace_plan: z.boolean().optional(),
+})
+
+export const CommentCheckerConfigSchema = z.object({
+  /** Custom prompt to replace the default warning message. Use {{comments}} placeholder for detected comments XML. */
+  custom_prompt: z.string().optional(),
+})
+
+export const DynamicContextPruningConfigSchema = z.object({
+  /** Enable dynamic context pruning (default: false) */
+  enabled: z.boolean().default(false),
+  /** Notification level: off, minimal, or detailed (default: detailed) */
+  notification: z.enum(["off", "minimal", "detailed"]).default("detailed"),
+  /** Turn protection - prevent pruning recent tool outputs */
+  turn_protection: z.object({
+    enabled: z.boolean().default(true),
+    turns: z.number().min(1).max(10).default(3),
+  }).optional(),
+  /** Tools that should never be pruned */
+  protected_tools: z.array(z.string()).default([
+    "task", "todowrite", "todoread",
+    "lsp_rename", "lsp_code_action_resolve",
+    "session_read", "session_write", "session_search",
+  ]),
+  /** Pruning strategies configuration */
+  strategies: z.object({
+    /** Remove duplicate tool calls (same tool + same args) */
+    deduplication: z.object({
+      enabled: z.boolean().default(true),
+    }).optional(),
+    /** Prune write inputs when file subsequently read */
+    supersede_writes: z.object({
+      enabled: z.boolean().default(true),
+      /** Aggressive mode: prune any write if ANY subsequent read */
+      aggressive: z.boolean().default(false),
+    }).optional(),
+    /** Prune errored tool inputs after N turns */
+    purge_errors: z.object({
+      enabled: z.boolean().default(true),
+      turns: z.number().min(1).max(20).default(5),
+    }).optional(),
+  }).optional(),
+})
+
+export const ExperimentalConfigSchema = z.object({
+  aggressive_truncation: z.boolean().optional(),
+  auto_resume: z.boolean().optional(),
+  /** Enable preemptive compaction at threshold (default: true since v2.9.0) */
+  preemptive_compaction: z.boolean().optional(),
+  /** Threshold percentage to trigger preemptive compaction (default: 0.80) */
+  preemptive_compaction_threshold: z.number().min(0.5).max(0.95).optional(),
+  /** Truncate all tool outputs, not just whitelisted tools (default: false). Tool output truncator is enabled by default - disable via disabled_hooks. */
+  truncate_all_tool_outputs: z.boolean().optional(),
+  /** Dynamic context pruning configuration */
+  dynamic_context_pruning: DynamicContextPruningConfigSchema.optional(),
+  /** Enable DCP (Dynamic Context Pruning) for compaction - runs first when token limit exceeded (default: false) */
+  dcp_for_compaction: z.boolean().optional(),
+})
+
+export const SkillSourceSchema = z.union([
+  z.string(),
+  z.object({
+    path: z.string(),
+    recursive: z.boolean().optional(),
+    glob: z.string().optional(),
+  }),
+])
+
+export const SkillDefinitionSchema = z.object({
+  description: z.string().optional(),
+  template: z.string().optional(),
+  from: z.string().optional(),
+  model: z.string().optional(),
+  agent: z.string().optional(),
+  subtask: z.boolean().optional(),
+  "argument-hint": z.string().optional(),
+  license: z.string().optional(),
+  compatibility: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  "allowed-tools": z.array(z.string()).optional(),
+  disable: z.boolean().optional(),
+})
+
+export const SkillEntrySchema = z.union([
+  z.boolean(),
+  SkillDefinitionSchema,
+])
+
+export const SkillsConfigSchema = z.union([
+  z.array(z.string()),
+  z.record(z.string(), SkillEntrySchema).and(z.object({
+    sources: z.array(SkillSourceSchema).optional(),
+    enable: z.array(z.string()).optional(),
+    disable: z.array(z.string()).optional(),
+  }).partial()),
+])
+
+export const RalphLoopConfigSchema = z.object({
+  /** Enable ralph loop functionality (default: false - opt-in feature) */
+  enabled: z.boolean().default(false),
+  /** Default max iterations if not specified in command (default: 100) */
+  default_max_iterations: z.number().min(1).max(1000).default(100),
+  /** Custom state file directory relative to project root (default: .opencode/) */
+  state_dir: z.string().optional(),
 })
 
 export const OhMyOpenCodeConfigSchema = z.object({
   $schema: z.string().optional(),
   disabled_mcps: z.array(McpNameSchema).optional(),
-  disabled_agents: z.array(AgentNameSchema).optional(),
+  disabled_agents: z.array(BuiltinAgentNameSchema).optional(),
+  disabled_skills: z.array(BuiltinSkillNameSchema).optional(),
   disabled_hooks: z.array(HookNameSchema).optional(),
+  disabled_commands: z.array(BuiltinCommandNameSchema).optional(),
   agents: AgentOverridesSchema.optional(),
   claude_code: ClaudeCodeConfigSchema.optional(),
   google_auth: z.boolean().optional(),
+  sisyphus_agent: SisyphusAgentConfigSchema.optional(),
+  comment_checker: CommentCheckerConfigSchema.optional(),
+  experimental: ExperimentalConfigSchema.optional(),
+  auto_update: z.boolean().optional(),
+  skills: SkillsConfigSchema.optional(),
+  ralph_loop: RalphLoopConfigSchema.optional(),
 })
 
 export type OhMyOpenCodeConfig = z.infer<typeof OhMyOpenCodeConfigSchema>
@@ -91,5 +255,14 @@ export type AgentOverrideConfig = z.infer<typeof AgentOverrideConfigSchema>
 export type AgentOverrides = z.infer<typeof AgentOverridesSchema>
 export type AgentName = z.infer<typeof AgentNameSchema>
 export type HookName = z.infer<typeof HookNameSchema>
+export type BuiltinCommandName = z.infer<typeof BuiltinCommandNameSchema>
+export type BuiltinSkillName = z.infer<typeof BuiltinSkillNameSchema>
+export type SisyphusAgentConfig = z.infer<typeof SisyphusAgentConfigSchema>
+export type CommentCheckerConfig = z.infer<typeof CommentCheckerConfigSchema>
+export type ExperimentalConfig = z.infer<typeof ExperimentalConfigSchema>
+export type DynamicContextPruningConfig = z.infer<typeof DynamicContextPruningConfigSchema>
+export type SkillsConfig = z.infer<typeof SkillsConfigSchema>
+export type SkillDefinition = z.infer<typeof SkillDefinitionSchema>
+export type RalphLoopConfig = z.infer<typeof RalphLoopConfigSchema>
 
 export { McpNameSchema, type McpName } from "../mcp/types"

src/features/AGENTS.md

@@ -0,0 +1,66 @@
+# FEATURES KNOWLEDGE BASE
+
+## OVERVIEW
+
+Claude Code compatibility layer + core feature modules. Commands, skills, agents, MCPs, hooks from Claude Code work seamlessly.
+
+## STRUCTURE
+
+```
+features/
+├── background-agent/           # Task lifecycle, notifications (460 lines)
+├── builtin-commands/           # Built-in slash commands
+├── builtin-skills/             # Built-in skills (playwright)
+├── claude-code-agent-loader/   # ~/.claude/agents/*.md
+├── claude-code-command-loader/ # ~/.claude/commands/*.md
+├── claude-code-mcp-loader/     # .mcp.json files
+│   └── env-expander.ts         # ${VAR} expansion
+├── claude-code-plugin-loader/  # installed_plugins.json (484 lines)
+├── claude-code-session-state/  # Session state persistence
+├── opencode-skill-loader/      # Skills from OpenCode + Claude paths
+├── skill-mcp-manager/          # MCP servers in skill YAML
+└── hook-message-injector/      # Inject messages into conversation
+```
+
+## LOADER PRIORITY
+
+| Loader | Priority (highest first) |
+|--------|--------------------------|
+| Commands | `.opencode/command/` > `~/.config/opencode/command/` > `.claude/commands/` > `~/.claude/commands/` |
+| Skills | `.opencode/skill/` > `~/.config/opencode/skill/` > `.claude/skills/` > `~/.claude/skills/` |
+| Agents | `.claude/agents/` > `~/.claude/agents/` |
+| MCPs | `.claude/.mcp.json` > `.mcp.json` > `~/.claude/.mcp.json` |
+
+## CONFIG TOGGLES
+
+```json
+{
+  "claude_code": {
+    "mcp": false,      // Skip .mcp.json
+    "commands": false, // Skip commands/*.md
+    "skills": false,   // Skip skills/*/SKILL.md
+    "agents": false,   // Skip agents/*.md
+    "hooks": false     // Skip settings.json hooks
+  }
+}
+```
+
+## BACKGROUND AGENT
+
+- Lifecycle: pending → running → completed/failed
+- OS notification on complete
+- `background_output` to retrieve results
+- `background_cancel` with task_id or all=true
+
+## SKILL MCP
+
+- MCP servers embedded in skill YAML frontmatter
+- Lazy client loading, session-scoped cleanup
+- `skill_mcp` tool exposes capabilities
+
+## ANTI-PATTERNS
+
+- Blocking on load (loaders run at startup)
+- No error handling (always try/catch)
+- Ignoring priority order
+- Writing to ~/.claude/ (read-only)

src/features/background-agent/manager.test.ts

@@ -0,0 +1,416 @@
+import { describe, test, expect, beforeEach } from "bun:test"
+import type { BackgroundTask } from "./types"
+
+const TASK_TTL_MS = 30 * 60 * 1000
+
+class MockBackgroundManager {
+  private tasks: Map<string, BackgroundTask> = new Map()
+  private notifications: Map<string, BackgroundTask[]> = new Map()
+
+  addTask(task: BackgroundTask): void {
+    this.tasks.set(task.id, task)
+  }
+
+  getTask(id: string): BackgroundTask | undefined {
+    return this.tasks.get(id)
+  }
+
+  getTasksByParentSession(sessionID: string): BackgroundTask[] {
+    const result: BackgroundTask[] = []
+    for (const task of this.tasks.values()) {
+      if (task.parentSessionID === sessionID) {
+        result.push(task)
+      }
+    }
+    return result
+  }
+
+  getAllDescendantTasks(sessionID: string): BackgroundTask[] {
+    const result: BackgroundTask[] = []
+    const directChildren = this.getTasksByParentSession(sessionID)
+
+    for (const child of directChildren) {
+      result.push(child)
+      const descendants = this.getAllDescendantTasks(child.sessionID)
+      result.push(...descendants)
+    }
+
+    return result
+  }
+
+  markForNotification(task: BackgroundTask): void {
+    const queue = this.notifications.get(task.parentSessionID) ?? []
+    queue.push(task)
+    this.notifications.set(task.parentSessionID, queue)
+  }
+
+  getPendingNotifications(sessionID: string): BackgroundTask[] {
+    return this.notifications.get(sessionID) ?? []
+  }
+
+  private clearNotificationsForTask(taskId: string): void {
+    for (const [sessionID, tasks] of this.notifications.entries()) {
+      const filtered = tasks.filter((t) => t.id !== taskId)
+      if (filtered.length === 0) {
+        this.notifications.delete(sessionID)
+      } else {
+        this.notifications.set(sessionID, filtered)
+      }
+    }
+  }
+
+  pruneStaleTasksAndNotifications(): { prunedTasks: string[]; prunedNotifications: number } {
+    const now = Date.now()
+    const prunedTasks: string[] = []
+    let prunedNotifications = 0
+
+    for (const [taskId, task] of this.tasks.entries()) {
+      const age = now - task.startedAt.getTime()
+      if (age > TASK_TTL_MS) {
+        prunedTasks.push(taskId)
+        this.clearNotificationsForTask(taskId)
+        this.tasks.delete(taskId)
+      }
+    }
+
+    for (const [sessionID, notifications] of this.notifications.entries()) {
+      if (notifications.length === 0) {
+        this.notifications.delete(sessionID)
+        continue
+      }
+      const validNotifications = notifications.filter((task) => {
+        const age = now - task.startedAt.getTime()
+        return age <= TASK_TTL_MS
+      })
+      const removed = notifications.length - validNotifications.length
+      prunedNotifications += removed
+      if (validNotifications.length === 0) {
+        this.notifications.delete(sessionID)
+      } else if (validNotifications.length !== notifications.length) {
+        this.notifications.set(sessionID, validNotifications)
+      }
+    }
+
+    return { prunedTasks, prunedNotifications }
+  }
+
+  getTaskCount(): number {
+    return this.tasks.size
+  }
+
+  getNotificationCount(): number {
+    let count = 0
+    for (const notifications of this.notifications.values()) {
+      count += notifications.length
+    }
+    return count
+  }
+}
+
+function createMockTask(overrides: Partial<BackgroundTask> & { id: string; sessionID: string; parentSessionID: string }): BackgroundTask {
+  return {
+    parentMessageID: "mock-message-id",
+    description: "test task",
+    prompt: "test prompt",
+    agent: "test-agent",
+    status: "running",
+    startedAt: new Date(),
+    ...overrides,
+  }
+}
+
+describe("BackgroundManager.getAllDescendantTasks", () => {
+  let manager: MockBackgroundManager
+
+  beforeEach(() => {
+    // #given
+    manager = new MockBackgroundManager()
+  })
+
+  test("should return empty array when no tasks exist", () => {
+    // #given - empty manager
+
+    // #when
+    const result = manager.getAllDescendantTasks("session-a")
+
+    // #then
+    expect(result).toEqual([])
+  })
+
+  test("should return direct children only when no nested tasks", () => {
+    // #given
+    const taskB = createMockTask({
+      id: "task-b",
+      sessionID: "session-b",
+      parentSessionID: "session-a",
+    })
+    manager.addTask(taskB)
+
+    // #when
+    const result = manager.getAllDescendantTasks("session-a")
+
+    // #then
+    expect(result).toHaveLength(1)
+    expect(result[0].id).toBe("task-b")
+  })
+
+  test("should return all nested descendants (2 levels deep)", () => {
+    // #given
+    // Session A -> Task B -> Task C
+    const taskB = createMockTask({
+      id: "task-b",
+      sessionID: "session-b",
+      parentSessionID: "session-a",
+    })
+    const taskC = createMockTask({
+      id: "task-c",
+      sessionID: "session-c",
+      parentSessionID: "session-b",
+    })
+    manager.addTask(taskB)
+    manager.addTask(taskC)
+
+    // #when
+    const result = manager.getAllDescendantTasks("session-a")
+
+    // #then
+    expect(result).toHaveLength(2)
+    expect(result.map(t => t.id)).toContain("task-b")
+    expect(result.map(t => t.id)).toContain("task-c")
+  })
+
+  test("should return all nested descendants (3 levels deep)", () => {
+    // #given
+    // Session A -> Task B -> Task C -> Task D
+    const taskB = createMockTask({
+      id: "task-b",
+      sessionID: "session-b",
+      parentSessionID: "session-a",
+    })
+    const taskC = createMockTask({
+      id: "task-c",
+      sessionID: "session-c",
+      parentSessionID: "session-b",
+    })
+    const taskD = createMockTask({
+      id: "task-d",
+      sessionID: "session-d",
+      parentSessionID: "session-c",
+    })
+    manager.addTask(taskB)
+    manager.addTask(taskC)
+    manager.addTask(taskD)
+
+    // #when
+    const result = manager.getAllDescendantTasks("session-a")
+
+    // #then
+    expect(result).toHaveLength(3)
+    expect(result.map(t => t.id)).toContain("task-b")
+    expect(result.map(t => t.id)).toContain("task-c")
+    expect(result.map(t => t.id)).toContain("task-d")
+  })
+
+  test("should handle multiple branches (tree structure)", () => {
+    // #given
+    // Session A -> Task B1 -> Task C1
+    //           -> Task B2 -> Task C2
+    const taskB1 = createMockTask({
+      id: "task-b1",
+      sessionID: "session-b1",
+      parentSessionID: "session-a",
+    })
+    const taskB2 = createMockTask({
+      id: "task-b2",
+      sessionID: "session-b2",
+      parentSessionID: "session-a",
+    })
+    const taskC1 = createMockTask({
+      id: "task-c1",
+      sessionID: "session-c1",
+      parentSessionID: "session-b1",
+    })
+    const taskC2 = createMockTask({
+      id: "task-c2",
+      sessionID: "session-c2",
+      parentSessionID: "session-b2",
+    })
+    manager.addTask(taskB1)
+    manager.addTask(taskB2)
+    manager.addTask(taskC1)
+    manager.addTask(taskC2)
+
+    // #when
+    const result = manager.getAllDescendantTasks("session-a")
+
+    // #then
+    expect(result).toHaveLength(4)
+    expect(result.map(t => t.id)).toContain("task-b1")
+    expect(result.map(t => t.id)).toContain("task-b2")
+    expect(result.map(t => t.id)).toContain("task-c1")
+    expect(result.map(t => t.id)).toContain("task-c2")
+  })
+
+  test("should not include tasks from unrelated sessions", () => {
+    // #given
+    // Session A -> Task B
+    // Session X -> Task Y (unrelated)
+    const taskB = createMockTask({
+      id: "task-b",
+      sessionID: "session-b",
+      parentSessionID: "session-a",
+    })
+    const taskY = createMockTask({
+      id: "task-y",
+      sessionID: "session-y",
+      parentSessionID: "session-x",
+    })
+    manager.addTask(taskB)
+    manager.addTask(taskY)
+
+    // #when
+    const result = manager.getAllDescendantTasks("session-a")
+
+    // #then
+    expect(result).toHaveLength(1)
+    expect(result[0].id).toBe("task-b")
+    expect(result.map(t => t.id)).not.toContain("task-y")
+  })
+
+  test("getTasksByParentSession should only return direct children (not recursive)", () => {
+    // #given
+    // Session A -> Task B -> Task C
+    const taskB = createMockTask({
+      id: "task-b",
+      sessionID: "session-b",
+      parentSessionID: "session-a",
+    })
+    const taskC = createMockTask({
+      id: "task-c",
+      sessionID: "session-c",
+      parentSessionID: "session-b",
+    })
+    manager.addTask(taskB)
+    manager.addTask(taskC)
+
+    // #when
+    const result = manager.getTasksByParentSession("session-a")
+
+    // #then
+    expect(result).toHaveLength(1)
+    expect(result[0].id).toBe("task-b")
+  })
+})
+
+describe("BackgroundManager.pruneStaleTasksAndNotifications", () => {
+  let manager: MockBackgroundManager
+
+  beforeEach(() => {
+    // #given
+    manager = new MockBackgroundManager()
+  })
+
+  test("should not prune fresh tasks", () => {
+    // #given
+    const task = createMockTask({
+      id: "task-fresh",
+      sessionID: "session-fresh",
+      parentSessionID: "session-parent",
+      startedAt: new Date(),
+    })
+    manager.addTask(task)
+
+    // #when
+    const result = manager.pruneStaleTasksAndNotifications()
+
+    // #then
+    expect(result.prunedTasks).toHaveLength(0)
+    expect(manager.getTaskCount()).toBe(1)
+  })
+
+  test("should prune tasks older than 30 minutes", () => {
+    // #given
+    const staleDate = new Date(Date.now() - 31 * 60 * 1000)
+    const task = createMockTask({
+      id: "task-stale",
+      sessionID: "session-stale",
+      parentSessionID: "session-parent",
+      startedAt: staleDate,
+    })
+    manager.addTask(task)
+
+    // #when
+    const result = manager.pruneStaleTasksAndNotifications()
+
+    // #then
+    expect(result.prunedTasks).toContain("task-stale")
+    expect(manager.getTaskCount()).toBe(0)
+  })
+
+  test("should prune stale notifications", () => {
+    // #given
+    const staleDate = new Date(Date.now() - 31 * 60 * 1000)
+    const task = createMockTask({
+      id: "task-stale",
+      sessionID: "session-stale",
+      parentSessionID: "session-parent",
+      startedAt: staleDate,
+    })
+    manager.markForNotification(task)
+
+    // #when
+    const result = manager.pruneStaleTasksAndNotifications()
+
+    // #then
+    expect(result.prunedNotifications).toBe(1)
+    expect(manager.getNotificationCount()).toBe(0)
+  })
+
+  test("should clean up notifications when task is pruned", () => {
+    // #given
+    const staleDate = new Date(Date.now() - 31 * 60 * 1000)
+    const task = createMockTask({
+      id: "task-stale",
+      sessionID: "session-stale",
+      parentSessionID: "session-parent",
+      startedAt: staleDate,
+    })
+    manager.addTask(task)
+    manager.markForNotification(task)
+
+    // #when
+    manager.pruneStaleTasksAndNotifications()
+
+    // #then
+    expect(manager.getTaskCount()).toBe(0)
+    expect(manager.getNotificationCount()).toBe(0)
+  })
+
+  test("should keep fresh tasks while pruning stale ones", () => {
+    // #given
+    const staleDate = new Date(Date.now() - 31 * 60 * 1000)
+    const staleTask = createMockTask({
+      id: "task-stale",
+      sessionID: "session-stale",
+      parentSessionID: "session-parent",
+      startedAt: staleDate,
+    })
+    const freshTask = createMockTask({
+      id: "task-fresh",
+      sessionID: "session-fresh",
+      parentSessionID: "session-parent",
+      startedAt: new Date(),
+    })
+    manager.addTask(staleTask)
+    manager.addTask(freshTask)
+
+    // #when
+    const result = manager.pruneStaleTasksAndNotifications()
+
+    // #then
+    expect(result.prunedTasks).toHaveLength(1)
+    expect(result.prunedTasks).toContain("task-stale")
+    expect(manager.getTaskCount()).toBe(1)
+    expect(manager.getTask("task-fresh")).toBeDefined()
+  })
+})

src/features/background-agent/manager.ts

@@ -1,9 +1,18 @@
+import { existsSync, readdirSync } from "node:fs"
+import { join } from "node:path"
 import type { PluginInput } from "@opencode-ai/plugin"
 import type {
   BackgroundTask,
   LaunchInput,
 } from "./types"
 import { log } from "../../shared/logger"
+import {
+  findNearestMessageWithFields,
+  MESSAGE_STORAGE,
+} from "../hook-message-injector"
+import { subagentSessions } from "../claude-code-session-state"
+
+const TASK_TTL_MS = 30 * 60 * 1000
 
 type OpencodeClient = PluginInput["client"]
 
@@ -24,12 +33,33 @@ interface Event {
   properties?: EventProperties
 }
 
+interface Todo {
+  content: string
+  status: string
+  priority: string
+  id: string
+}
+
+function getMessageDir(sessionID: string): string | null {
+  if (!existsSync(MESSAGE_STORAGE)) return null
+
+  const directPath = join(MESSAGE_STORAGE, sessionID)
+  if (existsSync(directPath)) return directPath
+
+  for (const dir of readdirSync(MESSAGE_STORAGE)) {
+    const sessionPath = join(MESSAGE_STORAGE, dir, sessionID)
+    if (existsSync(sessionPath)) return sessionPath
+  }
+
+  return null
+}
+
 export class BackgroundManager {
   private tasks: Map<string, BackgroundTask>
   private notifications: Map<string, BackgroundTask[]>
   private client: OpencodeClient
   private directory: string
-  private pollingInterval?: Timer
+  private pollingInterval?: ReturnType<typeof setInterval>
 
   constructor(ctx: PluginInput) {
     this.tasks = new Map()
@@ -39,6 +69,10 @@ export class BackgroundManager {
   }
 
   async launch(input: LaunchInput): Promise<BackgroundTask> {
+    if (!input.agent || input.agent.trim() === "") {
+      throw new Error("Agent parameter is required")
+    }
+
     const createResult = await this.client.session.create({
       body: {
         parentID: input.parentSessionID,
@@ -51,6 +85,7 @@ export class BackgroundManager {
     }
 
     const sessionID = createResult.data.id
+    subagentSessions.add(sessionID)
 
     const task: BackgroundTask = {
       id: `bg_${crypto.randomUUID().slice(0, 8)}`,
@@ -66,22 +101,21 @@ export class BackgroundManager {
         toolCalls: 0,
         lastUpdate: new Date(),
       },
+      parentModel: input.parentModel,
     }
 
     this.tasks.set(task.id, task)
     this.startPolling()
 
-    log("[background-agent] Launching task:", { taskId: task.id, sessionID })
+    log("[background-agent] Launching task:", { taskId: task.id, sessionID, agent: input.agent })
 
     this.client.session.promptAsync({
       path: { id: sessionID },
       body: {
         agent: input.agent,
         tools: {
+          task: false,
           background_task: false,
-          background_output: false,
-          background_cancel: false,
-          call_omo_agent: false,
         },
         parts: [{ type: "text", text: input.prompt }],
       },
@@ -90,8 +124,15 @@ export class BackgroundManager {
       const existingTask = this.findBySession(sessionID)
       if (existingTask) {
         existingTask.status = "error"
-        existingTask.error = String(error)
+        const errorMessage = error instanceof Error ? error.message : String(error)
+        if (errorMessage.includes("agent.name") || errorMessage.includes("undefined")) {
+          existingTask.error = `Agent "${input.agent}" not found. Make sure the agent is registered in your opencode.json or provided by a plugin.`
+        } else {
+          existingTask.error = errorMessage
+        }
         existingTask.completedAt = new Date()
+        this.markForNotification(existingTask)
+        this.notifyParentSession(existingTask)
       }
     })
 
@@ -112,6 +153,19 @@ export class BackgroundManager {
     return result
   }
 
+  getAllDescendantTasks(sessionID: string): BackgroundTask[] {
+    const result: BackgroundTask[] = []
+    const directChildren = this.getTasksByParentSession(sessionID)
+
+    for (const child of directChildren) {
+      result.push(child)
+      const descendants = this.getAllDescendantTasks(child.sessionID)
+      result.push(...descendants)
+    }
+
+    return result
+  }
+
   findBySession(sessionID: string): BackgroundTask | undefined {
     for (const task of this.tasks.values()) {
       if (task.sessionID === sessionID) {
@@ -121,6 +175,23 @@ export class BackgroundManager {
     return undefined
   }
 
+  private async checkSessionTodos(sessionID: string): Promise<boolean> {
+    try {
+      const response = await this.client.session.todo({
+        path: { id: sessionID },
+      })
+      const todos = (response.data ?? response) as Todo[]
+      if (!todos || todos.length === 0) return false
+
+      const incomplete = todos.filter(
+        (t) => t.status !== "completed" && t.status !== "cancelled"
+      )
+      return incomplete.length > 0
+    } catch {
+      return false
+    }
+  }
+
   handleEvent(event: Event): void {
     const props = event.properties
 
@@ -153,11 +224,18 @@ export class BackgroundManager {
       const task = this.findBySession(sessionID)
       if (!task || task.status !== "running") return
 
-      task.status = "completed"
-      task.completedAt = new Date()
-      this.markForNotification(task)
-      this.notifyParentSession(task)
-      log("[background-agent] Task completed via session.idle event:", task.id)
+      this.checkSessionTodos(sessionID).then((hasIncompleteTodos) => {
+        if (hasIncompleteTodos) {
+          log("[background-agent] Task has incomplete todos, waiting for todo-continuation:", task.id)
+          return
+        }
+
+        task.status = "completed"
+        task.completedAt = new Date()
+        this.markForNotification(task)
+        this.notifyParentSession(task)
+        log("[background-agent] Task completed via session.idle event:", task.id)
+      })
     }
 
     if (event.type === "session.deleted") {
@@ -176,6 +254,7 @@ export class BackgroundManager {
 
       this.tasks.delete(task.id)
       this.clearNotificationsForTask(task.id)
+      subagentSessions.delete(sessionID)
     }
   }
 
@@ -210,6 +289,7 @@ export class BackgroundManager {
     this.pollingInterval = setInterval(() => {
       this.pollRunningTasks()
     }, 2000)
+    this.pollingInterval.unref()
   }
 
   private stopPolling(): void {
@@ -219,6 +299,12 @@ export class BackgroundManager {
     }
   }
 
+  cleanup(): void {
+    this.stopPolling()
+    this.tasks.clear()
+    this.notifications.clear()
+  }
+
   private notifyParentSession(task: BackgroundTask): void {
     const duration = this.formatDuration(task.startedAt, task.completedAt)
 
@@ -241,19 +327,34 @@ export class BackgroundManager {
 
     log("[background-agent] Sending notification to parent session:", { parentSessionID: task.parentSessionID })
 
+    const taskId = task.id
     setTimeout(async () => {
       try {
+        const messageDir = getMessageDir(task.parentSessionID)
+        const prevMessage = messageDir ? findNearestMessageWithFields(messageDir) : null
+
+        const modelContext = task.parentModel ?? prevMessage?.model
+        const modelField = modelContext?.providerID && modelContext?.modelID
+          ? { providerID: modelContext.providerID, modelID: modelContext.modelID }
+          : undefined
+
         await this.client.session.prompt({
           path: { id: task.parentSessionID },
           body: {
+            agent: prevMessage?.agent,
+            model: modelField,
             parts: [{ type: "text", text: message }],
           },
           query: { directory: this.directory },
         })
-        this.clearNotificationsForTask(task.id)
         log("[background-agent] Successfully sent prompt to parent session:", { parentSessionID: task.parentSessionID })
       } catch (error) {
         log("[background-agent] prompt failed:", String(error))
+      } finally {
+        // Always clean up both maps to prevent memory leaks
+        this.clearNotificationsForTask(taskId)
+        this.tasks.delete(taskId)
+        log("[background-agent] Removed completed task from memory:", taskId)
       }
     }, 200)
   }
@@ -279,7 +380,42 @@ export class BackgroundManager {
     return false
   }
 
+  private pruneStaleTasksAndNotifications(): void {
+    const now = Date.now()
+
+    for (const [taskId, task] of this.tasks.entries()) {
+      const age = now - task.startedAt.getTime()
+      if (age > TASK_TTL_MS) {
+        log("[background-agent] Pruning stale task:", { taskId, age: Math.round(age / 1000) + "s" })
+        task.status = "error"
+        task.error = "Task timed out after 30 minutes"
+        task.completedAt = new Date()
+        this.clearNotificationsForTask(taskId)
+        this.tasks.delete(taskId)
+        subagentSessions.delete(task.sessionID)
+      }
+    }
+
+    for (const [sessionID, notifications] of this.notifications.entries()) {
+      if (notifications.length === 0) {
+        this.notifications.delete(sessionID)
+        continue
+      }
+      const validNotifications = notifications.filter((task) => {
+        const age = now - task.startedAt.getTime()
+        return age <= TASK_TTL_MS
+      })
+      if (validNotifications.length === 0) {
+        this.notifications.delete(sessionID)
+      } else if (validNotifications.length !== notifications.length) {
+        this.notifications.set(sessionID, validNotifications)
+      }
+    }
+  }
+
   private async pollRunningTasks(): Promise<void> {
+    this.pruneStaleTasksAndNotifications()
+
     const statusResult = await this.client.session.status()
     const allStatuses = (statusResult.data ?? {}) as Record<string, { type: string }>
 
@@ -295,6 +431,12 @@ export class BackgroundManager {
         }
 
         if (sessionStatus.type === "idle") {
+          const hasIncompleteTodos = await this.checkSessionTodos(task.sessionID)
+          if (hasIncompleteTodos) {
+            log("[background-agent] Task has incomplete todos via polling, waiting:", task.id)
+            continue
+          }
+
           task.status = "completed"
           task.completedAt = new Date()
           this.markForNotification(task)