@hypercli/hq 0.1.1

package/help/hq/spawn.md

@@ -0,0 +1,47 @@
+# hyper hq spawn
+
+Spawn a new Claude session for a project.
+
+## Usage
+
+`hyper hq spawn <project> [flags]`
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `project` | Project name (looked up under your configured projects root) or an absolute path |
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--worktree <branch>` | Use an existing worktree by branch name |
+| `--new-worktree <branch>` | Create a new worktree via `wt switch -c` and spawn into it |
+| `--permission-mode <mode>` | Permission mode: `default`, `acceptEdits`, `plan`, or `auto` |
+| `--name <name>` | Custom session name (default: `hq-<project>[-<branch>]`) |
+
+## Examples
+
+```sh
+# Spawn a session for a project in your projects root
+hyper hq spawn my-project
+
+# Spawn using an absolute path
+hyper hq spawn /absolute/path/to/project
+
+# Spawn on an existing worktree
+hyper hq spawn my-project --worktree feat-auth
+
+# Create a new worktree and spawn into it
+hyper hq spawn my-project --new-worktree feat-login
+
+# Spawn with auto-permission mode
+hyper hq spawn my-project --permission-mode auto
+```
+
+## Notes
+
+- If a session for the project is already running, the command exits early and suggests `hyper hq attach <project>`.
+- Connect to the spawned session via claude.ai/code, the Claude mobile app, or `hyper hq attach <project>`.
+- If a Telegram bot is configured for the project in `hq.toml`, the session will use it automatically.

package/help/hq/start.md

@@ -0,0 +1,39 @@
+# hyper hq start
+
+Start the HQ session — always-on Claude Code command center.
+
+## Usage
+
+`hyper hq start [flags]`
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--name <name>` | Custom session name (default: from config) |
+| `--spawn-mode <mode>` | How new sessions are created: `same-dir`, `worktree`, or `session` |
+| `--permission-mode <mode>` | Permission mode for sessions: `default`, `acceptEdits`, `plan`, or `auto` |
+| `--capacity <n>` | Max concurrent sessions |
+
+## Examples
+
+```sh
+# Start HQ with defaults
+hyper hq start
+
+# Start with worktree spawn mode
+hyper hq start --spawn-mode worktree
+
+# Start with higher session capacity
+hyper hq start --capacity 16
+
+# Start in auto-permission mode (no approval prompts)
+hyper hq start --permission-mode auto
+```
+
+## Notes
+
+- The first run triggers an interactive setup wizard to create `~/.config/hyper/hq.toml`.
+- HQ runs as a tmux session in Claude's remote-control server mode — connect to it from claude.ai/code or the mobile app.
+- If a session with the same name is already running, the command exits early and suggests using `hyper hq attach`.
+- Flags override the corresponding values in your config file.

package/help/hq/status.md

@@ -0,0 +1,38 @@
+# hyper hq status
+
+Show running HQ sessions.
+
+## Usage
+
+`hyper hq status [flags]`
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output as JSON |
+
+## Examples
+
+```sh
+# Show all running HQ sessions
+hyper hq status
+
+# Output as JSON
+hyper hq status --json
+```
+
+## Output
+
+```
+HQ Sessions
+═══════════
+  hyper-hq                 ONLINE     2024-01-15  (HQ)
+  hq-my-project            ATTACHED   2024-01-15
+  hq-another-project       ONLINE     2024-01-15
+```
+
+- `ATTACHED` — a terminal is currently connected to the session.
+- `ONLINE` — the session is running but no terminal is attached.
+
+If no sessions are running, the command suggests `hyper hq start`.

package/help/hq/stop-all.md

@@ -0,0 +1,20 @@
+# hyper hq stop-all
+
+Stop all HQ-managed sessions.
+
+## Usage
+
+`hyper hq stop-all`
+
+## Examples
+
+```sh
+# Stop every running HQ session
+hyper hq stop-all
+```
+
+## Notes
+
+- Kills all tmux sessions whose names start with `hq`.
+- If no HQ sessions are running, the command exits cleanly with a message.
+- To stop a single session, use `hyper hq stop [session]`.

package/help/hq/stop.md

@@ -0,0 +1,31 @@
+# hyper hq stop
+
+Stop an HQ session.
+
+## Usage
+
+`hyper hq stop [session]`
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `session` | Session name or project name (default: `hyper-hq`) |
+
+## Examples
+
+```sh
+# Stop the main HQ session
+hyper hq stop
+
+# Stop a specific project session by project name
+hyper hq stop my-project
+
+# Stop a session by its full session name
+hyper hq stop hq-my-project
+```
+
+## Notes
+
+- If the argument does not start with `hq`, the prefix `hq-` is added automatically — so `hyper hq stop my-project` targets the session named `hq-my-project`.
+- To stop all HQ sessions at once, use `hyper hq stop-all`.

package/help/hq.md

@@ -0,0 +1,48 @@
+# hyper hq
+
+Always-on Claude Code command center. Manages persistent Claude sessions via tmux, accessible from claude.ai/code, mobile, and Telegram.
+
+## Usage
+
+`hyper hq <command> [options]`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `hyper hq start` | Start the HQ command center session |
+| `hyper hq stop [session]` | Stop an HQ session |
+| `hyper hq stop-all` | Stop all HQ-managed sessions |
+| `hyper hq attach [session]` | Attach to an HQ tmux session |
+| `hyper hq spawn <project>` | Spawn a Claude session for a project |
+| `hyper hq list` | List available projects and their worktrees |
+| `hyper hq status` | Show running HQ sessions |
+| `hyper hq config` | Show HQ configuration |
+
+## Quick Start
+
+```sh
+# 1. Start the HQ command center
+hyper hq start
+
+# 2. Check what projects are available
+hyper hq list
+
+# 3. Spawn a Claude session for a project
+hyper hq spawn my-project
+
+# 4. Check running sessions
+hyper hq status
+
+# 5. Attach to a session in your terminal
+hyper hq attach my-project
+
+# 6. When done, stop everything
+hyper hq stop-all
+```
+
+## How It Works
+
+HQ runs a persistent Claude Code instance in a tmux session in remote-control server mode. Once started, you can connect to it from claude.ai/code, the Claude mobile app, or via Telegram. From there, you can ask HQ to spawn sessions for any of your projects.
+
+Run `hyper hq <command> --help` for details on any command.

package/oclif.manifest.json

@@ -0,0 +1,395 @@
+{
+  "commands": {
+    "hq:attach": {
+      "aliases": [],
+      "args": {
+        "session": {
+          "description": "Session name or project name (default: hyper-hq)",
+          "name": "session",
+          "required": false
+        }
+      },
+      "description": "Attach to an HQ tmux session",
+      "examples": [
+        "<%= config.bin %> hq attach",
+        "<%= config.bin %> hq attach my-project"
+      ],
+      "flags": {
+        "debug": {
+          "char": "d",
+          "description": "Enable debug output",
+          "name": "debug",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "hq:attach",
+      "pluginAlias": "@hypercli/hq",
+      "pluginName": "@hypercli/hq",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "hq",
+        "attach.js"
+      ]
+    },
+    "hq:config": {
+      "aliases": [],
+      "args": {},
+      "description": "Show HQ configuration",
+      "examples": [
+        "<%= config.bin %> hq config",
+        "<%= config.bin %> hq config --json",
+        "<%= config.bin %> hq config --path"
+      ],
+      "flags": {
+        "debug": {
+          "char": "d",
+          "description": "Enable debug output",
+          "name": "debug",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "json": {
+          "description": "Output as JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "path": {
+          "description": "Print config file path only",
+          "name": "path",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "hq:config",
+      "pluginAlias": "@hypercli/hq",
+      "pluginName": "@hypercli/hq",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "hq",
+        "config.js"
+      ]
+    },
+    "hq:list": {
+      "aliases": [],
+      "args": {},
+      "description": "List available projects and their worktrees",
+      "examples": [
+        "<%= config.bin %> hq list",
+        "<%= config.bin %> hq list --json",
+        "<%= config.bin %> hq list --root /path/to/projects"
+      ],
+      "flags": {
+        "debug": {
+          "char": "d",
+          "description": "Enable debug output",
+          "name": "debug",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "root": {
+          "description": "Override projects root directory",
+          "name": "root",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "json": {
+          "description": "Output as JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "hq:list",
+      "pluginAlias": "@hypercli/hq",
+      "pluginName": "@hypercli/hq",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "hq",
+        "list.js"
+      ]
+    },
+    "hq:spawn": {
+      "aliases": [],
+      "args": {
+        "project": {
+          "description": "Project name (under projects root) or absolute path",
+          "name": "project",
+          "required": true
+        }
+      },
+      "description": "Spawn a new Claude session for a project",
+      "examples": [
+        "<%= config.bin %> hq spawn my-project",
+        "<%= config.bin %> hq spawn my-project --worktree feat-auth",
+        "<%= config.bin %> hq spawn my-project --new-worktree feat-login",
+        "<%= config.bin %> hq spawn /absolute/path/to/project"
+      ],
+      "flags": {
+        "debug": {
+          "char": "d",
+          "description": "Enable debug output",
+          "name": "debug",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "worktree": {
+          "description": "Use an existing worktree (branch name)",
+          "name": "worktree",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "new-worktree": {
+          "description": "Create a new worktree via wt switch -c",
+          "name": "new-worktree",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "permission-mode": {
+          "description": "Permission mode",
+          "name": "permission-mode",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "default",
+            "acceptEdits",
+            "plan",
+            "auto"
+          ],
+          "type": "option"
+        },
+        "name": {
+          "description": "Custom session name",
+          "name": "name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "hq:spawn",
+      "pluginAlias": "@hypercli/hq",
+      "pluginName": "@hypercli/hq",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "hq",
+        "spawn.js"
+      ]
+    },
+    "hq:start": {
+      "aliases": [],
+      "args": {},
+      "description": "Start the HQ session — always-on Claude Code command center",
+      "examples": [
+        "<%= config.bin %> hq start",
+        "<%= config.bin %> hq start --spawn-mode worktree",
+        "<%= config.bin %> hq start --capacity 16"
+      ],
+      "flags": {
+        "debug": {
+          "char": "d",
+          "description": "Enable debug output",
+          "name": "debug",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "name": {
+          "description": "Custom session name",
+          "name": "name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "spawn-mode": {
+          "description": "How new sessions are created",
+          "name": "spawn-mode",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "same-dir",
+            "worktree",
+            "session"
+          ],
+          "type": "option"
+        },
+        "permission-mode": {
+          "description": "Permission mode for sessions",
+          "name": "permission-mode",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "default",
+            "acceptEdits",
+            "plan",
+            "auto"
+          ],
+          "type": "option"
+        },
+        "capacity": {
+          "description": "Max concurrent sessions",
+          "name": "capacity",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "hq:start",
+      "pluginAlias": "@hypercli/hq",
+      "pluginName": "@hypercli/hq",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "hq",
+        "start.js"
+      ]
+    },
+    "hq:status": {
+      "aliases": [],
+      "args": {},
+      "description": "Show running HQ sessions",
+      "examples": [
+        "<%= config.bin %> hq status",
+        "<%= config.bin %> hq status --json"
+      ],
+      "flags": {
+        "debug": {
+          "char": "d",
+          "description": "Enable debug output",
+          "name": "debug",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "json": {
+          "description": "Output as JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "hq:status",
+      "pluginAlias": "@hypercli/hq",
+      "pluginName": "@hypercli/hq",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "hq",
+        "status.js"
+      ]
+    },
+    "hq:stop-all": {
+      "aliases": [],
+      "args": {},
+      "description": "Stop all HQ-managed sessions",
+      "examples": [
+        "<%= config.bin %> hq stop-all"
+      ],
+      "flags": {
+        "debug": {
+          "char": "d",
+          "description": "Enable debug output",
+          "name": "debug",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "hq:stop-all",
+      "pluginAlias": "@hypercli/hq",
+      "pluginName": "@hypercli/hq",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "hq",
+        "stop-all.js"
+      ]
+    },
+    "hq:stop": {
+      "aliases": [],
+      "args": {
+        "session": {
+          "description": "Session name or project name (default: hyper-hq)",
+          "name": "session",
+          "required": false
+        }
+      },
+      "description": "Stop an HQ session",
+      "examples": [
+        "<%= config.bin %> hq stop",
+        "<%= config.bin %> hq stop my-project"
+      ],
+      "flags": {
+        "debug": {
+          "char": "d",
+          "description": "Enable debug output",
+          "name": "debug",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "hq:stop",
+      "pluginAlias": "@hypercli/hq",
+      "pluginName": "@hypercli/hq",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "hq",
+        "stop.js"
+      ]
+    }
+  },
+  "version": "0.1.1"
+}