Run the unified UniGrok agent on any task. This is the headline entry point — use it by default for anything nontrivial instead of picking a specialized tool.

It auto-routes across Grok models (planning model for reasoning-heavy tasks, coding model otherwise), gives the model its full action space on every request — xAI server-side web search, X search, and sandboxed code execution plus local file, git, and test tools — and lets the model decide for itself whether to act. Pass a session name and it remembers prior turns, including tool observations, so multi-step work continues across calls. When the client requests progress (MCP progressToken), depth and tool progress is reported live via the injected FastMCP context.

Args: task: The goal, question, or task for the agent. session: Optional session name. Persists conversation history and tool traces so later calls can continue the work. mode: "auto" (default) self-routes; "fast" forces a single toolless completion for trivial prompts; "reasoning" pins the planning model; "thinking" runs the agent loop plus a schema-enforced reflection review for the hardest tasks (slowest, most expensive); "research" runs multi-agent research on the planning model (agent_count from UNIGROK_RESEARCH_AGENT_COUNT, 4 or 16) with inline citations requested — sources come back under citations. model: Optional Grok model id. Leave unset to let routing choose. require_reasoning_level: Minimum required Grok reasoning level (low, medium, high).

Returns: AgentResult containing execution metadata and responses.

Send a text prompt to a Grok model and return its reply.

Absorbs the old agentic_chat tool: the ReAct AgentLoop is now the default route, so the model has its tool surface and self-directs. Set enable_agentic=False to force a single toolless completion.

Args: prompt: User message to send to the model. session: Optional session name. Persists conversation history. model: Grok model id (defaults to grok-build-0.1). system_prompt: Optional system instruction prepended to the conversation. agent_count: 4 or 16. Only valid with grok-4.20-multi-agent. enable_agentic: If True (default), runs through the ReAct AgentLoop. require_reasoning_level: Minimum required Grok reasoning level (low, medium, high).

Unified @grok Entry Point: run the thinking route — the ReAct AgentLoop wrapped in a schema-enforced reflection loop — with explicit retry and budget caps.

Args: prompt: Task or question for the agent. session: Optional session name for persistent history in chats. model: Grok model id (default grok-4.3). system_prompt: Optional system instruction prepended to the conversation. max_iterations: Strict cap on reviewer-driven correction retries (default 5). cost_limit: Total budget in USD before hard abort (default 0.50).

Run a structured, tool-free Grok review of an artifact or plan.

Use this when a client needs a deterministic critique shape rather than a full agent run. It calls xAI structured outputs through the shared _parse_structured helper, so the reflection pass cannot invoke local tools and degrades explicitly if structured parsing is unavailable.

Continue a server-side stored conversation using xAI's stateful chat.

Args: prompt: User message to append. model: Grok model id (default grok-4.3). response_id: ID of the previous response to continue from. system_prompt: Optional system instruction.

Returns: ChatResult containing execution metadata and responses.

Fetch a stored chat completion from xAI by its response ID.

Args: response_id: ID returned by a prior stateful_chat call.

Delete a stored chat completion from xAI's servers.

Args: response_id: ID of the stored response to remove.

Analyze one or more images with a Grok vision model.

Args: prompt: Question or instruction about the image(s). session: Optional session name for persistent history in chats. model: Vision-capable Grok model (default grok-4.3). image_paths: Local image file paths to analyze. image_urls: Public image URLs to analyze. detail: Image detail level. One of "auto", "low", or "high".

Chat with Grok using one or more previously uploaded files as context.

Args: prompt: Question or instruction about the attached files. file_ids: IDs returned by xai_upload_file. session: Optional session name for persistent local history. model: Grok model id (default grok-4.3). system_prompt: Optional system instruction prepended to the conversation.

Generate new images or edit existing ones with Grok Imagine.

Args: prompt: Image description or edit instruction. model: Image model (grok-imagine-image or grok-imagine-image-pro). image_paths: Local image files used as edit sources or references. image_urls: Public image URLs used as edit sources or references. n: Number of images to generate (1–10). image_format: "url" (default) or "base64". aspect_ratio: Aspect ratio like "16:9", "1:1", or "9:16". resolution: "1k" or "2k".

Returns: MediaResult containing image metadata and URLs.

Generate or edit videos with Grok Imagine.

Args: prompt: Video description, or the edit instruction for video editing. model: Video model (default grok-imagine-video). image_path: Local image to use as the starting frame. image_url: Public image URL to use as the starting frame. video_path: Local video to edit (max 20 MB, .mp4, ≤ 8.7s). video_url: Public video URL to edit (.mp4, ≤ 8.7s). reference_image_paths: Local images used as style/subject references. reference_image_urls: Public image URLs used as style/subject references. duration: Video length in seconds (1–15, ignored when editing). aspect_ratio: Aspect ratio like "16:9" or "9:16". resolution: "480p" or "720p".

Extend an existing video with a follow-up prompt.

Args: prompt: What should happen in the extended segment. video_url: Public URL of the source video (.mp4, 2–15 s). model: Video model (default grok-imagine-video). duration: Length of the extension in seconds (2–10, default 6).

Inspect the current health, versions, CLI auth, and sqlite metrics of the Grok-MCP server.

Exposes OKF bundle information, WebMCP manifests, and tool schemas for zero-configuration agent onboarding.

Safely restart the UniGrok Docker container by executing docker compose up --build -d. Only works if running in a context where docker compose is available and enabled.

List all chat sessions stored under the SQLite session store.

Return the most recent messages for a local chat session from SQLite.

Delete the history mapping and cascades messages for a chat session.

List live xAI API model IDs. Lightweight, direct, and fast.

List xAI API models, local Grok CLI models, and .grok model profiles separately.

Upload a local project file to xAI's servers so it can be reference-attached in chats.

Returns: A dict with file_id (pass it to chat_with_files/xai_get_file_content), filename, size_bytes, and a human-readable summary.

List all files uploaded to xAI from this account.

Retrieve metadata of a file uploaded to xAI.

Download the raw content of an uploaded file from xAI.

Delete an uploaded file from xAI.

Read a local project workspace file for code context or diagnostics.

List source code and config files present in the current workspace.

Solve a task by letting Grok write and run Python in xAI's server-side sandbox.

Renamed from code_executor — it invokes xAI's remote code_execution tool; no code runs on this machine.

Run local pytest verification without exposing arbitrary shell execution.

Query the web using xAI's real-time web search tool.

Args: prompt: The research question or search instruction. allowed_domains: Restrict search to these domains (e.g. ["arxiv.org"]). excluded_domains: Domains to exclude from search results.

Query X posts and profiles using xAI's real-time X search tool.

Args: prompt: The search question or instruction. allowed_x_handles: Restrict search to posts from these X handles. from_date: Earliest post date, ISO format (e.g. "2026-06-01"). to_date: Latest post date, ISO format (e.g. "2026-07-01").

Perform database compacting and optimization (VACUUM).

Return git status --porcelain for the current repository.

Return the current git diff, optionally for staged changes or one path.

Return a short one-line git history.

Return git show for a validated commit-ish ref.

Return the active branch name.

Create and switch to a new branch. Requires local git write mode.

Apply a unified diff patch. Requires local git write mode.

Commit explicit paths only. Requires local git write mode.

Submit a long-running research task as a deferred xAI job and return immediately. The job runs in the background with xAI's server-side web search, X search, and code-execution tools attached; poll get_research_job(job_id) for the result.

Args: prompt: The research question or task. model: Optional Grok model id. Leave unset to use the planning model. agent_count: Optional multi-agent fan-out — only 4 or 16 are accepted.

Returns: A dict with job_id (pass it to get_research_job), status ("queued"), and the resolved model.

Fetch the status and result of a deferred research job.

Statuses: queued/running (in flight), done (result and cost_usd present), error (error present), not_found, or stale — a queued/running job whose updated_at is older than UNIGROK_JOB_TIMEOUT_SEC, meaning the task that owned it did not survive a server restart and the job will never finish on its own.

Args: job_id: ID returned by submit_research_job.

List the most recent deferred research jobs, newest first.

Args: limit: Maximum number of jobs to return (clamped to 1-100, default 20).

Save one durable fact to the local workspace knowledge memory.

Facts are distilled knowledge — decisions, constraints, preferences, verified findings — injected as hints into future prompts that match them. Saving an identical fact again touches the existing row instead of duplicating it.

Args: fact: One self-contained sentence with concrete specifics. scope: 'global' (default, injected everywhere) or a session name for session-scoped knowledge.

Search the workspace knowledge memory for facts matching a query.

Local results are ranked by FTS5 bm25 when available (term-overlap otherwise). With UNIGROK_COLLECTIONS=1 and a capable SDK, matches from the xAI knowledge collection are merged in (origin='collection').

Args: query: Search terms. limit: Maximum number of local facts to return (1-25, default 5).

Permanently delete one fact from the workspace knowledge memory.

Args: fact_id: The id returned by remember_fact or search_knowledge.

Distill a chat session's stored history into durable knowledge facts.

Submits a background job (same lifecycle as research jobs — poll get_research_job(job_id)) that summarizes the session into 3-8 standalone facts on the cheap coding model and saves them to the knowledge memory with source='session:'.

Args: session: Name of a stored chat session.