better-claude-config/HANDOFF.md

HANDOFF — BCC feature backlog implementation

For the Claude Code agent working in this repo. Read this whole file, then CLAUDE.md, before touching code. A supervising Claude session watches this project through the Gitea MCP (issues, PRs, CI runs on git.avezzano.io), so keep all state in Gitea where it can be seen: issues for work items, PRs for changes, comments for decisions.

Step 0 — sync state

main may contain local commits that aren't on origin yet (the previous session couldn't push). Run git status / git log origin/main..main; if there are unpushed commits, push them first and confirm CI goes green before starting anything.

Step 1 — file the backlog as issues

Create one Gitea issue per item in the backlog table below (tea CLI or the API — you have full credentials). Prefix titles with the ID (e.g. "[#2] Stdio server spawn-test"). Create labels P0/P1/P2 first if they don't exist. Copy each item's full section from ../bcc-feature-requests.md (sibling of this repo folder) into the issue body — it has problem statements, evidence, proposed fixes, and acceptance criteria.

Corrections to that document — do not re-implement:

• "Doc correction: README Claude Code path" — DONE (commit b16c0fd).
• Item 1 (secret masking) — MOSTLY DONE (commit 6dee318): env/header values masked via delegate + Show-secrets toggle, Add-dialog password echo, diagnostics args redaction (redact_args). Only remainder: the warning badge when a secret-shaped value sits in args instead of env. File the issue scoped to just that.

Step 2 — work the backlog

Order	ID	Item	Priority	Notes
1	2	Stdio server spawn-test	P0	Spawn with timeout, capture stderr; core logic in bcc_core (GUI-free, testable)
2	3	Backup restore UI	P0	List .bcc_backups/, preview/diff, restore through normal atomic-write path
3	4	Stale-file protection	P0	mtime/hash at load, re-check before write, prompt on conflict
4	1r	Secret-in-args warning badge	P0	Remainder of item 1; is_secret_key/_is_secret_value already exist in bcc_core
5	8	Duplicate-name conflict on paste/import	P1	VERIFY FIRST: check paste_json/dropEvent in bcc.py for silent overwrite; file findings on the issue before coding
6	5	Cross-client support (Cursor/Windsurf/VS Code)	P1	VS Code uses servers not mcpServers — needs a read/write adapter, not just paths
7	6	In-app MCP log viewer	P1	Platform log paths in the doc
8	7	Windows MSIX path detection	P1	Can't test locally on macOS — unit-test the detection logic, note that in the PR
9	9	Restart Claude Desktop button	P1	Platform-specific process handling; scope to Desktop only
10	10	Server catalog / one-click add	P2	Design pass first — post a proposal as an issue comment before building

Workflow rules

• Branch per issue off main: feat/<issue-number>-short-slug (or fix/). One issue per PR. Reference the issue in the PR description (Closes #N).
• Before every commit: python -m pytest (all green), ruff check ., ruff format .. CI enforces all three.
• Conventional commits (feat:, fix:, test:, docs:, chore:) — match the existing history's style: body explains the why.
• Merge only with green CI. If the supervising session has flagged something on the PR, resolve it before merging.

Architecture guardrails (violating these fails review)

1. The cardinal rule: config writes only ever touch mcpServers and _disabledMcpServers. Every other key is preserved verbatim, in order. This matters extra for ~/.claude.json, which holds conversation history and project state.
2. Core/GUI split: all logic in bcc_core.py (no GUI imports, unit- testable); bcc.py stays a thin PySide6 shell. New logic gets tests in tests/ — they run without PySide6, keep it that way.
3. No new runtime dependencies without posting the justification on the issue first. PySide6 is currently the only one.
4. Writes are atomic + backed up — route any new disk writes through write_config().
5. Secrets never appear in diagnostics output or logs — use redact_args/ is_secret_key from bcc_core.

Current state (as of this handoff)

• 92 tests in tests/test_core.py, ruff clean, CI = lint + pytest (py3.10/3.12).
• main = ece049c (PR #16 merged). No unpushed commits.
• Completed items: #2 (spawn-test, PR #11), #3 (backup restore UI, PR #14), #4 (stale-file protection, PR #15), #1r (secret-in-args warning, PR #16).
• Next item: #8 — duplicate-name conflict handling. VERIFY FIRST: read paste_json and dropEvent in bcc.py to check whether pasting/dropping a server with a name that already exists silently overwrites it; file your findings as a comment on issue #8 before writing any code.
• Recent features you should know exist: lenient JSON repair (repair_json_text, parse_pasted_json_verbose, repair_config_file + RepairDialog), ArgsEdit numbered gutter + split_suspicious_args, resizable splitters with QSettings persistence, secret masking, Claude Code profile at ~/.claude.json (settings.json only as "legacy" when it holds parked servers), backup restore UI (RestoreDialog, list_backups, backup_diff, restore_backup), stale-file protection (StaleDialog, config_mtime, external_change_summary).
• GUI can't be smoke-tested in CI; note in each PR whether you ran python bcc.py locally and what you checked.