Bolt-Console/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A PySide6 desktop app (default) and a terminal REPL (--cli), both Claude Code-style, on top of an external Bolt server's desk API. It uses the same brain, memory, tools and persona as the server's Discord bot and its other desk clients. There is no import dependency on the server repo: it's a standalone HTTP client configured through its own .env. It was forked from Bolt-Pet with the desktop pet, wake word, STT/TTS, screen context/OCR, notifications, auto-updater and self-restart removed.

Pipeline: typed line → + cwd/OS note → POST /desk/converse_stream (or /desk/converse) → [server relays a command: filectl file op, or a shell command, after y/n approval] → /desk/tool_result → … → reply printed.

Commands

run.bat / run-cli.bat / ./run.sh [--cli]   # window / terminal; creates .venv; keeps the caller's cwd
python -m bolt_console --doctor [--deep]
python -m bolt_console -p "message"   # one-shot
.venv/Scripts/python -m pytest tests  # (.venv/bin on Linux/macOS)

Runtime dependencies: requests, plus PySide6 for the window only. bolt_console.gui is imported lazily, so --cli works without Qt. The local venv is Python 3.9, so no match, no runtime X | Y unions, and no builtin generics outside annotations.

Architecture (bolt_console/)

• config.py: a small hand-written .env parser feeding module constants. Nothing else reads os.environ. SESSION_ID defaults to pet-console-<host>. The pet- prefix is deliberate: the server advertises filectl to pet sessions, and -console keeps this a separate conversation from a Bolt-Pet on the same machine. new_session() (New chat / /new) rotates to <base>-<timestamp> and remembers it in ~/.cache/bolt-console/session.json. DESK_SESSION_ID in .env overrides the remembered id. Tests must monkeypatch config.STATE_FILE.
• server_client.py: the desk protocol. _relay() is the shared command → tool_result loop. converse_stream() hands each say sentence over as it arrives and finishes a tool call through _relay. It raises ServerError only if nothing was shown yet, which lets the caller fall back to converse() invisibly. Reply.streamed means "already on screen, don't print again". run_local_command runs in os.getcwd() with stdin closed and CREATE_NO_WINDOW, because under pythonw every cmd.exe would otherwise flash a console.
• tools.py: Tools, the on_command callable. It routes filectl to file_ops, answers petctl/dialoguectl with PET_UNAVAILABLE (the server may still emit them), and treats anything else as a shell command. Approval: reads and lists never ask. Shell, write and edit ask via ui.confirm unless mode == "auto", and "always" switches the session to auto. A decline returns DECLINED to the model rather than raising, so the turn still completes.
• file_ops.py: filectl {json} list/read/write/edit. It is a single-line JSON wire format because the server's command marker only captures to the first newline. edit must match exactly once. Parsing (parse) is separate from I/O (execute).
• relay_json.py: lenient JSON for model-typed payloads. It tries strict parsing first, then named repairs (fences, smart quotes, invalid backslash escapes, stray quotes, trailing commas, Python literals, single quotes), and accepts a repair only if the result parses. Repairs are always reported back to the model, never silent. The backslash repair only touches invalid escapes, so C:\temp still parses as a tab (that's ambiguous, so it's left alone).
• ui.py: Terminal handles plain ANSI rendering, the spinner thread, tool-call/result lines, diffs, confirm and read_message. All output goes through _emit under the same lock the spinner draws under. The spinner redraws by erasing the current line, so output is always written as whole lines (see assistant_chunk). Glyphs fall back to ASCII on non-UTF-8 streams.
• console.py: Session (one turn, delivered-file download, slash commands, ! local shell, the loop) and run() (argv). Collaborators are injected so tests can drive it.
• gui/: the window. bridge.Bridge implements the same surface as ui.Terminal (tool_call, tool_result, confirm, assistant_chunk, …) with each call emitting a Qt signal, so the window reuses console.Session and Tools unchanged. window.TurnRunner runs Session.send on a QThread. Bridge.confirm blocks the worker on an Event until a ToolCard's Allow/Deny calls answer(), and close() releases it as "no". window.MainWindow reacts only to Bridge signals. widgets.py holds the transcript pieces (ToolCard, AssistantMessage, Composer, …). theme.py holds the colours and the one stylesheet (widgets set object names and dynamic properties for it, then repolish()). icons.py draws every icon with QPainter, so there are no asset files. markdown_html swaps Qt's fixed font for code (Courier New on Windows) with the app's mono font.
• dictation.py: the mic button. It streams 16 kHz int16 to the server's /desk/stt websocket (Bolt-Pet's route: the server relays to Deepgram) and buffers every frame. If the live socket never opened or died, _fallback() sends the whole buffer once from an empty transcript, so a half-live session's words don't come back twice. A healthy socket is never re-sent, even when it heard nothing, because that would pay twice. Stops on click, on silence_seconds after speech, or on max_seconds. No Qt and no numpy (the array module does RMS), so it's identical in the Linux single file. The mic and socket are injected. The window turns the callbacks into DictationSignals, and the composer is read-only while a recording rewrites it. PySide6 6.10 needs QTextCursor.MoveOperation.End, not cursor.End.
• Chats: server_client.list_chats()/create_chat() wrap GET/POST /desk/chats (the server mints chat-… ids; a chat is only listed once used). Switching is config.set_session(id): a plain reassignment of the SESSION_ID every call reads, persisted to session.json, and deliberately not locked. The window refuses to switch mid-turn instead. gui/chat_list_window.py runs list/create as ChatTasks on QThreadPool.globalInstance() and hands results back through ChatSignals, never calling the network from a slot. The header New chat uses the same pool. Session.new_conversation() (terminal /new) is blocking and falls back to a local id if the server can't mint one. chats.py holds the Qt-free row helpers (the preview drops the [Bolt Console: …] and [on screen right now: …] notes).
• file_delivery.py: saves files the server queues via deliver_files. The name is reduced to its basename and never overwrites an existing file. Session.check_deliveries runs after every turn.
• doctor.py: independent checks, each reporting ok/warn/fail plus what to do about it. A check never raises.

Testing conventions

tests/test_gui.py sets QT_QPA_PLATFORM=offscreen itself and drives real turns through MainWindow and its worker thread against the loopback server (pump_until processes events). Offscreen Qt has no font database, so check the look by rendering with the real platform plus WA_DontShowOnScreen and grab(), not offscreen.

Tests cover logic with injected fakes (FakeUI, FakeShell, a Terminal writing to StringIO with a scripted input_fn). tests/test_console.py is the end-to-end file: a real threaded HTTP server on a loopback port driven through the real server_client, Tools and Terminal. Add a case there when a bug crosses module boundaries. Tests that embed a path in JSON must use json.dumps(str(path)), because Windows backslashes are otherwise invalid escapes.

Fabricated tool results

The model sometimes writes tool output as prose instead of emitting a command. The tool marker syntax in console.annotate() is load-bearing: vague wording ("use filectl") measurably caused this against the live server, and spelling out command: ... fixed it. console.fabricated() flags a reply shaped like tool output when Tools.calls didn't move, and the next message carries CORRECTION. A polluted session keeps copying its own history, so the remedy is New chat.

Security notes

Approved shell commands, writes and edits run as the user with no sandbox. auto mode removes the prompt. That is the same "full desktop control" trust model as the server's other desk clients, which is why ask is the default here. Keep DESK_API_KEY private.