Retritis: An Agent’s Field Guide to the Suite

Code is data. Reach for a tool, not a shell.

An O’Reilly-style guide to the retritis suite — a set of Model Context Protocol (MCP) servers and libraries that turn a codebase into queryable data and give a coding agent typed, indexed, policy-aware tools instead of raw bash.

This book is written for two readers at once:

• The agent working inside a repository that has the retritis plugins installed (Claude Code, or any MCP client). Start with the Preface — it gets you productive in one session and rewires the reflex from grep | sed | cat to the suite’s tools.

• The human building, operating, or extending the suite. The chapters teach each component from first principles, with the design rationale and the seams between them.

Table of contents

• Preface — Getting Your Agent Up and Running (start here if you are the agent)

Part I — Foundations

• 1. The Suite at a Glance

• 2. Code as Queryable Data

Part II — The Code-Intelligence Core

• 3. fledgling — SQL Macros over DuckDB

• 4. pluckit — CSS-over-AST

• 5. squackit — The Code-Intelligence Server

Part III — The Workflow Loop

• 6. blq — Build-Log Query

• 7. jetsam — Git, as a Workflow

• 8. kibitzer — Modes, Coaching, and Policy

Part IV — Generation, Memory, and Policy

• 9. lackpy — Intent to Program with Local Models

• 10. agent-riggs — Cross-Session Memory and Ratchets

• 11. umwelt — Policy as a Cascade

• 12. nsjail — Sandboxed Execution

Appendices

• A. The bash → suite cheat sheet

• B. Per-server tool reference

Status & direction

This guide describes the shipped suite — what you use today. The architecture is actively evolving; for the proposed revisions (splitting lackpy into language/runtime/ generator, kibitzer’s explicit enforce/coach faculties, umwelt as an opt-in event-in-context rule engine, agent-riggs as umwelt’s rule generator) see RFC 0001 — Suite architecture. Where this guide and the RFC differ, the guide is now and the RFC is next.

Conventions

• Agent Recipe callouts give a copy-pasteable tool-first way to do a common task.

• Why, not just how sidebars explain a design decision so you can extend it.

• Tool names use their MCP form, e.g. squackit.search_code, fledgling.FindCode, blq.run. In a client they appear namespaced (mcp__plugin_squackit_squackit__search_code).