Skip to main content
The GRID agent calls your robot’s available methods, reads documentation, and writes and runs Python skills through your GRID development session. You review actions before they run. A saved script, a finished call and a verified task are three different results.

​
Start a conversation

Set ANTHROPIC_API_KEY in the shell that starts GRID and sign in to GRID as usual. Inside the GRID terminal, run:
Use agent --no-robot to write code without connecting to hardware. Running agent without either option reuses your current live robot connection. If there is no live connection, it offers an online-robot picker. Use --no-robot when you want to author code without attaching to that connection. Recent tool calls stay visible while the agent works. Press Tab for the full trace, and use arrow keys or Page Up / Page Down to scroll. Saved filenames are terminal hyperlinks. Escape cancels and closes the conversation after cleanup. Conversation history is retained between turns, but cannot be resumed after a CLI restart. Ask for a destination, for example: Take me to the nearest chair. When Nav is available, the agent checks its active map. If no map is active and you have not specified one, it asks which to use before starting navigation and searching for matching objects. Setup and planning do not require approval. It plans a route and opens the viewer before asking you to approve movement. Review the destination and route, then press y followed by Enter to run it. If the map or starting position changes during approval, the agent must plan again. The agent uses the robot’s mission result to report completion or failure. Press Ctrl+X to request a stop during an action. Status and stop controls remain available while the action runs. A stop request alone does not confirm that the robot has stopped; follow the terminal’s stop question before another action. Press Ctrl+L to inspect agent events, then Tab to switch to the robot’s mission log. Inspected robot logs are saved under the session’s robot-logs directory; the terminal shows the file location. Logs remain available after a tool call.

​
Review, run and check

  1. The agent reads the docs, then saves a draft in your skill library, ~/.grid/skills/, the same wherever you start GRID. Draft saved means the code has not run. The agent can also revise an existing skill after reading it; if someone changed the file meanwhile, GRID refuses the save.
  2. Before an action, review its target, source, arguments, limits and success condition. Press y then Enter to approve, or Enter / n to deny. Changes to the approved program or inputs require another approval. Read-only tools do not need approval.
  3. GRID runs approved Python through the same runner as skill run, captures its output and reports the process result. After a completed run, an unchanged program may retry within its approved trial limit. A run that fails, times out or is cancelled needs a new approval.
  4. After the process ends, GRID asks you to check the robot, stop it if needed, and confirm it has stopped. It then asks whether the approved task succeeded, failed, or remains unclear. An exit code or the model’s answer does not prove task success.
The person testing remains responsible for the prepared robot and its motion limits. Python runs with your host’s permissions; this is process supervision, not an OS sandbox. Connecting establishes a GRID session; it does not check physical readiness. For direct robot actions, cancellation requests the robot’s stop control. For generated Python programs, cancellation ends the task process; that alone does not stop the hardware. You remain responsible for checking the robot, and GRID blocks another action while stopping is unconfirmed.

​
Call the agent without the terminal UI

Create a request file. query and all three limits fields are required; omit robot to work without a selected robot.
The final JSON result goes to stdout. Live approval notices go to stderr as JSON lines, so your application can watch for decisions while keeping stdout parsable as one document. Omitting approvalDirectory denies actions, but still permits read-only work and authoring. For each approval, the notice gives proposalPath, decisionPath, approvalHash, requestId and decideBy. Your application or an operator must:
  1. Read the complete proposal and decide whether to allow it.
  2. Write this decision to a temporary file beside decisionPath.
  3. Atomically rename that file to the exact decisionPath from the notice.
Use false to deny. Every request has new paths, including retries. An expired, used or mismatched decision cannot approve a later request. The directory must belong to the current user and must not be writable by other users. The default wait is 600 seconds; approvalTimeoutSeconds accepts 60–3600 seconds. File approvals are unavailable on Windows; program execution requires POSIX process groups. answers supplies replies to the agent’s ordinary questions. It cannot approve execution or confirm a task outcome or a stopped robot. Headless runs can execute approved robot actions or Python and return logs, but physical task outcomes stay unknown. Without live operator confirmation, another run stays blocked until someone checks the robot and reconciles stopping in an interactive session. The final result’s data.host reports denials, action failures, cancellation, stop confirmation and task verification. Check the overall ok and code as well as the model’s text. needs_attention means a host check prevented success; invalid_request means the input was rejected, and setup_failed includes a missing model key. A model failure may supply its own error code.

​
Limits and recovery

Interactive defaults are 60 tool calls, 900 seconds of working time and 10 execution trials. Model usage is recorded in session logs without a spending limit. A trial counts a program or robot action start, not each robot movement within it. Waiting for a person is excluded from working time. Headless requests supply these limits explicitly. Session evidence is saved in ~/.grid/agent/sessions/<id>/events.jsonl. Keep any unresolved stop record: deleting it bypasses the block without establishing that the robot stopped. Check the robot and follow GRID’s recovery message in an interactive session. Recovery also checks that the old process has ended; it does not pre-approve another task. Documentation comes from the hosted GRID docs MCP. GRID_DOCS_MCP_URL overrides that endpoint for a custom deployment. See the CLI reference for the other GRID commands.