IPC Channels Reference

IPC Channels Reference

Every IPC channel ClusterSpace exposes, grouped by domain. Channel names are constants in src/shared/types.ts:IPC_CHANNELS; preload bridges in src/preload/index.ts wrap each ipcRenderer.invoke / ipcRenderer.on call with a typed window.electronAPI.* method.

Use the preload bridge from the renderer — don't import ipcRenderer directly (it's sandboxed).

---

PTY

Constant	Channel	Direction
PTY_SPAWN	pty:spawn	renderer → main, returns ptyId
PTY_WRITE	pty:write	renderer → main
PTY_RESIZE	pty:resize	renderer → main
PTY_KILL	pty:kill	renderer → main
PTY_KILL_ALL	pty:kill-all	renderer → main (app exit)
PTY_DATA	pty:data	main → renderer (push)
PTY_EXIT	pty:exit	main → renderer (push)
PTY_BACKGROUND_WORKSPACE	pty:background-workspace	renderer → main (workspace switch)
PTY_FOREGROUND_WORKSPACE	pty:foreground-workspace	renderer → main
PTY_KILL_WORKSPACE	pty:kill-workspace	renderer → main (workspace delete)
PTY_GET_SCROLLBACK	pty:get-scrollback	renderer → main, returns string[]
PTY_HAS_ACTIVE	pty:has-active	renderer → main, returns boolean
PTY_GET_FOR_PANE	pty:get-for-pane	renderer → main, returns ptyId?

Preload bridge: spawnPty, writePty, resizePty, killPty, onPtyData, onPtyExit, etc.

---

Workspace

Constant	Channel
WORKSPACE_GET_ALL	workspace:get-all
WORKSPACE_GET	workspace:get
WORKSPACE_CREATE	workspace:create
WORKSPACE_UPDATE	workspace:update
WORKSPACE_DELETE	workspace:delete

Preload: getWorkspaces, getWorkspace, createWorkspace, updateWorkspace, deleteWorkspace.

---

Settings

Constant	Channel
SETTINGS_GET	settings:get
SETTINGS_UPDATE	settings:update

Preload: getSettings, updateSettings.

---

SSH

Constant	Channel
SSH_SERVERS_GET_ALL	ssh:servers:get-all
SSH_SERVERS_CREATE	ssh:servers:create
SSH_SERVERS_UPDATE	ssh:servers:update
SSH_SERVERS_DELETE	ssh:servers:delete
SSH_SERVERS_TEST	ssh:servers:test
SSH_GET_PASSWORD	ssh:get-password
SSH_GET_COMMAND	ssh:get-command

---

AI (chat + providers)

Constant	Channel
AI_SETTINGS_GET	ai:settings:get
AI_SETTINGS_UPDATE	ai:settings:update
AI_PROVIDERS_GET	ai:providers:get
AI_PROVIDERS_CREATE	ai:providers:create
AI_PROVIDERS_UPDATE	ai:providers:update
AI_PROVIDERS_DELETE	ai:providers:delete
AI_PROVIDER_TEST	ai:provider:test
AI_PROVIDER_DISCOVER	ai:provider:discover
AI_CHAT_SEND	ai:chat:send (one-shot)
AI_CHAT_STREAM	ai:chat:stream (streaming start)
AI_STREAM_CHUNK	ai:stream:chunk (main → renderer, text delta)
AI_STREAM_END	ai:stream:end (main → renderer, final message)
AI_STREAM_ERROR	ai:stream:error (main → renderer)
AI_CANCEL	ai:cancel
AI_SCREENSHOT_PANE	ai:screenshot:pane
AI_SCREENSHOT_WORKSPACE	ai:screenshot:workspace
AI_GET_PANES	ai:get:panes
AI_GET_TERMINAL_OUTPUT	ai:get:terminal-output
AI_WRITE_TERMINAL	ai:write:terminal
AI_FOCUS_PANE	ai:focus:pane
AI_MAXIMIZE_PANE	ai:maximize:pane

---

AI memory

Constant	Channel
AI_MEMORY_GET_CONVERSATIONS	ai:memory:get-conversations
AI_MEMORY_GET_CONVERSATION	ai:memory:get-conversation
AI_MEMORY_SAVE_CONVERSATION	ai:memory:save-conversation
AI_MEMORY_DELETE_CONVERSATION	ai:memory:delete-conversation
AI_MEMORY_CLEAR_ALL	ai:memory:clear-all

---

Agent (per-pane state)

Constant	Channel
AGENT_GET_STATE	agent:get:state
AGENT_GET_ALL_STATES	agent:get:all-states
AGENT_INITIALIZE	agent:initialize
AGENT_SET_ROLE	agent:set:role
AGENT_ASSIGN_TASK	agent:assign:task
AGENT_START_TASK	agent:start:task
AGENT_COMPLETE_TASK	agent:complete:task
AGENT_FAIL_TASK	agent:fail:task

---

Orchestration (multi-pane goals + event stream)

Constant	Channel
ORCHESTRATION_CREATE_GOAL	orchestration:create:goal
ORCHESTRATION_GET_ACTIVE_GOAL	orchestration:get:active-goal
ORCHESTRATION_GET_GOALS	orchestration:get:goals
(event stream)	orchestration:event (main → renderer push)

---

Goal runner (autonomous goals)

Channel (string literal — not in IPC_CHANNELS yet)	Preload bridge
goal:list	listGoals(filter?)
goal:get	getGoal(id)
goal:list-resumable	listResumableGoals()
goal:delete	deleteGoal(id)
goal:prune	pruneGoals()
goal:start	startGoal(input)
goal:abort	abortGoal(id)
goal:status	goalStatus(id)
goal:event	onGoalEvent(cb) (main → renderer push; started / step / verification_failed / critic / ended)

---

Browser (chrome controls + state)

Browser actions reach the WebContents via the registry in browser-pane-registry.ts. Preload bridges include browserNavigate, browserBack/Forward/Reload, browserGetCookies/SetCookie, browserBookmark*, browserHistory*, browserDownload*, browserFindInPage*, etc. Full surface in src/preload/index.ts.

---

Approval (browser)

Channel	Direction
BROWSER_APPROVAL_REQUEST	main → renderer (push request)
BROWSER_APPROVAL_RESPONSE	renderer → main (resolve request)

Used by the Goal-Policy-and-Risk-Levels for tools that exceed risk ceiling, and by the legacy regex gate for sensitive browser actions (password fields, checkout URLs, file uploads).

---

Browser action log

Channel	Direction
BROWSER_ACTION_LOG_APPEND	main → renderer (push, live ticker)
BROWSER_ACTION_LOG_GET	renderer → main (fetch ring buffer)

---

Dialog + app

Constant	Channel	Use
DIALOG_OPEN_DIRECTORY	dialog:open-directory	Native folder picker
APP_GET_PATH	app:get-path	Get userData, home, etc.
APP_GET_MEMORY	app:get-memory	Process memory usage (status bar)

---

Clipboard

Constant	Channel
CLIPBOARD_READ	clipboard:read
CLIPBOARD_WRITE	clipboard:write
CLIPBOARD_READ_IMAGE	clipboard:read-image (for vision attachments)

---

How to add a new channel

1. Add to IPC_CHANNELS in src/shared/types.ts (or use a string literal if it's domain-specific like goal:*)
2. Register a handler in src/main/index.ts (ipcMain.handle(channelName, async (event, ...args) => { ... }))
3. Add a typed bridge to src/preload/index.ts (under ElectronAPI interface + implementation)
4. Use window.electronAPI.myBridge(...) from the renderer
5. Type-check with npx tsc --noEmit

---

See also

• Architecture-Overview — process model + IPC flow diagram
• Tool-Registry — the in-process registry (different from IPC)
• Contributing — type-check and PR workflow