claude-panel
Skill9 starsChanged 5 days agoMITView on GitHub
Patterns of the Claude Code panel: Agent SDK conversations owned per view (src/main/claude, ipc/claude.ts), permission/question/elicitation cards, sessions (favorites, titles, rewind), prompt attachments and the / menu, the /mcp manager, session status and OS notifications, and the fake SDK for E2E. Use when creating or reviewing anything in src/main/claude, ipc/claude.ts, components/claude or the renderer `claude*.ts` modules.
- Reads credentials
In this repository17 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- app-testingSkill
- commands-settingsSkill
- containersSkill
- debuggerSkill
- files-git-searchSkill
- i18nSkill
- lspSkill
- main-ipcSkill
- main-processesSkill
- packaging-releaseSkill
- renderer-componentsSkill
- renderer-editorSkill
- renderer-storeSkill
- renderer-stylesSkill
- renderer-terminalSkill
- workspacesSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 42
Always pass permissionMode explicitly (omitted = auto).
- Very specific: line 115
All app notices are toasts (components/Toasts.tsx, notify() → showToast.
- Very specific: line 179
Add/remove are persistent through the CLI (claude/cliRunner.ts: claude mcp add-json|remove -s <scope> --, bundled native binary or …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Claude panel (src/main/claude, components/claude)
Main runs the Agent SDK; the renderer (the claude*.ts modules in src/renderer/src, components/claude/) only renders events and answers
requests. Everything from the CLI, the SDK, MCP servers and Claude itself is untrusted.
Conversations and the CLI
- Main runs
@anthropic-ai/claude-agent-sdk(pinned exact; ESM-only, kept external and loaded with a lazy nativeimport()inclaude/sdk.ts; its CLI is a native binary in a per-platform optional package, unpacked viaasarUnpackand spawned byclaude/spawn.tsthroughspawnGroup(process group, registry swept atwill-quit; spawn.ts only keeps the stderr tail and the SDK abort). - Expected conversation failures (closed,
/usagetimeout) areConversationErrorwith acode(claude/conversationError.ts; alsoinvalidReport); never classify an error by its translated text. - Each conversation (
claude/conversation/conversation.ts) is owned by itswebContentsand dies on folder change, reload, close and quit; termination signals callapp.quit()(SIGKILL can't be handled). ipc/claude.tsis channel wiring only. The domain lives beside the conversation:claude/registry.ts(conversations per view oncreateViewRegistry, editor contexts, attachment allowlists, session eventsonClaudeSessionEvent,sessionStatesOf/markAllRead/updateBadge,killAllClaude,restartAllOf,registerClaudeLifecycle),claude/conversationDeps.ts(createConversationDeps: the view side ofConversationDeps; the LSP diagnostics are injected by the handler, the domain never importsipc/lsp),claude/authCli.ts(claude auth …runs, login terminal source),claude/sessions.ts(history, meta, fork, export),claude/attachmentPicker.ts,claude/stores.ts(sessionMeta(),favoriteCommands()) andnotifications/sound.ts(requestNotificationSound). Nothing outsideindex.tsimportsipc/claude; other main code imports the registry.- A conversation leaves its view in ONE way:
removeConversation(wc, conversation)(registrydelete+retire: system notification closed, badge,removedevent emitted once +close()). A view reset goes through the registry'sdispose, which retires the same way, so aclaude:startthat fails after the reset must not emit again (delete(wc, id, expected)returns false). Never delete from the registry by hand. claude/conversation/splits the conversation by responsibility;conversation.tsis the facade that wires them:run.ts(RunManager: launch, stop, sleep,ensureRun,trackStopping; the CLI process of the conversation, never two at once),messageRouter.ts(SDK message to orderedRouteOp[]: events and state changes in one list because their order is observable; no SDK, no state of the conversation, tested inmessageRouter.test.ts),idlePolicy.ts(when the CLI may sleep; timers only, likelsp/idlePolicy.ts),controls.ts(permission mode, bypass, model, effort and theoverridesthe CLIinitmust not undo),checkpoints.ts(rewind, fork),interrupts.ts,send.ts(sendPrompt),commandCatalog.ts(the/menu list),history.ts(resume),mcpConnect.ts(wait for MCP servers after a launch),data.ts(session data shared by the facade and the checkpoints),deps.ts(ConversationDeps). The/mcpcalls go through the read-onlyconversation.mcp(McpController). Renderer args are parsed inipc/claude.ts(parseTaskId,parseModelinvalidate.ts;parseServerName,parseMcpEnabled,parseMcpScope,parseCallbackUrl,validateMcpServerInputinmcp.ts): conversation and controller methods take typed args.- Always pass
permissionModeexplicitly (omitted =auto);settingSources= user+project+local (repo.claude/settings, hooks and MCP apply, like runningclaudein the folder). claude.initialPermissionMode,claude.executableandclaude.envare user-only.- The Claude process gets the login-shell PATH (
env/loginShell.ts, cached per shell only on success, 5 s timeout). - Conversation,
claude mcp …andclaude auth …share ONE context:claude/cliContext.tsresolveCliContext(settings, cwd, loginPath?)(login PATH +claude.executable+claude.env,WALPH_FAKE_CLAUDE*stripped); never rebuild the env or resolve the executable inline. A.jsexecutable is refused withassertRunnableBinary(env/executable.ts). claude/pushStream.tsPushStreamis the only async queue:end()closes,fail(err)drains the queued items and then rejects the consumer (the fake SDK's outbox uses it). Deadlines on SDK calls useutil/deadline.ts(rejectAfterfor MCP calls,withDeadline+TIMEOUTfor status/usage/context).- Edits in the default permission mode (ask before editing) go through
canUseTool→kind:'edit'(claude/proposeEdit.tscomputes the proposal; outside the folder/unreadable → generictoolcard) → renderer diff tab (DiffTab.proposal) → the CLI writes and the clean tab reloads through the watcher. - Accept always rechecks the disk against
original(and a dirty tab is saved or reverted first); never write into a dirty buffer. - Paths from Claude go through
resolveInsideRoot(fs/paths.ts: lexical +realpath, returned in the window folder's spelling). - The CLI emits one
assistantmessage per content block andinittwice; main emits exactly oneresultper turn (the renderer's "Na fila" queue and partial-stream flush key on it). - Deltas are batched per animation frame in
claudeEvents.ts. - The in-process MCP server
walph(claude/ideServer.ts) is inallowedTools: the SDK'sCLAUDE_SDK_CAN_USE_TOOL_SHADOWEDwarning is expected (openDiffhas its own approval).
Renderer modules (src/renderer/src/claude*.ts)
Flat modules beside store.ts, listed in dependency order: each imports only modules above it in this table, so there are no cycles (only cycles are lint-enforced, not the order). Components import from
the owning module, there is no barrel.
| Module | Owns |
claudeState.ts | bridge (liveClaudeApi), failed, patchClaude, findConversation, updateConversation, activeConversation, liveConversationId (null for dormant tabs: never sent to IPC), optimisticPatch |
claudePromptBridge.ts | PromptHandle registry: lets actions insert text into / focus the mounted prompt box of the active conversation without the store |
claudeDrafts.ts | per-conversation prompt drafts and the sent-message history (↑), kept out of the action modules so the workspace session can save them |
claudeQueue.ts | startQueue (every start goes through it; claude.starting mirrors it) and earlyEvents (events that arrive before start answers) |
claudeVisibility.ts | window focus (watchWindowFocus), isShown/isVisible/syncRead (markRead), toast keys, revealConversation/openClaudeSession, done/error/model-fallback toasts |
claudePermissions.ts | respondPermission, acceptEdit/rejectEdit, diskMatches, proposal diff tabs (openProposalDiff, closeProposalTabs), card focus, reviewPermission and the pending-request toast (showAttentionToast) |
claudeEvents.ts | agentTimes, delta batching, handleEvent/applyEvent |
claudeLifecycle.ts | show/hide/toggle/focus the panel, runStart (job of startQueue), enqueueStart, autoStart, wake of dormant tabs, new/close/resume/activate/step, forgetConversation |
claudeEditorContext.ts | editor context sent to main (readEditorContext, debounced scheduleEditorContext), insertClaudeReference, openPathFromClaude, reviewChangedFile |
claudeSessionMeta.ts | favorite, rename, duplicate, export, loadSessions, hydrateDormantMeta |
claudeMcpActions.ts | /mcp calls (mcpCall) and the /usage report: both wake a dormant tab first (openOverlayAfterWake) |
claudeLogin.ts | openClaudeLogin (terminal + authStatus poll), logoutClaude, stopLoginPoll |
claudePromptActions.ts | sendPrompt (+ local commands /clear /mcp /usage /login /logout), retry/compact/interrupt/stopBackgroundTask, attachments, / menu, favorite commands, askClaude, handleStartRequested ("Comece com o Claude") |
claudeRewind.ts | rewindConversation |
claudeConversationSettings.ts | mode, model, effort (optimistic, undone on failure) |
claudeReactions.ts | startClaudeReactions (top of the chain, imported only by ipcReactions.ts): main events, root change reset (resetClaude), visibility, wake and auto start, editor context |
Pure conversation logic lives in lib/, store-free, one module per concern (each importing only the ones before it):
| Module | Owns |
lib/claudeConversation.ts | ClaudeConversation and its types, createConversation/createDormantConversation, userText, queued and permission helpers (addQueued, bindQueuedUuid, removeQueued, removePermission), setUserTitle, loadStep, background task labels |
lib/claudeReducer.ts | reduceEvent: the single reducer of main's ClaudeEvents over a conversation |
lib/claudeTimeline.ts | buildTimeline and TimelineItem (messages flattened into screen items, resultCache keeps tool results referentially stable) |
lib/claudeSessionTabs.ts | sessionClaudeTabs and sameSessionFields: the conversation tabs saved in the workspace session |
Timeline pieces live in components/claude/timeline/ (ItemView with the sameItemProps memo comparison, UserMessage
UserText,PinnedPrompt,TurnSummary,BackgroundTasks,RetryLine,ThinkIndicators,MessageTime);Timeline.tsxcomposes them. The prompt box isPromptBox.tsx(JSX and wiring) overusePromptText(draft, caret, history ref, theregisterPromptbridge),usePromptMenus(@//menus and their loads) andpromptKeyActioninlib/claudePrompt.ts(pure: which action a key triggers; menu arrows stay inuseActiveDescendant).
A lower module never calls a higher one: what several need goes down (startQueue, earlyEvents), what needs
everything goes up (claudeReactions.ts).
Session status and notifications
- Status/
unreadare derived in main (claude/sessionStatus.ts, pure reducer, priority attention > error > running > done > idle) and emitted assessionStatus; main countsunreadalways and the renderer callsclaude.markReadwhenever the session is visible (active tab + panel shown + window focused). - A failed conversation stays in main's map (closed) until the renderer's
close. - OS
Notifications (one per session, references kept against GC) +app.setBadgeCountlive inclaude/registry.ts/claude/conversationDeps.ts/claude/notify.ts. - All app notices are toasts (
components/Toasts.tsx,notify()→showToast;keyreplaces/removes). - E2E of the panel use the fake SDK (
WALPH_FAKE_CLAUDE=<script.json>,claude/fake/(index.ts; script format inscript.ts, CLI incli.ts, query inquery.ts) reached only throughclaude/runtime.ts/sdk.ts, ignored when packaged, its singlefake-*chunk excluded from the package, everyWALPH_FAKE_*stripped from the real CLI env); Playwright emulates page focus, so specs blur explicitly; spyNotification.prototype.showfor OS notifications.
Questions
AskUserQuestionis handled first incanUseTool(independent of the permission mode) askind:'question'.claude/question.tsnormalizes the untrusted input (malformed →denywithout interrupt and a message, nothing shown) and maps the renderer'sanswer({ [ClaudeQuestion.id]: string[] }) to the CLI formatupdatedInput.answers = { [original question text]: values.join(', ') };skip=denywithout interrupt.claude.respondreturns a boolean ack:false= main refused (wrong behavior for the kind, invalid answer/malformed) and the request STAYS pending, so the renderer keeps/restores the card;true= accepted or the request no longer exists; never leave a pending request without a card.- Cards carry
data-request-id; when the focused card leaves the DOM the prompt gets focus back (claudeFocuswould stay stuck). - Fake SDK step
questionfor E2E.
Sessions
- Favorite + user title per
sessionIdlive in main (claude/sessionMeta.ts,<userData>/claude/<sha256>.json); the user title wins everywhere and is mirrored to the CLI transcript withrenameSession(best effort,syncCliTitleinclaude/sessions.ts). ClaudeStarted.userTitleseparates it from the automatic title (a latertitleevent only replaces automatic ones); the renderer must take thesessionIdfrom EVERYinit(rewind to the start creates a new one, meta is copied).- "Permitir sempre" is session-only (suggestions retargeted to
session); "Sempre neste workspace" is written by main to<root>/.claude/settings.local.json(localPermissions.ts, never a path from the renderer, invalid file never overwritten) +.git/info/excludewhen new (gitExclude.ts). - Non-fatal warnings use the
noticeevent (toast), nevererror. - Turn
+N −Ncomes from the tool blocks (lib/claudeTurnSummary.ts, LCS with a per-turn budget). - Fake SDK: persistent session store (
WALPH_FAKE_CLAUDE_STORE), stepstoolCall/toolResult/subagentMessage,permission.suggestions. - Native save dialogs are stubbed in E2E via
electronApp.evaluate.
Prompt, attachments and commands
- File chips are
ClaudeAttachment { path }; a path outside the folder is accepted by main only if it is in the view'sPathAllowlist(fs/pathAllowlist.ts, one per view throughwindow/viewPathAllowlist.ts, registered inclaude/registry.ts: filled byclaude:pickAttachmentsor by the native confirmation inclaude:authorizeAttachments; 10 min renewed on use, pinned by canonical path + dev/ino, cleared with the view); the renderer never reads outside paths itself (files.pathForFileonly returns a path). /menu =claude:commands(init commands merged withclaude/commandFiles.ts, re-read per call with mtime cache, untrusted plain text, no symlinks out of.claude/commands).bypassPermissionsneeds the user-onlyclaude.allowBypassPermissions: only then does main launch withallowDangerouslySkipPermissions; turning it off moves open conversations back todefaultonly after the CLI confirms (failure closes the conversation).setEffort(null)= model default.- The fake SDK records calls in
globalThis.__walphFakeClaudeCalls/WALPH_FAKE_CLAUDE_LOG(user content blocks,setPermissionMode,applyFlagSettings). - The execution modes keep the design system's English names (Manual · Edit automatically · Plan · Auto · Bypass permissions, as in Claude Code): the same labels in every language on purpose; descriptions are translated.
- Prompt-bar menus use
ChipMenu+common/useMenuPopup.ts(shared withDropdownMenu). - Favorite commands (strip above the prompt,
FavoriteCommands.tsx) live in the app per folder (claude/favoriteCommands.ts,<userData>/claude/favorite-commands/<sha256>.json, never in the repo);shared/favoriteCommands.tsvalidates names/icons and the IPC takes the renderer'srootand refuses if the view changed folder. - Tool rows (
ToolRow.tsx) come from the purelib/claudeToolRow.ts(icon + past-tense verb, capped detail lines).
MCP manager (/mcp)
- A bare
/mcpis intercepted insendPrompt(like/clear) and openscomponents/claude/mcp/McpModal.tsx(overlay{ kind: 'mcp', conversationId }, one modal at a time; also ⋯ menu andclaude.manageMcp). - Status/toggle/reconnect/OAuth go through the SDK
Query(mcpAuthenticate/mcpClearAuth/mcpSubmitOAuthCallbackUrlare untyped: cast + feature-detect; the CLI never opens the browser, main does,http(s)only). - Add/remove are persistent through the CLI (
claude/cliRunner.ts:claude mcp add-json|remove -s <scope> --, bundled native binary orclaude.executable), run withrunCollectas a process group (20 s timeout; the conversation'sAbortSignalandwill-quitkill the tree).claude auth status|logout(claude:authStatus/claude:logout) use the same runner with a per-viewAbortController(authRunsregistry inclaude/authCli.ts, aborted on view reset), thenreloadPlugins; the live CLI may still list a removed server (main filters it per conversation) or a new one without scope (main remembers it). claude/mcp.tsnormalizes the untrusted status: env/header VALUES never leave main, secrets in args/URLs/errors masked; onlylocal/project/userareeditable, the internalwalph(source: 'sdk') is read-only.- MCP calls are serialized per conversation, count as activity (no sleep mid-OAuth) and are aborted on
close. - Fake SDK: root
mcpServers.
SDK events (elicitation, limits, progress)
- MCP elicitation goes through
onElicitation→ask()askind:'elicitation'(attention, like a question; answered only withbehavior:'elicitation'). claude/elicitation.tsnormalizes the untrusted schema (flat subset, ≤ 20 fields,__proto__/constructor/prototyperefused; anything else is declined with anotice, never half-shown); url mode is opened by MAIN (http(s) only, no credentials;openExternalfailure →cancel).- Content is validated by
shared/elicitation.tson both sides (error codes; main is authoritative,validate.tsparseResponsefirst). - The card shows errors only after the first submit (on blur the layout shift ate the next click).
rate_limit_eventutilizationis a fraction andresetsAtepoch seconds.prompt_suggestionis emitted only while idle;tool_progressis throttled to 1/s per tool; none of these start a turn or block sleep.model_refusal_fallbackremovesretracteduuids from the transcript (both scopes) and, forsession, swaps the model (+overrides.model) and re-emitsinit.commands_changedonly updates the init list (the/menu re-reads per call).claude.fallbackModel(user-only) drops entries equal to the model; the SDK throws whenfallbackModel === model.- Renderer state for these (
rateLimit,retry,suggestion,taskProgress,toolElapsed) is ephemeral, never in the session. - E2E:
e2e/claudeSdkEvents.spec.tswith the fake SDK steps.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

