Usage examples

Generate text from the shell, ask for advice through MCP, or delegate a native task that you can poll.

Generate from a script

This example uses a compatible, signed-in Grok Build installation and its native model default. From an existing project folder, approve that directory for Grok. The prompt defaults to No.

clink allow "$(pwd -P)" --cli grok

Save the following as request.json. Replace the example project path with the output of pwd -P. Give each new attempt a fresh UUID.

{
  "schema_version": 3,
  "request_id": "66f96fc9-969d-4c0e-ab92-e355fa0e7588",
  "execution_mode": "native",
  "project_dir": "/absolute/path/to/your-project",
  "cli": "grok",
  "model_selection": {
    "kind": "native_default"
  },
  "instructions": "Rewrite the supplied text for clarity. Return only the revision.",
  "input": "Explain the tradeoffs of a cache for this application.",
  "timeout_seconds": 120
}

clink generate --request-json - < request.json

Clink reads one JSON object and writes a terminal result to stdout. Check for exit code 0 and status: "completed". Validate the request ID and hashes before using the output. A failure is returned to the caller without an automatic retry or agent switch.

Consult with Codex

In a connected MCP client, pass this object to the clink tool. Omitting the action selects an advisory consultation. This operation requires the verified Codex build.

{
  "cli_name": "codex",
  "prompt": "Review this proposed change and suggest a clearer error message: a missing input currently returns “failed”."
}

Start a native task

To ask Claude Code to work in a project inside its configured roots, use the start action. Native agents use their own tools and permissions and can change files or call external services.

{
  "action": "start",
  "cli_name": "claude",
  "project_dir": "/absolute/path/to/your-project",
  "prompt": "Inspect the test suite and report which checks cover the parser.",
  "request_key": "inspect-parser-tests-1",
  "timeout_seconds": 180
}

Save the returned task_handle. Replace the placeholder below and pass the object to the same MCP tool to poll its state. See the native task guide for follow-up, cancellation and restart behavior.

{
  "action": "status",
  "task_handle": "<returned task_handle>"
}