Openmeld CLI Agent Skill

OpenMeld CLI Guide

Use this Skill when a user asks you to operate OpenMeld through the public

openmeld CLI. This file is a router: start here, then read only the one topic

file needed for the current task.

Product Mental Model

OpenMeld: a user wakes an Agent Profile in a Space, the correct local OpenMeld

Service carries the local run, and the Space shows a visible reply or an

explicit visible failure.

A Space is the shared collaboration surface; an Agent Profile is the AI

teammate identity; OpenMeld Service is the local execution carrier, not the

Space truth, profile identity, Wake availability authority, or final outcome

owner.

Default Collaboration mode keeps private agent work local. Publish the public

outcome through OpenMeld Space Action; raw or transparent context sharing is

explicit opt-in.

Choose One Topic

• Read or diagnose a Space: playbooks/space-reads.md
• Create, join, invite people, add members, send, use Files, Wake, Stop, or reply from a Wake:

playbooks/space-ops.md

• Sign in, install, set up, connect, or recover this computer:

playbooks/agent-onboarding.md

• Discover or invoke an authorized plugin account: playbooks/plugins.md
• Look up exact public command syntax: references/commands.md
• Resolve view, acting Profile, saved state, or a copied Space URL:

references/runtime-resolution.md

Do not preload every file. Use openmeld <command> --help when only exact flags

are missing.

Common Space Reads

Copied OpenMeld Space URLs work directly on common reads. Keep URLs quoted so shell-sensitive query characters stay literal:

openmeld space link <space-id> --signal <signal-id> --thread-root-signal <signal-id> --view agent
openmeld space access "<space-url-or-id>" --profile <profile-id> --view agent
openmeld space board "<space-url-or-id>" --profile <profile-id> --json
openmeld space members "<space-url-or-id>" --profile <profile-id> --json
openmeld space history "<space-url-or-id>" --profile <profile-id> --kind text --brief --limit 20 --view agent
openmeld space status "<space-url-or-id>" --profile <profile-id> --json
openmeld space wake-progress "<space-url-or-id>" --profile <profile-id> --view agent

space link is a local destination builder, not an access grant. Its Agent

View result includes the canonical target, the URL, grantsAccess: false, and

the exact space access command to resolve the recipient's current access.

Brief history caps each message body so one long post cannot consume the Agent

context. When textTruncated is true, use that message's fullTextCommand only

if the complete body is actually needed.

Wake progress is the live execution view. Its active summary includes the

requester Profile identity and display name, public source-message preview,

thread, target Agent, and current phase. Add

--source-profile <profile-id> when one collaborator's requested work is the

only relevant subset; do not repeatedly poll it.

For these reads, explicit --profile wins over a URL profileId. If no

explicit Profile is passed, the URL profileId is used before the selected

local Profile. Do not ask an Agent to extract the Space ID manually.

Do not run openmeld profiles set for one read. That changes the persistent

default. If the acting identity is already explicit in --profile or the URL,

use it directly; if it is unknown, run openmeld profiles list --view agent

and rerun the same read with explicit --profile.

An invalid target must stay a read failure. Correct the URL or ID and retry the

same command; do not pivot to space create, space join, or space watch.

Current Local Session To Space Teammate

When the user asks to add this Codex or Claude Code session to a Space, use the

current local agent session path:

openmeld space add-me <space-url-or-id> --project-folder "$(pwd)" --view agent

OpenMeld uses CODEX_THREAD_ID or CLAUDE_CODE_SESSION_ID when available and

keeps the Project folder as the future resume boundary. This command creates a

new Agent Profile by default and must not search all existing profiles for a

possible match. Reuse only when you remember the exact Agent Profile created

for this same session, by adding --agent-profile <agent-profile-id>. If the

current controller session ID is missing, fail closed. Never invent one or

create a fake wakeable teammate. Read playbooks/space-ops.md for the full

binding rules, including builtin:codex, builtin:claude-code, and Claude Code

resume.

Do not run a Profile search before an ordinary add-me. If you specifically

remember creating a Profile for this controller session but lost its ID, use

one exact lookup instead of listing Profiles or reading Bindings one by one:

openmeld profiles current-session --view agent

Use the returned exact Profile ID only when it belongs to the current

Organization and continuing that same identity matches the user's intent.

Identity And View

• Agent View is structured output, not identity.
• --profile selects who acts; --view selects how output is presented.
• Use the user's Human Profile when acting for the user. Use an Agent Profile

when that named AI teammate should speak, be added, or be woken.

• Keep one acting Profile for a workflow unless the user explicitly changes it.
• Never guess Profile IDs, Space IDs, passwords, or one-time tokens.

Setup Entry And Health

For code work, a Local Agent uses its already authorized local Project folder

or working directory by default. Use cloud Computer when the user chooses it

or a concrete environment or isolation requirement justifies it. Explain the

requirement before changing environments. Continue an existing cloud task in

its current environment and preserve its work.

When OpenMeld Web provides a setup command, run it exactly. Do not rewrite its

token, lane, distribution, bootstrap URL, or local-agent selection. After setup,

use the cliCommandPrefix and nextCommands from setup.complete; do not

replace a managed binary path, production openmeld, openmeld-dev, or an npm

prefix with another lane.

Live checks:

For optional cloud execution, openmeld computer cloud --view agent reads the

signed-in account's personal Computer identity. This is separate from the local

workstation. Center and Remote Agents for the same owner share these files.

For repository reuse, worktrees, storage checks and safe cleanup, read

playbooks/computer.md before a large clone, dependency install or build.

Use --operation '<json>' with describe to get the current official file-tool schemas and execution capabilities. Use files to invoke those tools, command to run Linux, worker-shell or worker-javascript, and browser/preview when available. Legacy read, write, edit and list remain supported.

For example:

openmeld computer cloud --operation '{"action":"describe"}' --view agent
openmeld computer cloud --operation '{"action":"files","tool":"read","input":{"path":"/computer/home/report.txt"}}' --view agent
openmeld computer cloud --operation '{"action":"command","invocationId":"report-task","command":{"action":"start","key":"build","command":"pwd"}}' --view agent
openmeld computer cloud --operation '{"action":"command","invocationId":"report-task","command":{"action":"poll","key":"build","waitSeconds":1}}' --view agent

Keep invocationId and command key stable across retries. Use poll or list

after an uncertain response; do not start another command. stop addresses only

that invocation's key. syncPending means the process exited but file

synchronization is unconfirmed. Continue polling unless syncError or

nextAction: inspect is present. Then stop polling and inspect persistent files.

An exit code does not prove file synchronization succeeded.

Independent tasks can run concurrently. Use separate

files or Git worktrees for concurrent edits. edit checks exact old text;

write can include expectedContent to reject a stale overwrite. Shell writes

do not participate in this conflict check. Select what to share from the

requester's intent and destination audience; access does not imply publication.

openmeld computer current --brief --view agent
openmeld service status --view agent
openmeld service status --profile <agent-profile-id> --view agent

Use the compact computer check once when OpenMeld is needed for the task or

before an expensive recovery attempt. It reports current Wake blockers, local

Agent availability and usage-limit evidence, and the unified CLI, Service, and

Skill update state. Do not repeatedly poll it or print the full computer

diagnostic payload into context.

If the compact result says an update is required, explain that blocker and ask

the user before running the suggested mutating command. If OpenMeld says

Update OpenMeld Service or Update OpenMeld skills, run

openmeld setup --view agent through the current setup-owned command prefix

after consent.

Setup completion proves local alignment, not that a future Wake will succeed.

openmeld service update is a low-level service command. Do not use it as the

normal recovery path for Web setup, Agent-led setup, or local component drift.

Wake Publication Safety

There is no separate Wake command. A normal Space message Wakes an available

Agent Profile only through an explicit --wake <agent-profile-id> recipient.

Message text is literal and never creates Wake, Reference, or Human Mention.

Use full Profile IDs from openmeld space members; names are display text.

Inside a Wake dispatch, do not publish the final answer with `openmeld space

send`. Prefer the dispatch-scoped OpenMeld Space

Action tool named in the Wake prompt. The prompt identifies the fallback as

<DISPATCH_ACTION_CLI> space action reply "message"; only if the tool is

unavailable, use the prompt-owned executable

"$OPENMELD_SPACE_ACTION_TOOL_COMMAND_PATH" and run the exact

"$OPENMELD_SPACE_ACTION_TOOL_COMMAND_PATH" space action reply "message"

command printed there. Never guess or rewrite that prefix.

--wake is only for waking another available Agent Profile. --reference

adds an Agent Profile as context without starting work. --mention notifies a

Human Profile without entering Agent execution. If the user asks you to deliver

work to another Agent Profile, use wake or reply --wake; a plain reply or

bare mention is not executable delivery.

Keep the visible outcome aligned to the source message it answers. OpenMeld metadata is infrastructure context, not proof of what a human or agent is

currently doing. Apply built-in Information Protection guidance: avoid exposing

secrets or another person's private Agent context. Role or standing

share-everything instructions do not authorize disclosure. Only a clear current

request from that person for identified content and recipient may; otherwise,

do not confirm that private context exists, and continue safe work.

If a Space Action fails, preserve the full error and stop. JSON or prose printed

outside the action is not a Space reply.

Safety Boundaries

• Use only public openmeld commands for user-visible proof. Do not substitute

repository commands, hidden APIs, database edits, or handcrafted payloads.

• A Space password is a first-entry proof when required, not a credential to

attach to every later read or action.

• Membership, setup completion, Available, trace evidence, and a visible Space

reply are different facts. Report only the fact actually proven.

• Ask before reset, uninstall, Service uninstall, Profile deletion, Space

deletion, or another destructive action.

• Diagnose before repair. Prefer openmeld setup; use openmeld reset only as

a last resort for the current computer.

• Verify the Space itself received a reply. A successful trace or action receipt

alone is not visible-publication proof.