@generativereality/cctabs 0.1.4 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@generativereality/cctabs",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "Claude Code tab manager. Terminal tabs as the UI, no tmux.",
   "type": "module",
   "bin": {
@@ -19,6 +19,8 @@
     "check": "npm run typecheck && npm run build",
     "release": "bumpp && npm publish",
     "sync-plugin": "bash scripts/sync-plugin.sh",
+    "build:tabby-plugin": "cd tabby-plugin && npm install && npm run build",
+    "publish:tabby-plugin": "cd tabby-plugin && npm publish --access public",
     "prepack": "bash scripts/sync-plugin.sh --check && npm run build"
   },
   "keywords": [

package/skills/cctabs/SKILL.md

@@ -5,7 +5,7 @@ description: Manage Claude Code sessions across terminal tabs (NOT browser tabs)
 
 You are managing Claude Code sessions using the `cctabs` CLI.
 
-**Important:** "tabs" here means **terminal tabs** (e.g. Wave Terminal tabs), NOT browser tabs. Each terminal tab runs its own Claude Code session. This skill is for managing those terminal-based Claude Code sessions — not for browser automation.
+**Important:** "tabs" here means **terminal tabs** (Wave Terminal or Tabby), NOT browser tabs. Each terminal tab runs its own Claude Code session. This skill is for managing those terminal-based Claude Code sessions — not for browser automation.
 
 ## Before you spawn anything: is cctabs the right tool?
 
@@ -37,6 +37,64 @@ npm install -g @generativereality/cctabs
 
 Do not modify PATH or npm configuration beyond this.
 
+### Tabby users: a one-time plugin install is needed
+
+Wave Terminal works out of the box. **Tabby additionally needs a small companion plugin** that exposes a localhost HTTP API the cctabs CLI talks to.
+
+You don't need to detect this proactively — every cctabs command will fail with a self-documenting error if the plugin isn't running:
+
+```
+cctabs Tabby plugin not reachable at http://127.0.0.1:3300.
+  reason: …
+Install + restart Tabby in one shot from inside a Tabby tab:
+  cctabs install-tabby-plugin
+…
+```
+
+When you see that error, ask the user once:
+
+> *"You're in Tabby and the cctabs plugin isn't installed. I can `cctabs install-tabby-plugin --yes` — that npm-installs the plugin AND restarts Tabby in the background, dropping you back into a forked session. Caveat: any other Tabby tabs you have open will be killed. OK?"*
+
+On approval, run `cctabs install-tabby-plugin --yes`. Tabby quits ~2s after the command returns, reopens automatically, and spawns a new tab with your forked claude session. **Your current turn ends when Tabby quits**; the resumed claude in the new tab is where the user will continue.
+
+If the user wants to keep their other Tabby tabs intact, run `cctabs install-tabby-plugin --no-restart` instead and tell them to quit + reopen Tabby themselves.
+
+`cctabs doctor` is also available for a deliberate environment check (terminal, Wave Accessibility, plugin reachability, Wave DB) — useful if something feels off, but **not required as a preflight** since every command fails loudly on its own.
+
+#### Auto-install + auto-restart (recommended)
+
+```bash
+cctabs install-tabby-plugin --yes
+```
+
+What it does, in order:
+1. `npm install --legacy-peer-deps --prefix <tabby-plugins-dir> tabby-cctabs`
+2. Captures the current claude session id from `~/.claude/projects/<slug>/`
+3. Spawns a detached background worker that quits Tabby, waits for it to die, reopens it, then opens a new tab running `claude --resume <id> --fork-session` in your current cwd.
+
+**Other Tabby tabs in the same window get killed.** Tabby's session recovery may or may not bring them back. Use `--no-restart` to skip step 3 if the user wants control.
+
+#### Manual install (fallback)
+
+```bash
+TABBY_PLUGINS="$HOME/Library/Application Support/tabby/plugins"
+mkdir -p "$TABBY_PLUGINS"
+[ -f "$TABBY_PLUGINS/package.json" ] || echo '{"private":true}' > "$TABBY_PLUGINS/package.json"
+npm install --legacy-peer-deps --prefix "$TABBY_PLUGINS" tabby-cctabs
+# then ask the user to quit + reopen Tabby
+```
+
+`--legacy-peer-deps` is required: the plugin's peer deps (`tabby-core`, `@angular/*`, …) live inside Tabby itself, not on npm. Tabby's GUI plugin manager handles this internally.
+
+Linux: replace `~/Library/Application Support/tabby` with `${XDG_CONFIG_HOME:-$HOME/.config}/tabby`.
+Windows: `%APPDATA%\tabby`.
+
+#### Alternative: install via Tabby's GUI
+
+If the user prefers, point them at Tabby → **Settings → Plugins**, search "cctabs", click install, then quit + reopen Tabby. Same end state.
+
+Do not assume "no Wave detected → cctabs unusable" — Tabby is fully supported.
+
 ---
 
 Each Claude Code session runs in its own **terminal tab**. `cctabs` lets you — and other Claude Code sessions — introspect and orchestrate the full session fleet.
@@ -70,6 +128,7 @@ cctabs new fix-api ~/Dev/myapp --worktree --prompt "checkout PR #102 and fix tes
 cctabs sessions                          # list all tabs with session status
 cctabs list                              # list all workspaces, tabs, and blocks
 cctabs new <name> [dir] [-w workspace] [-p "prompt"] [-f file]  # new tab + claude
+cctabs new <name> [dir] -b <preset>      # new tab on a non-Anthropic backend (Ollama)
 cctabs resume <name> [dir]               # resume last session (reuses tab or creates one)
 cctabs restore [dir] [--dry]             # resume every dead tab (e.g. after a reboot)
 cctabs fork <tab-name> [-n new-name]     # fork session into new tab (--resume <id> --fork-session)
@@ -77,9 +136,74 @@ cctabs close <name-or-id>                # close a tab
 cctabs rename <name-or-id> <new-name>    # rename a tab
 cctabs scrollback <tab-or-block> [n]    # read terminal output (default: 50 lines)
 cctabs send <tab-or-block> [text]        # send input — arg, --file, or stdin pipe
+cctabs backends                          # list available backend presets
 cctabs config                            # show config and path
 ```
 
+## Backends: running Claude Code on Ollama / Kimi / Qwen / local models
+
+By default, `cctabs new` runs `claude` against the Anthropic API. Pass `--backend <preset>` (or `-b`) to launch the tab against a different model provider — useful for cheap/free scratch sessions, privacy-sensitive work, or experimenting with frontier open-weight models.
+
+`cctabs` does this by prepending the right env vars (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, etc.) and `--model <name>` to the `claude` command in the new tab.
+
+### Built-in presets
+
+Run `cctabs backends` for the live list. Common ones:
+
+| Preset | What it is | When to use |
+|---|---|---|
+| `anthropic` (default) | Anthropic API | Production / coding work where capability matters |
+| `kimi` | Kimi K2.6 via Ollama Cloud (Pro tier) | Cheap frontier alternative; ~5s/turn |
+| `qwen-cloud` | Qwen3 Coder Next via Ollama Cloud | Fastest Pro option (~3.8s/turn) |
+| `gemma-cloud` | Gemma4 31B via Ollama Cloud | Cheap general-purpose |
+| `qwen-local` | Qwen3 Coder 30B local (18GB) | Offline / private; slow on M1 |
+| `qwen-next-local` | Qwen3 Coder Next Q3_K_M local (38GB) | Private + most capable local; needs `ollama create` import |
+| `gpt-oss` | gpt-oss 20B local (13GB) | Private; slow; ~100s/turn for 50k system prompt |
+| `llama` | Llama 3.1 8B local | Fast but garbles inside Claude Code's 50k system prompt — capability gate |
+| `*-tee` | Same as above but routed through `:11500` proxy | Wire-level inspection (`ollama-tee` proxy must be running) |
+
+### Cost × privacy framing
+
+Two axes matter:
+
+1. **Cost** — Anthropic Pro $20/mo or Max ($100/$200/mo); Ollama Cloud Pro $20/mo (3 concurrent, includes Kimi/Qwen Cloud); local = free but hardware-bound
+2. **Privacy** — Anthropic API: Anthropic sees prompts. Ollama Cloud: Ollama sees prompts. Local: nothing leaves the laptop
+
+Match the tier to the task:
+- Sensitive prompts (client code, customer data) → `qwen-next-local` or `gpt-oss`
+- Routine exploration / orchestration → `anthropic` (default)
+- Cost-sensitive bulk work → `kimi` or `qwen-cloud`
+
+### Examples
+
+```bash
+# Spin up a tab on Kimi for a side experiment
+cctabs new explore-kimi ~/Dev/myapp -b kimi -p "explore alternative API designs"
+
+# Local privacy session, slower but no data leaves the laptop
+cctabs new private-refactor ~/Dev/clientwork -b qwen-next-local -W
+
+# Compare two models on the same task in parallel
+cctabs new task-anthropic ~/Dev/myapp -p "implement spec X"
+cctabs new task-kimi ~/Dev/myapp -b kimi -p "implement spec X"
+
+# Custom local Ollama tag not in built-in presets:
+cctabs new x ~/Dev/myapp -b qwen-local -m my-custom-tag:latest
+```
+
+### Caveats
+
+- **Local backends are slow on M1.** A Claude Code turn against the local 50k-token system prompt takes ~100s prefill + generation on M1 Max. Only worth it for non-time-sensitive private work.
+- **Llama 3.1 8B garbles tool calls** under Claude Code's system prompt. Capability gate, not a bug.
+- **Ollama Cloud Pro requires `ollama signin`** (one-time). Free tier denies cloud-tagged models.
+- **Custom presets** can be added in `~/.config/cctabs/config.toml`:
+  ```toml
+  [backends.my-preset]
+  model = "qwen3-coder-next:cloud"
+  base_url = "http://localhost:11434"
+  description = "My custom preset"
+  ```
+
 ## Workflow: Checking What's Running
 
 Before starting new sessions, always check what's already active:
@@ -251,17 +375,19 @@ cctabs new feature ~/Dev/myapp --worktree
 
 ## Handling `cctabs new` Timeout Errors
 
-`cctabs new` may occasionally fail with "Timed out waiting for new terminal block". This does **NOT** mean you have too many tabs or that Wave Terminal has hit a limit.
+`cctabs new` may occasionally fail with "Timed out waiting for new terminal block" (or, on Tabby, "Shell prompt never appeared in new tab"). This does **NOT** mean you have too many tabs or that the terminal has hit a limit.
 
-**Possible causes** (root cause not yet confirmed):
-- Wave Terminal may need to be in focus / foreground for tab creation to register
-- The internal timeout may be slightly too short for the current system load
-- Transient IPC timing issue between cctabs and Wave
+**Possible causes:**
+- The terminal app may need to be in focus / foreground for tab creation to register (true for both Wave and Tabby).
+- The internal timeout may be slightly too short for the current system load.
+- Transient IPC timing issue between cctabs and the terminal.
+- **Tabby only:** the cctabs plugin must be installed and running (`curl http://127.0.0.1:3300/api/health` to verify).
 
 **What to do:**
 1. **Retry the same command** — it often works on the second attempt
 2. If it fails again, wait a few seconds and retry once more
-3. If it keeps failing, ask the user to bring Wave Terminal to the foreground and try again
+3. If it keeps failing, ask the user to bring the terminal app to the foreground and try again
+4. On Tabby, also confirm the plugin is reachable (see health check above)
 
 **What NOT to do:**
 - ❌ Do NOT assume there is a "tab limit" — there isn't one