claudeboss 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "claudeboss",
+  "description": "Delegate tasks to free opencode agents from Claude Code — Team mode (pair review) or Boss mode (manage, approve, deploy).",
+  "owner": {
+    "name": "xWael9",
+    "url": "https://github.com/xWael9"
+  },
+  "plugins": [
+    {
+      "name": "claudeboss",
+      "description": "Team and Boss modes for delegating work to free opencode agents.",
+      "source": "./",
+      "category": "productivity"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "claudeboss",
+  "description": "Delegate tasks to free opencode agents and supervise them from Claude Code — Team mode (pair review) or Boss mode (manage, approve, deploy).",
+  "author": {
+    "name": "xWael9",
+    "url": "https://github.com/xWael9"
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xWael9
+
+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.

package/README.md

@@ -0,0 +1,59 @@
+# ClaudeBoss
+
+Delegate tasks to **free** opencode agents, straight from Claude Code — as a teammate you review, or as a worker you manage.
+
+Claude Code can spend a lot of its own context/tokens doing every step of a task itself. ClaudeBoss routes the actual work to [opencode](https://opencode.ai)'s free-tier models (OpenCode Zen, no login required), while Claude reviews the result, fixes what's wrong, and — in Boss mode — supervises deployment. You keep Claude's judgment; the free model does the token-heavy grinding.
+
+## Install (one command)
+
+```bash
+npm install -g claudeboss
+claudeboss install
+```
+
+`claudeboss install` checks for the `opencode` CLI (installs it via npm if missing), confirms at least one free model is reachable, and prints manual OpenRouter fallback steps if not — **it never creates third-party accounts on your behalf.**
+
+### Via the Claude Code plugin marketplace
+
+```
+/plugin marketplace add xWael9/ClaudeBoss
+/plugin install claudeboss@claudeboss
+```
+
+Either install path gives you the same two skills inside Claude Code:
+
+| Command | What it does |
+|---|---|
+| `/claudeboss:team` | You and opencode work as a pair. Opencode drafts, Claude reviews like a second engineer and implements/finishes it. |
+| `/claudeboss:boss` | Claude manages, doesn't code. Delegates to opencode, requests revisions (max 3 rounds), shows you a summary, waits for your approval, then supervises deployment end-to-end. |
+
+## Why this exists
+
+Spawning a full Claude subagent for routine work still burns Claude's own context/tokens. Opencode's free tier (OpenCode Zen — DeepSeek V4 Flash Free, Nemotron 3 Ultra Free, North Mini Code Free, MiMo V2.5 Free, and more) does real work at zero API cost. ClaudeBoss:
+
+- **Picks the model live, per task.** `claudeboss model code` and `claudeboss model write` query `opencode models` at run time and rank by keyword heuristics (coder/code-tuned models for coding tasks, larger general models for prose/research). Free-tier catalogs change without notice — nothing here is hardcoded to a specific model ID.
+- **Extracts only the final answer.** Opencode's own reasoning/tool-call trace never reaches Claude's context — only the last text output does.
+- **Never auto-creates accounts.** If OpenCode Zen's free tier is ever unavailable, you get exact manual steps for a free OpenRouter key — no silent browser automation signing you up for a third-party service.
+
+## Manual CLI usage (outside Claude Code)
+
+```bash
+claudeboss model code                          # -> best free model id for a coding task
+claudeboss run code "add input validation to the signup form"
+claudeboss run write "draft a 3-paragraph changelog entry for v0.2.0"
+```
+
+## Requirements
+
+- Node.js >= 18 (for the npm install path)
+- `jq` (installed automatically via Homebrew/apt if missing, or install manually: https://jqlang.org/download/)
+
+## Limitations
+
+- Free models are weaker than Claude — don't expect them to solve hard/ambiguous problems unsupervised. Both modes cap revision loops (2 in team mode, 3 in boss mode) and escalate to you instead of grinding forever.
+- Boss mode's deployment step assumes you've already told Claude what "deploy" means for your project (push to a branch, run a script, SSH to a server, etc.) — it doesn't invent a deploy pipeline for you.
+- Free-tier model catalogs are provider-controlled and can shrink or disappear. `claudeboss install` re-checks live, every time.
+
+## License
+
+MIT

package/bin/claudeboss.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const SCRIPTS_DIR = path.join(__dirname, '..', 'scripts');
+const [, , cmd, ...rest] = process.argv;
+
+function run(script, args) {
+  const res = spawnSync('bash', [path.join(SCRIPTS_DIR, script), ...args], { stdio: 'inherit' });
+  process.exit(res.status === null ? 1 : res.status);
+}
+
+switch (cmd) {
+  case 'install':
+    run('install-opencode.sh', rest);
+    break;
+  case 'model':
+    run('select-model.sh', rest);
+    break;
+  case 'run':
+    run('claudeboss-run.sh', rest);
+    break;
+  default:
+    console.log(`ClaudeBoss -- delegate tasks to free opencode agents from Claude Code.
+
+Usage:
+  claudeboss install                    Check/install opencode CLI, verify a free model is reachable
+  claudeboss model <task-type>          Print the best free model id for a task type (code|write|research|general)
+  claudeboss run <task-type> "<task>"   Run a task through the selected free model, print only the final answer
+
+Claude Code usage: install this as a plugin, then use /claudeboss:team or /claudeboss:boss inside a session.
+Repo: https://github.com/xWael9/ClaudeBoss`);
+    process.exit(cmd ? 1 : 0);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "claudeboss",
+  "version": "0.1.0",
+  "description": "Delegate tasks to free opencode agents and supervise them from Claude Code -- Team mode (pair review) or Boss mode (manage, approve, deploy).",
+  "bin": {
+    "claudeboss": "bin/claudeboss.js"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "skills",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude-code",
+    "opencode",
+    "ai-agent",
+    "plugin",
+    "delegation",
+    "free-llm"
+  ],
+  "author": "xWael9",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xWael9/ClaudeBoss.git"
+  },
+  "homepage": "https://github.com/xWael9/ClaudeBoss",
+  "bugs": {
+    "url": "https://github.com/xWael9/ClaudeBoss/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/claudeboss-run.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Delegates one task to the best free opencode model and prints ONLY the
+# final answer text -- opencode's internal tool calls/reasoning never reach
+# the caller's context.
+set -uo pipefail
+
+TASK_TYPE="${1:-general}"
+shift || true
+TASK="$*"
+
+if [ -z "$TASK" ]; then
+  echo "Usage: claudeboss run <task-type> \"<task text>\"" >&2
+  echo "task-type: code | write | research | general" >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MODEL=$("$SCRIPT_DIR/select-model.sh" "$TASK_TYPE")
+STATUS=$?
+
+if [ $STATUS -ne 0 ] || [ -z "$MODEL" ]; then
+  echo "No usable free model found. Run: claudeboss install" >&2
+  exit 1
+fi
+
+echo "[claudeboss] model: $MODEL" >&2
+
+opencode run --agent build --model "$MODEL" --format json "$TASK" 2>&1 \
+  | jq -r 'select(.type=="text") | .part.text' \
+  | tail -1

package/scripts/install-opencode.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# ClaudeBoss setup: ensure opencode CLI + jq are present, verify a free model is reachable.
+# Never creates third-party accounts automatically -- prints manual steps instead.
+set -uo pipefail
+
+echo "== ClaudeBoss: opencode setup =="
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "jq not found (needed to parse opencode's JSON output)." >&2
+  if command -v brew >/dev/null 2>&1; then
+    echo "Installing jq via Homebrew..."
+    brew install jq
+  elif command -v apt-get >/dev/null 2>&1; then
+    echo "Installing jq via apt-get..."
+    sudo apt-get update -y && sudo apt-get install -y jq
+  else
+    echo "Install jq manually: https://jqlang.org/download/" >&2
+    exit 1
+  fi
+fi
+
+if command -v opencode >/dev/null 2>&1; then
+  echo "opencode CLI found: $(opencode --version 2>/dev/null)"
+else
+  echo "opencode CLI not found. Installing..."
+  if command -v npm >/dev/null 2>&1; then
+    npm install -g opencode-ai
+  else
+    echo "npm not found. Install Node.js first, or run: curl -fsSL https://opencode.ai/install | bash" >&2
+    exit 1
+  fi
+fi
+
+if ! command -v opencode >/dev/null 2>&1; then
+  echo "opencode install failed. Install manually: https://opencode.ai/docs" >&2
+  exit 1
+fi
+
+FREE_MODELS=$(opencode models 2>/dev/null | grep -i 'free' || true)
+
+if [ -n "$FREE_MODELS" ]; then
+  echo ""
+  echo "Free models available (no login needed):"
+  echo "$FREE_MODELS" | sed 's/^/  - /'
+  echo ""
+  echo "ClaudeBoss is ready. Use /claudeboss:team or /claudeboss:boss in Claude Code."
+  exit 0
+fi
+
+cat <<'EOF'
+
+No free OpenCode Zen models detected on this install.
+
+Manual fallback (ClaudeBoss does not create third-party accounts on your behalf):
+  1. Create a free account: https://openrouter.ai
+  2. Generate an API key:   https://openrouter.ai/keys
+  3. Connect it to opencode:
+       opencode providers login
+     (choose OpenRouter, paste the key)
+  4. Re-run: claudeboss install
+
+If you'd rather have your AI assistant do steps 1-3 for you interactively (via
+browser/computer control), ask it directly -- ClaudeBoss intentionally does not
+automate account creation for anyone who installs this package.
+EOF
+exit 1

package/scripts/select-model.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Picks the best available free opencode model for a task type.
+# Always checks live `opencode models` output -- never hardcodes a model id
+# that might no longer exist (free catalogs change without notice).
+set -uo pipefail
+
+TASK_TYPE="${1:-general}"
+
+if ! command -v opencode >/dev/null 2>&1; then
+  echo "opencode CLI not found. Run: claudeboss install" >&2
+  exit 1
+fi
+
+FREE_MODELS=$(opencode models 2>/dev/null | grep -i 'free' || true)
+
+if [ -z "$FREE_MODELS" ]; then
+  echo "No free models detected via 'opencode models'. Run: claudeboss install" >&2
+  exit 1
+fi
+
+pick() {
+  echo "$FREE_MODELS" | grep -i -- "$1" | head -1 || true
+}
+
+MODEL=""
+case "$TASK_TYPE" in
+  code|coding)
+    for kw in coder code-free deepseek qwen3 nemotron; do
+      MODEL=$(pick "$kw")
+      [ -n "$MODEL" ] && break
+    done
+    ;;
+  write|writing|research)
+    for kw in ultra nemotron gpt-oss-120b deepseek qwen3; do
+      MODEL=$(pick "$kw")
+      [ -n "$MODEL" ] && break
+    done
+    ;;
+  *)
+    for kw in deepseek ultra nemotron gpt-oss-120b qwen3; do
+      MODEL=$(pick "$kw")
+      [ -n "$MODEL" ] && break
+    done
+    ;;
+esac
+
+if [ -z "$MODEL" ]; then
+  MODEL=$(echo "$FREE_MODELS" | head -1)
+fi
+
+echo "$MODEL"

package/skills/boss/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: boss
+description: Act as the boss — delegate the task to a free opencode agent, review its output, request revisions, and only after the user approves, supervise deployment end-to-end. Claude does not write code or do heavy implementation in this mode. Use when the user says "be the boss", "/claudeboss:boss", or wants Claude to manage rather than execute.
+metadata:
+  origin: ClaudeBoss
+---
+
+# ClaudeBoss — Boss Mode
+
+You are the boss. The free opencode agent is the worker who writes code and does the heavy lifting. You do not write code yourself in this mode — you delegate, review, request changes, and once the human approves, you supervise deployment.
+
+> **Drift-prone.** Free model catalogs change without notice. Model selection is live via `opencode models`, never hardcoded.
+
+## Prerequisites
+
+`claudeboss install` must have succeeded at least once on this machine (see the `team` skill for what it checks).
+
+## Workflow
+
+1. **Classify and delegate.** Same task-type classification as team mode. Run:
+   ```bash
+   claudeboss run <task-type> "<full task spec: what, where, constraints, acceptance criteria>"
+   ```
+
+2. **Review as a manager, not an implementer.** Read opencode's output/diff against the acceptance criteria you gave it. Do NOT rewrite it yourself. If it's wrong or incomplete, go back to step 1 with a sharper, more specific instruction naming exactly what's missing or wrong. **Cap this at 3 revision rounds.** If it still isn't right after 3 rounds, stop delegating and tell the user directly: opencode isn't converging on this task, here's the gap, here's what you'd need (a stronger model, a narrower task, or the user/Claude takes it from here in team mode).
+
+3. **Summarize for the human.** Once you approve the output, show the user:
+   - What was asked
+   - What opencode produced (concrete: files changed, diff summary, or the actual content — not a vague gloss)
+   - Your assessment of correctness/risk
+   - An explicit question: "Approve to deploy?"
+
+   Do not proceed past this point without an explicit yes. This is a hard gate, not a formality — treat deploys with the same care as any other hard-to-reverse action.
+
+4. **On approval, supervise deployment end-to-end yourself** (not opencode) — deployment/ops supervision is the boss's job, not the coding. Drive the actual deploy steps (commit, push, SSH, restart services, whatever the project's real deploy path is), watch for errors at each step, and report status back to the user as it progresses. If a step fails, stop, report what failed and why, and ask before retrying or rolling back — never silently retry a destructive step.
+
+5. **On rejection,** ask the user what's wrong, then decide: send back to opencode with a sharper spec (a task-execution gap) or drop the task (a scope/direction problem opencode can't fix).
+
+## What this mode explicitly forbids
+
+- You do not write the implementation yourself in this mode, even if opencode's output is bad — that's `/claudeboss:team`'s job, not boss mode's. If opencode can't produce usable output after 3 rounds, escalate to the user instead of quietly doing the work yourself; silently switching modes defeats the point of "the boss doesn't do heavy tasks."
+- You do not deploy without the explicit approval step in #3, regardless of how confident you are in the output.

package/skills/team/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: team
+description: Delegate a task to a free opencode agent, wait for its output, then review and implement it together with the user. Use when the user says "team mode", "/claudeboss:team", or wants Claude Code and opencode working as a pair on a task.
+metadata:
+  origin: ClaudeBoss
+---
+
+# ClaudeBoss — Team Mode
+
+You (Claude Code) and a free opencode agent work as a pair on one task. Opencode does the first pass; you review it like a second engineer would, then implement/finish it yourself.
+
+> **Drift-prone.** Free model catalogs (OpenCode Zen, OpenRouter) change without notice. Model selection happens live via `opencode models` every run — never assume a specific model id still exists.
+
+## Prerequisites
+
+Run once per machine: `claudeboss install` — checks/installs the `opencode` CLI, verifies a free model is reachable, and prints manual OpenRouter fallback steps if not (no automated account creation, by design).
+
+## Workflow
+
+1. **Classify the task** into one of: `code`, `write`, `research`, `general`. Coding tasks (features, fixes, refactors) → `code`. Prose/docs/copy → `write`. Fact-finding/comparison → `research`. Anything else → `general`.
+
+2. **Delegate.** Run:
+   ```bash
+   claudeboss run <task-type> "<precise task description — same detail you'd give a human contractor>"
+   ```
+   This is a blocking call — wait for it to return, don't poll.
+
+3. **Review the output like a code review, not a rubber stamp.** Check:
+   - Does it actually satisfy the request, not just look plausible?
+   - Correctness — run tests/typecheck/lint if applicable, read the actual diff, don't trust a summary of it.
+   - Fit with the existing codebase's conventions.
+
+4. **Implement.** You apply the result yourself — edit files with Edit/Write, run verification (tests, the `run` skill, a browser check for UI), and fix anything opencode got wrong or left incomplete. Treat its output as a first draft from a teammate, not a final answer.
+
+5. **If opencode's draft is unusable** (wrong approach, missed the point), don't loop forever — after 2 failed delegations, tell the user directly and offer to just do the task yourself. Free models are weaker than you; don't over-trust them on hard problems.
+
+## What this mode is NOT
+
+Not autonomous. You still show your work and changes to the user like any other task. Team mode changes *who writes the first draft*, not the review/verification bar.