BugTape docs

BugTape Live terminal

Watch errors, filter and hand selected issues to your connected coding agent.

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.

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.

npx -y bugtape live --project "My app"
npx -y bugtape live --project-id <uuid>
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 <name or ID>, 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

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

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 <name> or --project-id <uuid> 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, install the SDK, then trigger a real error in your app.
2. Connect your coding agent 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 · MCP tools · Agent lifecycle · Privacy checklist.