HEAD Queries

A HEAD query returns all active things and assertions at their current version. It’s the fastest way to orient yourself in a repository.

CLI

# All active items
wh thing head

# Filter by shape
wh thing head --shape Location

# Filter by kind (thing, assertion, shape)
wh thing head --kind assertion

# Limit results
wh thing head --limit 50

# Glob filter on wrefs (* = one segment, ** = zero or more)
wh thing head --match "Location/*"

# JSON output
wh thing head --json

Counting

Use --count to get just the number of matching items instead of the full result list:

# Count all active items
wh thing head --count

# Count by shape
wh thing head --shape Location --count

# Count assertions
wh assertion head --count
wh assertion head --shape Belief --count

--count cannot be combined with --limit, --cursor, --all, or --live.

For assertions specifically:

# Equivalent to: wh thing head --kind assertion
wh assertion head

# With shape filter
wh assertion head --shape Belief

MCP

{
  "name": "warmhub_thing_head",
  "arguments": {
    "shape": "Location",
    "kind": "thing",
    "match": "Location/dungeon/*",
    "limit": 100
  }
}

Count via MCP:

{
  "name": "warmhub_thing_head",
  "arguments": {
    "shape": "Location",
    "count": true
  }
}

All parameters are optional. Omit them to get everything.

HTTP API

GET /api/repos/myorg/myrepo/head
GET /api/repos/myorg/myrepo/head?shape=Location&kind=thing&limit=100
GET /api/repos/myorg/myrepo/head?match=Location%2Fdungeon%2F*&limit=50

Count via HTTP (separate endpoint):

GET /api/repos/myorg/myrepo/count?shape=Location&kind=thing

Count response:

{ "count": 42 }

Response

The response contains an items array. Each item includes:

Field	Description
name	Thing name
wref	Full wref (Shape/name)
shapeName	Shape name
kind	Entity kind (shape, thing, assertion)
version	Current version number
data	Current data payload
aboutWref	About target wref (assertions only)

Reactive Mode

Watch HEAD in real-time:

wh thing head --live

This opens a WebSocket connection and re-renders the display whenever data changes. On TTY terminals, the output refreshes in place. Combine with filters:

wh thing head --live --shape Location --kind thing

When to Use HEAD

HEAD queries are best for:

• Orientation — understanding what’s in a repo before targeted queries
• Monitoring — watching for changes with --live
• Broad snapshots — getting everything of a particular shape or kind

For targeted lookups, prefer filtering queries which accept more specific criteria.