Workspace context

modular context lets a local process use the registered contracts of one running workspace:

current directory ──▶ open workspace ──▶ commands · state · events

Run it from the same folder that is open in Modular. The CLI never falls back to another window.

Commands

Discover and inspect a command before invoking it:

modular context commands list
modular context commands describe local.coding-worker.askCodex

list returns ids, titles, and whether arguments are accepted. describe returns the argument schemas and return documentation available from the owner.

Arguments are a positional JSON array:

modular context commands run local.coding-worker.askCodex \
  --args='["Reply with exactly hi and nothing else."]'

The handler receives them as ctx.command.args. Its JSON return value is wrapped without losing the difference between a value and no return value:

{
  "kind": "command-completed",
  "commandId": "local.coding-worker.askCodex",
  "result": {
    "kind": "value",
    "value": { "kind": "completed", "response": "hi" }
  }
}

Non-JSON results are rejected instead of being stringified. See Commands for the authoring side and Terminal for the complete Codex example.

State

modular context state list
modular context state read workbench.layout
modular context state watch workbench.layout

read returns one snapshot. watch emits the current snapshot followed by each revision as newline-delimited JSON.

Snapshots contain the id, descriptor, access scope, value, revision, capture time, and previous version. The bridge is read-only. Run the command or action that owns a state change instead.

See State for declaration and ownership.

Events

modular context events list
modular context events subscribe editor.selectionChanged

list returns the event id, owner, schema, sensitivity, and stability. subscribe first emits event-subscribed, then one event entry per validated occurrence.

{"kind":"event","eventId":"editor.selectionChanged","value":{"current":{"charCount":4}}}

See Events for declaration and emission.

Process contract

Operation	Output
list, describe, run, read	one JSON object, then exit
watch, subscribe	one JSON object per line until the context ends

Streams end when cancelled, rejected, or when the app or workspace closes. Ctrl+C exits with code 130.

Common rejection kinds are app-not-running, workspace-unavailable, renderer-unavailable, unknown-command, unknown-state, unknown-event, not-permitted, and operation-failed. Branch on kind; do not parse error sentences or infer success from field presence.

For automation:

1. Discover ids with list.
2. Inspect command arguments with describe.
3. Read streams line by line as they arrive.
4. Treat state as read-only.