MCP workflows

Every workflow begins with lomi_status → approved pairing → lomi_workspace_list → lomi_connect. Use explicit IDs, fresh observations and the operation/retry rules. The names below link conceptually to the complete tool reference; scopes are explained in permissions.

Run and inspect a terminal command

1. lomi_terminal_create creates a terminal with the approved Bash/Zsh profile. Poll its operation for readiness, terminalSessionId and leaseId.
2. lomi_terminal_run submits one single-line command at a confirmed idle prompt. Keep the returned command operation ID.
3. lomi_operation_get monitors observed completion. lomi_terminal_read with mode: "command" and that operation ID reads its bounded output.
4. Use lomi_terminal_interrupt for a still-running observed command; continue inspecting the original operation for exit.

For an existing terminal, lomi_panel_control can request claim or release. Claiming requires native approval with YOLO off and preserves the shell process. Human input invalidates the lease. A protected origin terminal cannot be claimed as an ordinary agent target.

lomi_terminal_input sends exact text or supported keys with an ordered inputSequence; text does not append Enter. It supports REPL/TUI interaction but does not make an unknown prompt safe for automatic run. Terminal reads offer output, command, retained xterm screen and opt-in base64 raw; output/raw cursors use separate byte spaces. Screen reads report parser lag.

Command completion comes from shell-integration markers, which are untrusted observations. Silence, a prompt redraw or EOF alone is not a successful exit. macOS Bash 3.2 with an existing DEBUG trap can refuse automatic run readiness rather than overwrite the trap.

Search, edit and save a file

1. lomi_files_list lists one project-relative directory. lomi_files_search searches disk text with literal/regex, case/whole-word and include/exclude globs.
2. lomi_files_read reads disk bytes decoded as text. Later pages require the original expectedDiskRevision; offsets use UTF-16 and retain disk line endings.
3. lomi_editor_open opens/reuses a shared buffer. lomi_editor_read reads the loaded buffer, including unsaved changes, and returns its documentId, buffer/disk revisions, dirty/conflict state and encoding.
4. lomi_editor_apply_edits applies ordered nonoverlapping edits against that exact buffer revision in one undo transaction. Offsets use zero-based UTF-16; inserted text uses normalized LF. This does not save disk.
5. lomi_editor_save saves the exact loaded revision atomically. It rechecks disk bytes, preserves supported encoding, line endings and ordinary permissions, and keeps later edits dirty.

Read disk and buffer as separate sources. A file read does not open an editor, and an editor read does not load a missing buffer. Supported text files are UTF-8, UTF-8 BOM and UTF-16 with BOM; ordinary reads/edits/saves are bounded to 4 MiB. Read pages accept 2-8192 UTF-16 units. One edit request contains 1-64 edits and at most 64 KiB inserted UTF-8 text; split surrogate pairs, overlapping edits and stale revisions are rejected.

lomi_editor_open also supports preview/split for Markdown and SVG; raster images require preview. Raster previews use the first frame, orientation/alpha preservation and bounded PNG derivatives (1280 pixels per edge, 3 MiB). AVIF is unsupported. External Markdown images remain links.

lomi_files_mutate creates an empty file/folder, renames/moves entries or requests Trash. Read the required parent/entry revisions first. It never overwrites an existing destination or follows links; cross-volume moves have no copy/delete fallback. Directory revisions cover immediate entries, not a recursive content snapshot. Open buffers retain dirty text and undo across path changes.

Trash uses native recovery staging. A dirty-file Save cancels the removal so the saved version can be read and a new request reviewed. Discard/Cancel follow the existing guard. See recovery.

Inspect and interact with a browser

1. Grant the intended HTTP(S) origins, including port. lomi_browser_open creates an isolated native profile and returns an operation; keep its browser generation and lease.
2. lomi_browser_snapshot returns bounded semantic elements and frames. Use its snapshotId, navigationId, element/frame references and viewportRef.
3. lomi_browser_fill, click, scroll or key acts on the current referenced target with the lease. Poll modifying operations.
4. Refresh the snapshot after a page change. lomi_browser_wait waits at most ten seconds for load, URL, DOM text or a role/name, and replaces old references.
5. lomi_browser_logs reads JavaScript errors, console messages or promise rejections. lomi_browser_screenshot returns a viewport PNG with explicit composite-capture permission.

Snapshot coverage includes at most 16 same-origin HTTP(S) frames to depth four. Cross-origin/opaque/hidden/over-budget frame content and all form values are omitted. References expire after 60 seconds or navigation, a new snapshot, document/frame replacement or takeover. Snapshots are not a complete accessibility tree.

Clicks, fills and keys use synthetic DOM events. They do not provide trusted user gestures. key dispatches to an already focused top-level element and reports defaultAction: false; it is not native keyboard editing or traversal. Click cannot activate file inputs or ordinary downloads.

visible: false can prepare a hidden browser without changing selection. DOM reads can work while hidden, but input/screenshots need an appropriately visible renderable panel; focus its exact generation first. Navigation completion means native document commit or page load, not network idle. Screenshots can contain third-party frames even though DOM reads omit them.

Each log kind retains 64 main-document entries of at most 256 UTF-16 units. Cursors belong to that kind/document. Objects, stacks, child-frame/network data and headers/cookies are omitted. Reports can be synthetic; eventTrusted alone is not authenticity proof on WKWebView. A page can replace console methods and bypass later collection.

Transfer files through artifacts

Artifacts are private immutable copies with IDs, sizes and SHA-256 values. They are not arbitrary local paths and expire after 24 hours. Re-reading/exporting rechecks original source permission and, for captures/downloads, the originating device or browser generation/profile/origin. A closed or human-taken source can deny later access.

• Import: lomi_artifact_import takes a project-relative source, exact length/hash and kind: "file" (0-4 MiB) or kind: "android_apk" (4 bytes to 512 MiB). Poll for the artifact. Generic files remain opaque; metadata reads do not reveal their bytes or private storage path.
• Upload: import the file, identify a visible file_input and frame in a snapshot, then request lomi_browser_upload with the artifact/hash and a basename. With YOLO off, approve the exact page/input, filename, size and hash in Browser upload requests. The page can transmit bytes immediately after attachment. Success confirms attachment and input/change events, not server acceptance.
• Download: lomi_browser_download performs a bounded same-origin GET in the owned profile, with maxBytes up to 4 MiB and a five-second deadline. It uses that profile’s same-origin credentials and refuses redirects, URL credentials/fragments and custom methods/headers/body. A failed/cancelled GET can still have a server effect.
• Export: lomi_artifact_export writes up to 4 MiB to a new project-relative file after checking the destination parent revision and original source scopes. It creates no parent folders and never overwrites a file or link.

Imports share a 2 GiB global quota, 1 GiB per connection/project, 64 files and two producers. APK limits are separate from the 4 MiB upload/export limit; a large imported APK is not automatically exportable.

Operate a managed Android device

1. lomi_android_list shows devices explicitly shared in pairing. lomi_android_open creates/selects a retained panel without booting the device.
2. lomi_android_start starts a stopped device or reuses this connection’s generation. Poll until native Android/RPC/ADB/IME readiness; boot can take up to 180 seconds.
3. lomi_android_snapshot reads a bounded UI Automator projection. lomi_android_screenshot gives a PNG with dimensions, rotation and an image-to-hardware coordinate transform.
4. lomi_panel_control obtains Android input authority. lomi_android_input sends ordered touch, key, navigation, rotation or committed Unicode text events. The selected panel must be visible in a focused Lomi window.
5. lomi_android_launch delivers an intent to an approved package; verify behavior with snapshot/logs. lomi_android_logcat reads a recent snapshot for the approved package’s running main process.
6. lomi_android_stop requests confirmed stop without deleting installed apps/data. Force stop remains a native user-interface action.

Snapshot node IDs are observation-local, not input targets. Editable/password values are omitted; Canvas, WebView and secure screens can be incomplete. Input uses hardware_display coordinates, while snapshot bounds use rotated_display; use the reported dimensions/rotation and screenshot transform. Screenshots are single PNGs, not continuous MCP video or desktop capture (up to 1600 pixels per edge, 2 million pixels and 3 MiB).

The UI projection has at most 500 nodes, 48 KiB output and a 12-second deadline. Logcat covers recent main-buffer lines from the running main process, not all subprocesses/crashed apps or every log buffer. It refuses shared-UID packages and reports unknown gaps; cursors last 60 seconds. There is no arbitrary ADB shell, clipboard tool or implicit Enter.

SDK setup, devices and APK installation

lomi_android_setup_plan supports inventory, catalog pages and an exact prepared SDK/private-Java plan. Planning does not download SDK archives or accept licenses. Apply the plan/revision within 30 minutes using lomi_android_setup_apply; with YOLO off, Settings shows sources, versions, sizes and provider terms for human approval.

lomi_android_device_manage handles create/modify/wipe/delete, recovery, bounded owned-cache cleanup, metadata restoration and package removal/rollback. Existing devices must be explicitly shared and stopped; destructive targets require their exact name. Modification preserves image/data-partition size and applies hardware changes on next start. Referenced images are immutable.

For APKs, import the exact bytes first, then call lomi_android_install_apk for the controlled running generation. With YOLO off, approve that copy/device in Settings within 120 seconds. Installation may take 180 seconds; it preserves app data and does not uninstall on failure. INSTALL_FAILED_INSUFFICIENT_STORAGE is a concrete failure, while interrupted/unrecognized outcomes can be unknown. Inspect the device before requesting again. YOLO automatically handles supported approvals as described in permissions.

Read or change Git

lomi_git_status, diff, history, commit and remotes use guarded read-only system Git. Specify repositoryRelative for a repository inside the project; the reader does not discover arbitrary ancestors. Linked worktrees/external metadata are unsupported. Reads deny helpers, writes and network. Remote observations redact credentials, repository paths, query/fragment and unknown transports.

Status cursors page an immutable per-command snapshot for 60 seconds; later disk changes do not change that cached page. Diff continuation requires the exact observation revision. History continuation keeps the returned starting commit rather than following a moving HEAD. Commit APIs require a full 40/64-character SHA; merge changed-file comparisons use the first parent. lomi_git_open opens a read-only diff/commit view.

lomi_git_mutate supports stage, unstage, commit, fetch, push, discard and pull. With YOLO off, each request gets an exact main-window approval plan bound to files, index, HEAD, refs, configuration and environment. Git execution can run configured hooks/helpers with your account; read permission does not grant it.

• Commit takes the complete staged path set and exact message; it does not stage implicitly. Git’s final LF behavior is disclosed in the preview.
• Fetch updates one approved remote-tracking branch; it does not merge, prune, fetch tags or submodules.
• Push needs network/push scopes, current HEAD and an exact expected remote commit (explicit null means create only if absent). Fast-forward checks and an expected-value lease prevent history rewrite/concurrent overwrite.
• Discard restores tracked worktree files from the index, preserving staged changes. Discarded worktree bytes are not stored in Git or Trash. Dirty buffers block it; use file Trash for untracked entries.
• Pull needs network/pull scopes, a clean tracked worktree, current HEAD and a locally observed remote commit (fetch first). Modes are ff_only and bounded linear rebase. Conflicts remain visible; Lomi does not automatically abort, reset, stash or replay.

Work with Chat AI

lomi_chat_list lists metadata for individually shared conversations (up to 64). lomi_chat_read reads saved draft/message checkpoints; it omits reasoning, attachments, system instructions and provider metadata. A null message ID selects the active leaf; use parent IDs to walk the branch.

lomi_chat_open reuses an existing conversation or creates one with target.type: "new". It sends no provider request. lomi_chat_draft replaces up to 32 KiB of persisted draft text, preserving attachments and protecting concurrent human typing. It does not send.

For lomi_chat_send, read with includeSendTarget: true to obtain the configured connection/model and current conversation/draft revisions. With YOLO off, Lomi presents actual context, attachments, system instructions, model, response limit and possible charges for approval. The tool cannot change the provider/model. Poll the operation; draftRevision: null means reservation rather than accepted send. Never resend with a new key after an uncertain provider effect.

lomi_chat_stop targets an exact native requestId, so a retry cannot cancel a newer answer. lomi_chat_export returns Markdown/JSON text for saved message variants and draft, bounded to 512 messages/4 MiB; it writes no file and calls no provider. Later pages require its document revision.

Change settings or arrange the workspace

lomi_settings_read reads retained effective editor defaults, terminal preferences, keybindings or theme selections/safe mode. lomi_settings_update requests one revision-bound patch: indentation, a closed terminal field, shortcut set/reset, focus-follows-pointer, built-in Lomi/DeepMono or system/light/dark appearance. With YOLO off, Settings displays before/after values for approval. Custom theme import/selection and recovery writes are unsupported. lomi_settings_open only requests the named Settings section.

lomi_workspace_create starts with a scratch file, not a shell. lomi_workspace_update renames/selects or requests close. lomi_project_open requests another canonical root with one workspace; lomi_project_close requires all current workspaces. lomi_panel_move supports tab reorder, docking, moving a pane and same-project transfer between approved workspaces. It preserves qualified live resources and rejects unsupported plugin descendants, modal UI or insufficient space.

Closure respects dirty-buffer dialogs, protected/busy/human-owned runtimes and shared views. The final Android view requires confirmed Stop; the final Chat view requires saved drafts/native checkpoints and stop permission. Saving during closure keeps the workspace/project open with partial effects; read the new state before requesting closure again. Closing a project never deletes its folder.

Source: tool behavior and limits, broker domain adapters, native usage/qualification boundaries.