Get the current state of the Ikenga desktop app — sidebar mode, focused pane route, and the full pane tree under shell.panes. shell.panes has shape { leaves: [{ id, focused, activeTabIdx, tabs: [{kind,title}] }], tree: }; use leaves[].id with iyke_focus or iyke_close (pane_id) to operate on a specific pane. Call this before iyke_go / iyke_mode / iyke_focus / iyke_close to check what the user is currently looking at.

Navigate the focused pane to a route path inside the Ikenga desktop app (e.g. "/notes/today"). Path must start with "/". This replaces the focused pane's active tab content; use iyke_open with kind=route to add a new tab instead.

Switch the activity-bar sidebar mode. Valid modes: app, files, agents, sessions, settings, storyboard, video-engine, canvas-design, image-generator. The first five are core; the rest are mini-apps.

Open a new tab in the focused pane. kind selects the view type. For "route" pass path; "terminal" optionally cmd (a shell command string); "chat" requires session_id; "artifact" requires path; "mini-app" requires name.

Split the focused pane (or a specific pane via pane_id) into two. "horizontal" splits side-by-side; "vertical" splits top-bottom. Subject to the in-app MAX_LEAVES cap (currently 6).

Focus a specific pane. Provide either pane_id (leaf id from iyke_state response — shell.panes.leaves[].id) or index (1-based DFS leaf index, matching the in-app ⌃1..⌃6 keyboard shortcuts).

Close a pane (or the focused pane if pane_id omitted). Closes the entire pane and all its tabs — to close a single tab from the in-app keyboard, use ⌘⇧W (⌘W closes the whole pane). Refuses to close the last remaining pane.

Take an accessibility-tree snapshot of the focused pane. Returns Playwright-style text plus structured JSON. Each interactive element gets a stable ref like e1, e2; pass that ref to iyke_click / iyke_type / iyke_key. Refs invalidate on the next snapshot or page navigation. Use query for substring filter, all=true to include hidden elements.

Read recent console + error logs (last 500) from the running webview. Includes window error and unhandledrejection captures.

Read recent fetch + XHR network activity (last 100). Each entry has method, url, status, duration_ms, and error if it failed.

Capture a PNG screenshot of either the full window or a specific pane. Returns the saved path, dimensions, and byte count. Default writes to ~/.local/share/ikenga/screenshots/.

Wait until a predicate is satisfied or timeout. Use this after iyke_click / iyke_go to wait for the new state to render, instead of fixed sleeps. Returns { satisfied, elapsed_ms, message? }.

Click an element. Specify exactly one of ref (from iyke_dom), selector (CSS), or text (innerText match). Refs are most reliable.

Type text into an input/textarea/contenteditable element. Specify exactly one of ref or selector. By default appends; pass replace=true to overwrite the existing value.

Dispatch a keyboard combo. Use names like "Enter", "Escape", "Tab", "ArrowDown", and modifiers Ctrl/Alt/Shift/Meta separated by + or , (e.g. "Ctrl+S", "Meta+K"). Optional ref/selector targets a specific element; otherwise the active element receives.

Dump the TanStack Query cache: queryKey, status, fetchStatus, isStale, dataUpdatedAt, errorUpdatedAt, error, and a 200-char data preview for each entry. Useful for diagnosing stale data or failed fetches.

Open Chrome DevTools for the main webview (debug builds only). Returns 503 in production builds.

Read the latest published state object for an iframe pane (storyboard cursor, comp current frame, etc.). Iframes call publishState(key, value) from their iyke-bridge to expose runtime state for inspection.

Send a fire-and-forget postMessage to an iframe pane. The iframe bridge listens for known kinds (e.g. "story-select") and acts on the payload. Use to drive mini-app actions from outside the running app.

Create a new project in the Ikenga shell. Projects scope chats, installed pkgs, pane layouts, todos, scratchpads and cron jobs — switching project rebinds those surfaces. Slug id must match ^[a-z0-9][a-z0-9_-]{0,63}$ and be unique; default is reserved. display_name is freely Unicode, capped at 120 chars. root_path is optional but recommended — it becomes the cwd for new chats spawned inside the project. color is a hex string used for the activity-bar dot. Use when the user asks to set up a new working context (a codebase, a label, an experiment).

Patch fields on an existing project. Only the fields you pass in patch are touched — omit a field to leave it as is. Pass null to clear a nullable field (root_path, icon, color, description). position controls the project ordering in the activity-bar switcher (lower = earlier). Cannot change id; create a new project and migrate instead.

List projects in switcher order (position ASC, then created_at). Each entry has id, display_name, root_path, icon, color, description, position, is_default, created_at, archived_at. Archived projects are hidden by default — pass include_archived=true to surface them (e.g. when an agent is restoring an old project).

Archive a project (soft-delete — sets archived_at, no data removed). The project disappears from the default switcher list but its sessions/pkgs/todos remain on disk and can be restored by a later iyke_project_update if needed. Refuses to archive the built-in "Default" project. If the archived project was active, the shell falls back to Default automatically.

Switch the shell's active project. Subsequent new chats, scratchpads, todos and pkg installs default to this project; existing project-scoped TanStack queries (sessions, pkgs, todos, scratchpads, cron) refetch automatically. Does NOT navigate panes — pane contents stay put until a phase-2/6-aware surface reads the new active id. Fails if the id is unknown or archived.

Return the currently active project (id, display_name, root_path, icon, color, description, position, is_default, created_at). Call this before iyke_project_set_active or any project-scoped mutation so an agent knows which project the user is in.

List Claude chat sessions. Filter by project (defaults to active); pass include_all=true to list across all projects. Returns at most 50 threads by default (max 200). Each entry has id, title, cwd, project_id, claude_session_id, created_at, updated_at.

Move a chat thread between projects. Metadata-only — does not restart the claude subprocess. The cwd captured at spawn time stays whatever it was. Fails if the target project is unknown or archived.

Mint a new Claude chat thread attached to a project. The shell resolves the project root as the session cwd, builds the layered Claude-config overlay dir (skills + agents + commands + merged .mcp.json) for the spawn, and routes the request through the ACP session/new handler. Returns the new thread_id; the actual subprocess spawns lazily on the first prompt — fire acp_prompt or open /sessions/$threadId in the UI to send the initial message. initial_prompt is currently informational only (the bridge does not forward it yet).

List MCP servers visible from a project. Returns each (server name × source) pair so conflicts across tiers are surfaced separately. Each entry reports: source tier (personal | workspace_pkg | project | project_pkg), provider (pkg id or "personal"), lifecycle (long-lived | per-call | on-demand), live state (running / parked / crashed / blocked / not-started / on-demand), and the source file path. Defaults to the active project; pass project_id to query a specific one.

Restart a supervised MCP server by pkg id. Restarts every long-lived MCP entry the pkg declares (the supervisor keys per pkg, not per server name). Useful when a child has wedged. Fails with 404 if the pkg is not supervised — per-call MCPs spawn fresh on every tool invocation and have nothing persistent to restart.

Get the trust state for a single installed pkg. Returns one of: auto_trusted (built-in com.ikenga.* shipped with the shell), auto_granted (no sensitive permissions declared), granted (user approved a specific manifest version), or needs_approval (sensitive perms declared but no current grant; either never approved, perms changed since last grant, or explicitly revoked). When state is needs_approval, MCP tools/call against this pkg returns the structured trust_required error until the user grants approval via Settings → Pkgs.

List trust state for every installed pkg. Returns one entry per pkg with state (auto_trusted / auto_granted / granted / needs_approval), declared sensitive permissions summary, and last grant timestamp when applicable. Use when surveying which third-party pkgs need user approval before their MCP tools can be invoked.

List kernel-level permission-violation audit rows newest-first. Today only shell.execute denials write here (a pkg attempted to spawn a binary outside its manifest's declared allowlist). Returns one entry per attempt with attempted (the resolved command), declared (the manifest allowlist at attempt time, comma-joined), scope_kind ('shell.execute'), pkg_id, and occurred_at (unix millis). Pass pkg_id to filter to one pkg; omit for a cross-pkg view. limit defaults to 100 and is hard-capped at 1000.

Read a secret from the vault. The scope arg partitions the read: omit it (or pass an empty string) to read from the active project; pass "workspace" to read a cross-project shared secret; pass "project:" or "pkg:" to target a specific partition. Returns the value as a string, or null when the key does not exist in the chosen scope. Falls back transparently to the legacy unscoped key when a scoped value is missing (with a deprecation log on the host).

Write a secret to the vault under the given scope (same scope semantics as iyke_secret_get). Triggers a re-dump of the runtime env-vault file so sidecars and per-call MCP children pick up the new value on next spawn. Use this sparingly — secrets are sensitive and the values land in the user's encrypted Stronghold snapshot.

Delete a secret from the given scope. Same scope semantics as iyke_secret_get. Returns ok even if the key did not exist. Does not touch the legacy unscoped key — to clean up legacy entries, delete the value at the unscoped key directly.

List secret KEY NAMES (not values) in a scope. Same scope semantics as iyke_secret_get. Returns sorted bare key names — the scope prefix is stripped. Use to inventory what secrets are stored in a project without revealing values.

Get the saved layout (pane tree, files-explorer state, panel sizes) for a project. Returns the raw layout_state row contents — each field is the JSON the shell wrote, or null when nothing has been saved for that key. Defaults to the active project; pass project_id to query a specific one. Useful for the conductor pattern (an agent inspecting "what does this project look like to the user").

Reset a project's saved layout — deletes the pane tree, files-explorer state, and panel sizes rows. Next time the user (or anyone) switches to this project, the layout-swap orchestrator finds no saved state and leaves the current view in place. Use this to recover from a wedged layout or as part of a clean-slate workflow.

List Claude-config assets (skills, agents, commands, hooks, mcps) discovered for a project, grouped by provider tier. Returns a tree where each asset name maps to one or more AssetSource entries; multiple entries on the same name indicate a conflict between tiers. Defaults to the active project; pass project_id to query a specific one. Use this to see what an agent will actually load in a project context.

Pin a preferred provider for a Claude-config asset name in a scope. When discovery finds the same asset name in multiple tiers (e.g. a code-reviewer agent in both ~/.claude/ and a project pkg), the lowest tier wins by default; a pin overrides that. Scope is "workspace" (cross-project) or "project:" (this project only). preferred_tier is one of personal | workspace_pkg | project | project_pkg. preferred_source is the pkg id (or "personal" for ~/.claude/) — omit to match any source in the tier.

Remove a pinned resolution. Falls back to the default lowest-tier-wins rule.

List Claude-config asset pins for a scope. Scope is "workspace" (cross-project) or "project:" (this project only). Returns one entry per pin with preferred_tier + preferred_source.

Register this agent so locks and timers can attribute work to it. Returns an opaque id. Pass the id as holder to iyke_lock_acquire. Repeated calls with the same {id} bump last_seen_at; omit id to mint a new one.

Create or replace a project-scoped Markdown scratchpad. Use for plans, handoffs, working context that should outlive a chat. scope defaults to the active project (project:); pass "workspace" or "pkg:" to opt out. name is a slug unique within scope. Body cap 1 MB.

Append to a scratchpad without overwriting. Creates it if missing. with_separator=true (default) inserts a horizontal rule + timestamp between the prior body and the new content.

Read a scratchpad by scope+name. 404 if missing. Returns id, body, updated_at.

List scratchpads in a scope (defaults to active project). Each entry has id, name, updated_at, and a 200-char preview.

Delete a scratchpad by scope+name. Idempotent.

Store a small JSON value at scope+key. Cap 64 KB per value; cap 1 MB total per scope. For larger durable text, use scratchpads. Scope defaults to active project.

Read a JSON value at scope+key. Returns { key, value: null } if absent (200, not 404).

Delete a KV entry. Idempotent.

List KV entries in a scope. prefix filter narrows by key prefix.

Acquire a project-scoped lease lock on a named resource. Use for short-lived coordination around shared files, plans, migrations. holder is the agent id from iyke_agent_register. ttl_ms defaults to 60000 (clamped to [1000, 600000]). If wait_ms is set, blocks up to that long for an existing lock to expire.

Check whether a resource is currently locked (active leases only). Returns held=false if the lease has expired.

Release a lock you hold. No-op if held by someone else or already expired.

Extend a lock you hold by ttl_ms. Useful for long-running work that needs more time than the original lease.

Create a project-scoped todo. Tags are free-form strings; assignee is a free-form name (agent or user). Set blocker_id to mark this todo as blocked by another.

Partial update of a todo. Only supplied fields are changed. Pass status="done" or use iyke_todo_complete for the common case.

List todos in a scope (defaults to active project). Filter by status, tag, assignee.

Mark a todo as done and stamp completed_at. Equivalent to iyke_todo_update with status=done.

Schedule a one-shot timer in the active project (or specified scope). Pass either fire_at (absolute epoch-ms) or delay_ms (relative from now), not both. When the timer fires the shell emits an OS notification; if agent_id is set, an entry also lands in that agent's inbox (delivered on its next tool call, 24h TTL).

Cancel a pending timer by id. No-op if already fired or cancelled. Returns { cancelled: bool }.

List timers in a scope (defaults to active project). Optional status filter: pending | fired | cancelled. Returns timers sorted by fire_at ascending.

List installed pkgs visible from the active project. Workspace-scoped pkgs are always included; project-scoped pkgs are included only when their project is active unless include_other_projects=true. Each entry: id, version, install_path, enabled, source, scope ("workspace" | "project:"), active_now.

Change the scope of an installed pkg. scope="workspace" (always loaded) or "project:" (loaded only when that project is active). Triggers a kernel reconcile so sidecars start/stop accordingly.

Uninstall a pkg. Stops its sidecars, removes its registry entries, deletes its files. Project-scoped state in iyke_kv / iyke_scratchpads / iyke_todos survives. Builtins (com.ikenga.*) cannot be uninstalled.