In-CLI feedback / bug reporting (`devflow feedback` + in-session hotkey, no browser)

[karava]

Problem

The feedback channel is decided — GitHub Issues (see #11: repo is public, bug_report.md template + package.json bugs URL landed in ffa40dd). But there's still no way to give feedback from inside the CLI itself. A user who hits a bug mid-session has to know to go find the GitHub repo. We want reporting to be a first-class, terminal-native flow.

Captured from discussion: prefer GitHub Issues over the old idea of pushing to a Google Form.

Goal

Let a user report a bug / send feedback without leaving the terminal and without opening a browser — a complete submission flow in the CLI — plus a way to do it mid-session without tearing down the timer/music.

Proposed UX

1. devflow feedback command — complete in-CLI submission flow

• Prompt for the message (multi-line; e.g. finish with an empty line or Ctrl+D).
• Auto-attach low-noise context: CLI version, OS/arch, Node version, and current mode/channel if a session is active. Show the user exactly what will be sent and confirm before submitting.
• Submit directly and print the resulting issue URL. No browser.

2. In-session hotkey

• While devflow start is running, a key (e.g. f) opens a quick feedback capture without ending the session. The countdown redraw + music keep going (or pause cleanly) and resume after submit.
• Note: start.ts runs stdin in raw mode and swallows stray keystrokes today — this needs a deliberate "suspend redraw → read a line → restore" path. Must stay best-effort: a failure here can never crash or corrupt the session.

Architecture — the key constraint: no browser

Filing a GitHub issue directly from a published npm CLI means we cannot ship a GitHub token. Options:

• (Recommended) Server endpoint on devflow.fm. Add POST /api/feedback (in the web repo) that holds a server-side GitHub token and creates the issue. The CLI just POSTs { message, context } to it — exactly the pattern src/lib/listener.ts already uses for the heartbeat. Override via DEVFLOW_FEEDBACK_URL (cf. DEVFLOW_CHANNELS_URL).
  • ⚠️ This half lives in the separate devflow.fm web repo, not this one — needs to be built there first (or in parallel).
• Fallback: if the endpoint is unreachable/offline, fall back to printing (and optionally opening) a prefilled GitHub new-issue URL using the bug_report.md template, so feedback is never a dead end.
• Rejected as primary: requiring the user to create a personal access token (too much friction for a focus tool).

Analytics tie-in

We also want to capture some analytics alongside this. Feedback submissions are a natural event to record (count, version spread, was-a-session-active), and the anonymous-context idea overlaps heavily with #7 (anonymous CLI usage telemetry). Decide whether the feedback endpoint and the telemetry endpoint share infrastructure, and keep the privacy stance consistent.

Privacy

• Anonymous by default — no PII, no file paths, no usernames in the auto-attached context.
• Show the payload before sending; submission is explicit/opt-in by nature (the user typed it).

Acceptance

• devflow feedback files a GitHub issue end-to-end with no browser, and prints the issue URL.
• Context (version, OS, mode/channel) is attached and shown before sending.
• A session can be reported from via an in-session hotkey without ending it.
• Graceful fallback when the endpoint is unreachable.
• devflow.fm POST /api/feedback endpoint exists (tracked in the web repo).

Refs

• Decide repo visibility (public vs private) + set up a user feedback / bug-reporting channel #11 (feedback channel decision — this is the in-CLI surface it left open)
• Anonymous CLI usage analytics (telemetry) #7 (anonymous telemetry — shared endpoint/privacy considerations)
• Add README (with Reporting bugs + install/usage sections) #12 (README "Reporting bugs" section should mention devflow feedback)
• Precedent for best-effort API POST: src/lib/listener.ts

[karava]

Consolidating #36 into this issue (duplicate — same ask: terminal-native feedback without a browser, both as a CLI flag and an in-session option).

User report from #36:

It always opens in GitHub in a browser when I want to leave feedback. Would be good to have the option to have it in the terminal only. Also there is the potential to have it as a cli option, then there is the option to have it in the interactive session itself that's in full screen. But is dangerous — we don't want to break any of the UI.

Reported from an active session — mode: pomodoro, channel: deepfocus.

Current state: devflow feedback exists but only opens a pre-filled GitHub URL in the browser. The no-browser in-CLI submission + the in-session (full-screen) capture path are the open work here. Tagged claude-do so the runner can pick it up.

[karava]

🤖 claude-do runner picking this up…