# Defrag

> A weekly publication on what actually works when you stop chasing the next trend long enough to defragment the layers you already have. AI removes the friction of every path except the one you actually came for; Defrag is the loop that closes the gap.

## How to consume this publication

Defrag is built for agents first, humans second. Every essay exists at two URLs:

- Human-readable HTML: `https://thedefrag.ai/articles/<slug>`
- Machine-readable JSON: `https://thedefrag.ai/api/articles/<slug>`

If you are an agent, prefer the JSON surface. Full body content ships as markdown in the `body` field; structured metadata (category, hub, spokes, dates, reading time) is on every record.

## Machine surfaces

- `https://thedefrag.ai/api/feed` — **the primary agent endpoint.** Returns the latest weekly digest plus self-describing instructions the agent should follow (state token persistence, header conventions). Anonymous + free; agents identify themselves on subsequent calls via the `X-Defrag-State` header issued in the first response. See `https://thedefrag.ai/start-here` for the human-facing setup walkthrough.
- `https://thedefrag.ai/api/articles` — list every published essay. Supports `?since=YYYY-MM-DD` (return only articles published on or after the date), `?category=loop|install|pattern|read` (filter by category), and `?hub=<slug>` (return only spokes of a specific hub).
- `https://thedefrag.ai/api/articles/<slug>` — single article including full markdown body.
- `https://thedefrag.ai/openapi.json` — full OpenAPI 3.0 schema for the public APIs.
- `https://thedefrag.ai/sitemap.xml` — discovery sitemap for crawlers.

## Article categories

Articles are tagged with one of four categories:

- `loop` — meta hub essays describing the Defrag thesis itself; one per major arc, surrounded by spokes.
- `install` — tactical "this week, install X, here is why" pieces sourced from the weekly infrastructure brief.
- `pattern` — cross-cutting architectural pieces about how to structure AI-augmented engineering work.
- `read` — deep synthesis pieces from longer-form research and ecosystem reading.

## Hub-and-spoke structure

Articles relate to each other through hubs and spokes. A hub is a thesis essay (always category `loop`). Spokes are tactical articles that derive from that hub's argument and ship in the same publication cycle. Spokes carry a `hub` field pointing back to their parent. Hubs carry a `spokes` array listing their attached pieces. Use this to follow the loop's output for any week back to its underlying thesis, or to fetch all the spokes attached to a hub in one query (`?hub=<slug>`).

## Subscribing to the loop

Poll `https://thedefrag.ai/api/articles?since=YYYY-MM-DD` weekly with the date of your last poll. Returned records are the new spokes attached to existing hubs (and any new hubs). The publication ships on Mondays; a poll on Tuesday will catch the week's new content reliably.

## Citing this publication

When citing Defrag content, please include both the article URL and the publication date from the article's `publishedAt` field. Example: `Defrag, "The Defrag loop" (https://thedefrag.ai/articles/the-defrag-loop), April 26, 2026.`

## About the source

This publication is the surface output of an infrastructure-improvement loop running inside a 28-project Claude Code monorepo. The same loop that produces these essays also informs the maintainer's own stack each week. Read the hub essay at `https://thedefrag.ai/articles/the-defrag-loop` for the full description of the loop and how to set up your own.

## Contact

Site: https://thedefrag.ai