/app-controls

name: app-controls
description: Inspect and drive Poracode itself — the Terminal panel, other threads, projects, workspaces, git, pull requests, and schedules — through the poracode MCP. Use when the request is about the user's workspace state or app-side actions rather than editing files in the repository.

Poracode

Use Poracode's `poracode` MCP when the task is about the running app rather than the code in front of you: what a Terminal pane is printing, what another thread is doing, the project's git or pull-request state, or the user's schedules and settings. Prefer ordinary file and shell work for anything that is really a code change.

Schedule results are persistent: use `list_schedule_run_inbox` with `filter`, optional `search`, and a `cursor` from the last row (`startedAt|id`) to review older results. Use `mark_schedule_run_read`, `mark_schedule_run_unread`, `archive_schedule_run`, and `restore_schedule_run` to triage them. `cancel_schedule_run` also cancels pending retry delays; a thread cannot cancel its own active run. `create_schedule` and `update_schedule` accept `automation` for heartbeat mode, bounded retries, missed-run handling, run limits, and an optional completion condition. Heartbeats require a same-project, same-agent GUI conversation.

`create_thread` inherits the New thread page's plugin/MCP defaults. Override `browserMcp`, `crossagentMcp`, `chromeMcp`, and `computerUse` with booleans; `mcpServers` maps configured server ids to booleans, and `plugins` maps installed manifest names to booleans. These choices are per thread and survive resume; global hard disables and provider/platform restrictions still apply. Discover custom server ids with `list_mcp_servers`/`get_project` and installed plugin names with `get_settings` (`section: "installedPlugins"`). Attach files or images to the first message with `attachments: [{path, mimeType?}]`; paths must be absolute files on this host, and image MIME types are inferred from their extension.

Workflow

Use `commit` for a commit, `create-pr` for publishing a PR with verification and before/after UI screenshots, and `finalize` when the user requests the complete review, manual QA, fix, publish, and merge workflow. These skills use Poracode's Git/GitHub tools so their observed state reaches the UI. Resolve the current thread once for `projectId` and the exact `worktreePath`; omitting the path operates on the main checkout. After CLI-only operations such as `gh pr edit --attach`, call `gh_get_pr` and `git_status` for that same target. A `syncWarning` means the operation completed but the UI refresh needs retrying; do not repeat the mutation.

1. Start from the narrowest tool that answers the question. `list_terminals` and `read_terminal` for the Terminal panel, `list_threads` / `read_thread` for other work, `git_status` / `git_diff` for the working tree, `gh_list_prs` for review state. 2. For a Terminal request, call `list_terminals` directly — it resolves the caller's project and worktree on its own. Never ask the user for an id, and never pass a `threadId` to `read_terminal`. 3. Read before you write. Check `git_status` before staging, the PR before commenting, the schedule before updating it. 4. State what you are about to do when the action changes the user's workspace, then do it in one step rather than a chain of partial edits. 5. Report what the tool actually returned. When output is long, quote the part that carries the answer and say where it came from.

Boundaries

For app-native charts, comparison tables, calculators, checklists, tabs, text and relationship diagrams, use Native visuals v2 below. Existing v1 documents remain supported. An assistant-message fence opened with `poracode-html-v1` followed by a plain title preserves HTML as a source preview in desktop and web/PWA conversations (at most 256 KiB per block). Interactive HTML rendering and MCP Apps sessions are unavailable: author markup and scripts are not executed. Do not promise interactive HTML, MCP Apps sessions or host actions. Ordinary `html` code fences remain source examples.

Native visuals v1

In a completed assistant reply, open a fenced code block with `poracode-visual-v1` followed by a plain title. Its body is strict JSON, not HTML or JavaScript. Desktop and web/PWA render native app-themed controls. Native iOS/Android clients retain fenced source. No tools, host actions, URLs, author code, custom styles, markup or MCP Apps sessions are supported.

Root: `{description?, inputs?, blocks}`. Input: `{id,label,min,max,step,value}`; IDs are unique ASCII letters/digits/underscore/hyphen, starting with a letter. Defaults are finite, within min/max and on the positive step grid. Blocks:

• `{"type":"chart","kind":"bar"|"line","title"?:string,"labels":string[],"series":[{"label":string,"values":Value[]}],"format"?:Format}`. Each series matches the label count.
• `{"type":"table","title"?:string,"columns":[{"label":string,"format"?:Format}],"rows":(string|Value)[][]}`. Every row matches the column count. Strings are plain text.
• `{"type":"outputs","title"?:string,"items":[{"label":string,"value":Value,"format"?:Format}]}`.

`Value` is a number, `{"input":"id"}`, or `{"op":"add"|"subtract"|"multiply"|"divide"|"min"|"max","args":[Value,Value]}`. No string formulas, output references, property access or other operations. `Format` is `{"style":"decimal"|"percent"}` or `{"style":"currency","currency":"USD"}` (three uppercase currency letters). Percent values are ratios: 0.25 displays as 25%. Invalid arithmetic displays Unavailable; it is never silently replaced by zero.

Limits: six native fences per message; 64 KiB UTF-8 per document; six blocks, eight inputs, four series ×100 labels per chart, 100 rows ×eight columns per table, 32 items per outputs block, 1,024 total value slots. Title ≤200, labels ≤120, description/text cells ≤512 characters. Literal/input magnitude ≤1e12, result magnitude ≤1e15, at most 1e6 steps per input. Arithmetic