Crystal for Agents: v1.21.0 Update, 27 Advanced Recipes & Automated Code Verification

News
1

Hey everyone,

A while back, I shared Crystal for Agents here; my reference project aimed at keeping LLMs from hallucinating outdated patterns, stale threading APIs, or Rubyisms when working with Crystal.

I recently finished updating it for Crystal v1.21.0, auditing semantics against the compiler source and standard library, and adding a dedicated chapter of practical patterns/recipes.

Here is a summary of what was updated:

1. Crystal v1.21.0 Semantic Audit

The 21 reference sections were cross-checked against Crystal v1.21.0 compiler internals and stdlib:

  • Type Hierarchy & Semantics: Explicit heap vs. value allocations, reference semantics (String and Array inheriting from Reference), and strict nil safety.
  • Concurrency: Modern Execution Contexts, fiber scheduler behavior, Channel(T) mechanics, and modern Sync primitives (Sync::Mutex, Sync::RWLock, Sync::ConditionVariable, Sync::Exclusive(T)).
  • Inheritance vs. Reopening: Explicit distinction between subclassing (super) and reopening types (previous_def), eliminating hallucinated keywords like override.
  • Tooling & Standards: Modern Time.instant APIs, Ameba and Flaw integration, spec guidelines, and E2E testing with selenium.cr/webdrivers.cr.

2. Chapter 20: Advanced Recipes

Added a collection of 27 tested recipes covering common concurrency, metaprogramming, and performance patterns:

  • Fiber Concurrency & Channels: Channel-ring resource pooling, non-blocking channel polling using select ... else, concurrent piped process I/O (handling >64KB output without pipe buffer deadlocks), and atomic mutations with Sync::Exclusive#replace.
  • Metaprogramming: Deferred AST ivar reflection via {% verbatim do %}, compile-time annotation registries using nested macro finished, and zero-allocation dynamic dispatch with Tuple indexing.
  • Low-Level & OS: Stack buffers via StaticArray, zero-copy socket transfers with Socket#sendfile, and target-specific vectorization with @[TargetFeature].
  • Peak Performance & Micro-Binaries: Host-tuned optimization pipelines with --mcpu=native, --release, --no-debug, and linker stripping (-z relro -z now -s).

3. Automated Code Snippet Verification

To make sure documentation examples don’t bitrot or break, scripts/verify_code_examples.cr extracts every code block across all 21 RST chapters, formats it with crystal tool format, and checks compilation with crystal build --no-codegen:

  • 218 code blocks checked: 0 format errors, 0 compilation failures.
  • RST linting with rstcheck across all sections.
  • Builds into a single PDF book via Pandoc and XeLaTeX (make all).

4. Portable Agent Skill & LLM Benchmark

  • Gemini/Antigravity Skill: Updated the agent skill package (agents/gemini/crystal/) with reference cheat-sheets, 27 superpower recipes, and antipattern rules.
  • LLM Benchmark (scripts/llm_benchmark.bash): A test harness to compare baseline model output against documentation-guided prompts to check compliance with modern Crystal concurrency and memory safety.

The repository is hosted on GitLab (it uses the Git SHA-256 object format, which GitHub currently doesn’t support):

If you’re experimenting with LLMs for Crystal development or just want a quick reference for these patterns, feel free to check it out. Feedback, corrections, and additional recipe ideas are always welcome.

1 Like