# BugTape Live terminal BugTape Live is an interactive, authenticated issue inbox for the command line. It polls BugTape's existing issue API and does not invent a new event bus. ## Start in your repository Node.js 20 or later. `npx` runs the `bugtape` package from npm; nothing else to install. ```bash npx -y bugtape live ``` **Shortcut:** `npx -y bugtape` with no command opens Live in a terminal. Install once with `npm i -g bugtape`, then type `bugtape`. Scripts, pipes and `--json` still get the help text. `live` guides your first sign-in: open the link, check the code, choose your workspace and click **Allow**. The inbox opens here after access is confirmed. A saved sign-in is reused; an expired sign-in is renewed first. Use `--no-browser` to open the link yourself, or `live --switch` to choose another workspace. If `BUGTAPE_TOKEN` is set, it selects the workspace; unset it before switching. The header names your workspace, repository and project. Live uses an explicit project, a choice saved for this repository and workspace, a known capture-key project, a unique folder-name match, or the workspace's only project. With several projects it asks you to choose before loading any issues. Press **W** to choose another project. **All projects** is an explicit choice. A missing saved project asks you to choose again. ```bash npx -y bugtape live --project "My app" npx -y bugtape live --project-id npx -y bugtape live --all-projects ``` These options select existing projects; they do not create them. Changing project or workspace clears the old selection and inbox. An empty inbox offers `npx -y bugtape init` to set up capture. Network failures retry and label saved data. Loss of access clears the inbox and offers sign-in inside Live. ## Sign in without leaving Live Press **L**, or press **:** and type `login`, then Enter. The terminal shows your approval link and code. Check the code in your browser, choose the workspace, then click **Allow**. Live returns to the project picker or your saved project after approval. Escape cancels and returns to Live. If your previous sign-in still works, its inbox returns. A declined or expired code shows a retry. Temporary connection failures retry with the same approval code. Ctrl+C exits. `BUGTAPE_TOKEN` overrides saved sign-in, so Live explains how to unset it before changing workspace. The **:** menu also accepts `projects`, `project `, `project all`, `mouse on`, `mouse off`, `refresh`, `help` and `quit`. These are Live commands, not a system shell. ## What you see A header band names BugTape Live and the connection state. Under it are your workspace, repository and project, and buttons for Project, Login, Commands and Mouse. When the terminal is at least 80 columns by 24 rows, a toolbar adds **Search issues**, **High+ only** and **Preview agent handoff**. These do the same as `/`, **F** and **P**. Each issue row shows the time, the level and the title, with the report count on the right. Critical and High are red, Medium is orange and Low is muted. The focused issue is bold on a shaded band. Its details are in a box at the bottom, with the title in the top edge. Key hints show the key in orange and the word after it. Smaller terminals keep the dense list. `--no-colour` (or `NO_COLOR=1`) gives the same layout in plain text, and **T** switches between light and dark. ## Optional mouse controls Press **M**, type `:mouse on`, or start with `--mouse`. In terminals that support SGR mouse reporting you can click header controls, choose a project, click an issue to inspect it, or click its selection circle. The wheel moves through issues and projects. In a hand-off, you can click Back or Review; launching an agent always requires the keyboard. Keyboard controls always work. Mouse mode starts off so native text selection works. Press M or type `:mouse off` to restore it. Mouse reporting is off during sign-in and agent work, and is restored on exit. CLI login and agent MCP authorisation are separate. `login` signs the terminal in; `connect claude` connects the agent. `npx -y bugtape init` checks the ingest route, but its generated test is not proof the SDK is installed in your own app. Reproduce a recognisable error there and verify it reached the correct project. ## Keyboard quick reference | Key | Action | | --- | --- | | ↑ / ↓ or J / K | Navigate issues or project choices | | Page Up / Page Down | Move one page through issues or projects | | Home / End | Jump to the first or last issue or project | | Tab / Shift+Tab | Focus the next or previous visible button | | Space | Select and deselect issues | | Enter | Activate the focused button; otherwise inspect the issue or choose a project | | / | Search by issue title, project or ID | | W | Choose the project | | L | Sign in or change workspace inside Live | | : | Enter a Live command, such as `login` | | M | Toggle optional mouse controls | | F | Filter High and Critical issues | | P | Preview a hand-off | | S, then Enter | Review the launch, then confirm with the keyboard | | A | Change target: Claude Code, Codex, Cursor | | T | Toggle BugTape light/dark colours | | R | Refresh | | ? | Show help | | Esc | Go back one step; cancel search edits; clear filters from the feed | | Q / Ctrl+C | Exit | ## How the agent hand-off works Select up to ten issues and choose P then S. The preview lists the exact issue IDs and titles and holds that selection while you confirm. It marks selected issues hidden by your current filters. A small terminal must be enlarged before an agent can launch. The terminal starts a locally installed Claude Code or Codex process with the selected issue IDs, project names/IDs, workspace and repository name. It sends no issue titles or captured events. The agent must check its repository and MCP workspace before proposing a patch. It reads evidence using its **own MCP authorisation** and asks before editing code or opening a pull request. Cursor receives a ready-to-paste prompt, not an automated process launch. This first version does not impersonate a human to call `POST /v1/bugs/:id/notify-agent`. That endpoint remains human-session-only. For server-side queued agent notifications use the console's **Send to agent** action. ## Automation ```bash npx -y bugtape live --once --project "My app" npx -y bugtape live --once --json --project "My app" npx -y bugtape live --json --interval 10 --all-projects npx -y bugtape live --theme light npx -y bugtape live --no-colour ``` Use `--project ` or `--project-id ` to select one project and `--interval` between 2 and 60 seconds. Machine modes use the same saved project, capture-key and folder matching as Live. If several projects still match, they exit with `PROJECT_REQUIRED`; pass a project or `--all-projects` instead of guessing. The feed shows up to 80 recent issues. `--json` emits snapshots, not guaranteed durable events. A non-interactive terminal requires `--json` or `--once`. `--once` and `--json` require a saved sign-in or `BUGTAPE_TOKEN` and never start browser approval. Sign in once with `npx -y bugtape login` before running them. Auth and permission failures emit one error and exit with status 1. JSON errors include `code`, `message`, `action` and `retryable`; transient stream failures retry without emitting an empty snapshot. ## Privacy and correctness Only issue and project metadata is fetched by the terminal. No raw DOM replay, tokens, user data or sensitive captured events are passed in agent CLI arguments. Evidence reads through MCP use the agent's own permission and can consume plan credits. CLI sign-in and agent MCP authorisation are separate. Windows users open the printed approval link manually; local agent launch on Windows is not yet qualified. Do not place capture keys in MCP configurations. A local agent starting, exiting, opening a PR or claiming a bug is not proof of a fix. Verify the repaired release independently. Unsupported terminal colours can be switched off with `NO_COLOR` or `--no-colour`, and CI/--no-motion avoid unnecessary effects. Error titles are sanitised for terminal output, never used as shell commands. ## How-to: your first issue 1. Run [Quickstart](/docs/quickstart/), install the SDK, then trigger a real error in your app. 2. [Connect your coding agent](/docs/mcp-install/) with its independent MCP credentials. 3. Start `live`, navigate with arrows, and select issues with Space. 4. Preview the hand-off, choose an agent, and confirm. 5. Review the agent's diagnosis and any proposed patch. Check the fix against a repaired release. [CLI guide](/docs/cli/) · [MCP tools](/docs/mcp-tools/) · [Agent lifecycle](/docs/agents/) · [Privacy checklist](/docs/privacy-proof-checklist/).