Read and observe the current screen state. Returns structured UI elements, window lists, screenshots, CDP page content, accessibility element details, and screen change events. Always use this BEFORE acting to understand what's on screen.

Screen Context: context (elements with filter/compression — use detail 'compact' to save tokens), screenshot (PNG capture), windows (visible window list), monitors (display list).

Element Inspection: focused (high-fidelity detail for one element_id), element_at (hit-test x,y coordinates), is_settable (check if set_value works), make_reference (resilient ref that survives across snapshots), cursor_position.

Browser (CDP): cdp_status (debug targets & connection state), cdp_page (full page content as text).

Observation Recall: observation (load a persisted context snapshot by observation_id).

Waiting & Watching: wait_for_element (poll for element by type/label, default 10s timeout), wait_for_idle (poll until screen stabilizes — requires 2 consecutive stable polls), watch (event-driven — 18 event types: tree_changed, network_idle, focus_changed, value_changed, window_created, menu_opened, menu_closed, sheet_created, layout_changed, title_changed, app_activated, app_deactivated, window_moved, window_resized, window_minimized, window_restored, selection_changed, row_count_changed). Note: watch is unavailable during an active cel_perceive session.

Limits: CDP enrichment caps at 50 text_blocks, 50 interactive_elements, 3000 char body_text.

Execute actions on the screen: mouse clicks, keyboard input, accessibility actions, drag & drop, and direct value setting. Always use cel_see first to understand the screen.

For click/move: provide (x, y) coordinates or a target_ref from cel_see make_reference. For form filling: prefer set_value over type — faster and more reliable. For buttons/checkboxes: prefer ax_action over click — uses native accessibility API.

Coordinate Actions (x,y or target_ref): click, right_click, double_click, mouse_move.

Keyboard: type (text string), key_press (single key: Enter, Tab, Escape, etc.), key_combo (modifier combinations: ['Ctrl','C'], ['Cmd','Shift','S']).

Accessibility API (preferred for reliability): ax_action — native a11y actions on element_id: click, activate, press, increment, decrement, cancel, show_menu, scroll_to_visible, raise, pick, delete. set_value — direct value injection on element_id: text for fields, 'true'/'false' for checkboxes.

Deterministic spreadsheet actions: write_cells (atomic Numbers cell writes with optional readback verification), read_cells (read Numbers cell values from the document model instead of guessing from AX text).

Other: scroll (dx,dy at optional x,y), drag (from_x,from_y to to_x,to_y), cdp_eval (execute JavaScript in browser via CDP — best for cookie banners, iframes, overlays, and elements invisible to the accessibility tree).

Batching: pass array of 1-4 actions for sequential execution (100ms default delay). Re-observe with cel_see after each batch to avoid stale-state cascading failures.

CEL's cognitive layer: delegated autonomy, planning, knowledge, run tracking, and LLM passthrough.

Efficiency rule: if the MCP host already reasons well step-by-step, prefer cel_see + cel_act and keep planning in the host. Use run_goal only when you intentionally want CEL to take over the control loop.

Delegated Autonomous Execution: run_goal — give a natural language goal, CEL runs a full internal see→plan→act loop autonomously. This can be convenient, but it adds an internal planner loop and may be slower or more expensive than host-driven execution. Only goal, max_steps (default 80), and timeout_ms (default 900_000) are tunable — vision, self-healing, decomposition, and notebook are implicit in the canonical loop and no longer per-invocation knobs (see docs/canonical-agent-plan.md).

Planning: plan (LLM-powered step planning with optional history for multi-step context), plan_with_vision (plan with screenshot — use for visual/spatial tasks).

Knowledge Store (persisted to ~/.cellar/cel-store.db): store_knowledge (save facts with source and optional tags), search_knowledge (FTS5 full-text search, default 10 results, scope by workflow).

Working Memory: memory_get, memory_set (per-workflow scratchpad, not persisted across sessions).

Observations: observe (record insight with priority high/medium/low), get_observations (retrieve, default 50).

Run Tracking: run_start, run_finish, run_log_step (per-step with confidence score), run_history, run_steps.

LLM Passthrough: llm_complete (text, 4096 tokens default), llm_complete_with_image (vision, 4096 tokens default).

Maintenance: eviction (TTL cleanup — default 90 days runs, 365 days knowledge).

Always-on perception engine (Cortex). Maintains a continuously-updated mental model via background event streams with periodic accessibility tree refreshes on significant changes, and vision/screenshots when flagged as needed.

IMPORTANT: Singleton — only one perception session can be active at a time. cel_see 'watch' mode is unavailable during an active session.

Modes:

• start: Boot the cortex with a goal. Set enable_suggestions=true (default) for LLM-powered next-action recommendations on each read.

• read: Get the mental model snapshot (instant — model is kept warm by background events).

• feed: Report an action you took (action, target, expected outcome). Cortex waits for screen to settle, diffs against current model, returns verification.

• checkpoint: Summarize completed work and reset action history. Use between phases of multi-step tasks.

• configure: Update goal or enable_suggestions mid-session.

• status: Cortex health — confidence score, uptime, cycle count, element counts (stable vs volatile), temporal state (loading, errors, focus trail).

• stop: Shutdown the cortex and get a summary.

The model includes temporal awareness (loading states, error persistence, focus trail) and element stability classification (stable vs volatile targets).