# The xai-cookbook is a catalogue of runnable Grok examples, not a library

> xai-cookbook is a repository of self contained example applications built on the SpaceXSI TypeScript SDK and the Grok APIs, covering podcast generation, realtime voice agents, prompt injection defences, tool disclosure, code sandboxes and evaluation harnesses. Every example teaches one idea end to end and is meant to be copied, which makes it a reference for patterns rather than a dependency.

**xai-org/xai-cookbook** — A collection of pragmatic, real-world examples guiding you from basic to advanced use of xAI's Grok APIs.

- Repository: https://github.com/xai-org/xai-cookbook
- Stars: 624 · Forks: 202
- Language: Python
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/xai-org-xai-cookbook

## A cookbook is a set of snapshots, and that is the point

The project is described as a collection of pragmatic, real-world examples guiding you from basic to advanced use of xAI's Grok APIs. The README puts it more plainly: runnable examples for building with Grok, and each example teaches one idea end to end with code meant to be copied.

That framing settles the question of what this repository is for. It is not a package you add to your dependencies, and it is not a service you deploy. Every example is a folder under examples/ with its own README explaining what it teaches and how to run it. The README's own catalogue is generated from those per example READMEs, which is a small detail that tells you the structure is the documentation.

The catalogue is organised into three tiers. Recipes are short, focused demonstrations: Article to Read-Along turns an article into audio that highlights each word as it is spoken using per-character timestamps from text to speech, Live Interpreter speaks one language and has Grok say it in another through the realtime voice API with a short-lived token, and Photo to Talking Character makes a photo talk with Grok Imagine reference-to-video. There are also Database over MCP, which serves a SQLite database as a read-only MCP server, and Progressive Tool Disclosure, which gives Grok 203 tools from a made-up company and lets it load only the few each question needs.

Guides are longer, and they are the entries that teach a mechanism rather than a trick. Apps are the largest category, and they are complete products rather than fragments.

The repository also carries a registry.yaml, a catalog directory, a templates directory and a .gitleaks.toml, which is a configuration for a secret scanner. The presence of a secret scanner config is a small signal about the shape of the repository, since every one of these examples needs an API key and a key in a committed file is the obvious mistake.

## The security examples are the most transferable part

Three entries stand out for a reader who will build anything with an agent, because they are about failure rather than about a feature.

Prompt Injection Defenses is described as watching poisoned pages try to make an agent leak private data, seeing each of four defenses miss an attack another catches, and stopping all ten with all four on. The framing is unusually concrete: four defenses, ten attacks, and a stated result for each combination. A guide that tells you which defense catches which attack is a far more useful artefact than a list of defense names, and the fact that it is presented as a table of misses rather than a wall of successes suggests the examples were actually run.

Progressive Tool Disclosure addresses a different problem that arrives as soon as an agent has many tools. The example gives Grok 203 tools from a made-up company's eight work apps, shows it only their names, and lets it load the few each question needs with tool search. The alternative, giving a model 203 full tool schemas, is a context cost and a mistake rate cost at the same time, and the example makes that visible with a deliberately absurd number.

Prompt Caching plays one 30-message chat three ways to see what the prompt cache saves, how the time at the top of the system prompt breaks it, and what compaction costs. That last part is the interesting one, because compaction is what you do when the context is too long and it silently changes what the model sees.

Between them, these three examples answer questions that the API documentation cannot: not what the parameter is, but what it does to your agent when things go wrong.

## Human approval is a pattern, not a feature

Refund Agent with Human Approval is listed as an Advanced example with a specific description: build a support agent that stops before a refund, waits for a person to approve it, and resumes the same run from a stored response, even after a restart.

That last clause is the whole difficulty of the pattern. An agent that pauses for approval and then continues has to survive the pause. If the process dies while it is waiting, the run cannot simply be restarted from the beginning, because the conversation history, the tool calls already made and the pending action all have to be recovered. The example handles that by storing the response and resuming from it, which means the example is really about durable execution state rather than about refunds.

The same concern shows up in a different form in Company to Call Brief, which preps for a sales call with a one-page brief as Grok searches the web and 𝕏 and looks up the account through CRM functions that run in your app. The distinction between a function that runs inside your application and one the model executes in a sandbox is a security boundary, and the description makes that boundary explicit.

Database over MCP takes the same idea to data. It serves a SQLite database as a small MCP server that only reads, and the example is that Grok lists its tables, reads their schemas and runs SQL through it to answer a question. The read-only constraint is stated rather than assumed, which is the correct way to do it.

## The sandbox and the code interpreter are two different things

CSV to Answers is described as dropping in a CSV and asking questions about it, with Grok writing and running pandas in a sandbox, showing the code it ran, and answering with computed numbers and a chart.

The detail that matters is that the code is shown. In a design where the model writes code and the code is run, the interesting question is not whether the model can write pandas, it is whether you would run code you cannot see. Showing the code is what makes the pattern safe to reason about, and the answer with a chart rather than a text summary shows the code path being used for the computation rather than the model guessing at a number.

A different example handles a different kind of grounded answer. Docs to Cited Answers asks questions about a folder of documents and returns answers that cite the passages they came from, with a metadata filter deciding which documents count. That filter is the part worth copying, because it is the mechanism that stops a document set from being more than the set you intended, and metadata is usually already there.

Screenshot to Component is a UI case with a self-checking loop: turn a screenshot of a UI into a React component styled with Tailwind, then have Grok compare the result with the original and fix what does not match. The comparison step is what turns a one-shot generation into an iterative one, and it works because a screenshot is a verifiable ground truth.

## Getting a key is the only setup step

The README is explicit about the path in for someone new. Start with the quickstart in the SpaceXSI docs, browse the models documentation, and get an API key from the SpaceXSI Console.

The repository itself carries a .env.example with the single variable every example needs:

```
XAI_API_KEY="your_xai_api_key"
```

That file is the entire environment contract. The Python side of the repository declares a small dependency set in pyproject.toml: check-jsonschema, jupyter, pip and python-dotenv, with a dev group of nbmake, pre-commit and pytest. Python 3.12 or newer is required, and the presence of a .python-version file, a uv.lock and a pyproject.toml points at uv as the tool in use for the Python example.

The TypeScript examples do not live in this repository's dependency graph. They use the SpaceXSI TypeScript SDK published on npm as @xai-official/sdk, and each example folder has its own package setup, which is the usual arrangement for a cookbook where every sample has to stand on its own.

The starting points the README recommends are worth following in order. For TypeScript, Podcast from a Link turns an article into a two-host episode with a few calls to the SDK. For voice, Web Voice Agent is a browser app you can talk to. And for data, the Real-Time Sentiment Analysis on 𝕏 example searches 𝕏 live and scores sentiment, with the detail that it keeps its outputs, so you can read the notebook on GitHub without running anything. That last property is a deliberate choice about how a cookbook should be readable, and it is a good one.

## Where the cookbook is the wrong thing to reach for

Four situations rule it out.

The first is when you want a dependency. The cookbook is examples, and the SDK is a separate npm package. If your problem is that the SDK lacks a method you need, the answer is in the SDK, and reading 25 example applications is an expensive way to learn its surface.

The second is when you need the code to keep working. A cookbook is a snapshot of patterns at a point in time, and it is not versioned against the API. The repository publishes no GitHub releases, so there is no tag to pin to and no changelog to check when an example breaks. The last push was on 2026-10-19, which shows the examples are being kept in step with something, but the individual examples carry no version marker of their own.

The third is when you want one pattern applied everywhere. Every example teaches one idea, which means adopting it means picking one example and adapting it, and you inherit that example's assumptions about structure, error handling and where the logic lives. That is fine for learning and awkward as an architecture.

The fourth is a language boundary. Most of the catalogue is TypeScript, with a few in Swift, Kotlin and Python. The Mobile Voice Apps example, for instance, is native iOS and Android apps with text-to-speech on iOS, and it is the only entry with two code links. A team that is standardised on one language will find the coverage thin outside TypeScript, and the Python notebook is a single example rather than a Python track.

The alternative worth naming is the official documentation itself, which is where the API reference and the model list live. The cookbook's contribution is precisely the thing documentation does not do well, which is showing a complete working application with the shape of the code visible. The right order is to read the documentation for the parameters and the cookbook for the patterns, and to write your own code for the parts that have to fit your system.

## Conclusion

The xai-cookbook fits a developer who already has an API key from the SpaceXSI Console and wants to see a working pattern for one specific Grok capability, whether that is a realtime voice agent, a tool calling loop, a prompt injection defence or an evaluation harness. It is the wrong choice if you want a maintained SDK, an abstraction layer or support, since the examples are deliberately standalone and the SDK is a separate npm package, and it is the wrong choice if you need English text, because the prose and the READMEs are the deliverable here and the Python notebook is one example among many. Before you start, check three things: that the example you want is in the catalogue and at the level you need, since the entries are labelled Beginner, Intermediate and Advanced, that the language is one you can run, since most examples are TypeScript with a few in Swift, Kotlin and Python, and that the patterns still match the current API, since a cookbook is a snapshot rather than a versioned dependency.

## FAQ

### What is the xai-cookbook?

It is a collection of runnable, real-world examples for building with the Grok APIs, most of them TypeScript applications built on the SpaceXSI TypeScript SDK, with a few in Swift, Kotlin and Python. Each example is a folder under examples/ with a README explaining what it teaches and how to run it.

### How do I get an API key to run the xai-cookbook examples?

The README points to the quickstart in the SpaceXSI docs, the models documentation, and the SpaceXSI Console for getting an API key. The repository ships a .env.example containing XAI_API_KEY="your_xai_api_key", which is the only environment variable the examples need.

### Which xai-cookbook example should I start with?

The README recommends Podcast from a Link for TypeScript, which turns an article into a two-host episode, Web Voice Agent for voice, which is a browser app you can talk to, and the Real-Time Sentiment Analysis on 𝕏 notebook for data work, which keeps its outputs so it can be read on GitHub without running anything.

### Does the xai-cookbook cover prompt injection defences?

Yes. The Prompt Injection Defenses example watches poisoned pages try to make an agent leak private data, shows each of four defenses miss an attack another catches, and stops all ten with all four on. The Prompt Caching guide also covers what the prompt cache saves and what compaction costs.

### What licence is the xai-cookbook under?

The project records a custom licence that GitHub cannot classify, so the terms are in the LICENSE file in the repository root. The repository also includes a SECURITY.md, a CONTRIBUTING.md, a pre-commit configuration and a gitleaks configuration for secret scanning.

## Sources

- [Issues](https://github.com/xai-org/xai-cookbook/issues)
- [README](https://github.com/xai-org/xai-cookbook/blob/main/README.md)
- [xai-org/xai-cookbook on GitHub](https://github.com/xai-org/xai-cookbook)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/xai-org-xai-cookbook