Agent Context (wh prime)

wh prime prints a compact CLI context dump built for AI agents. It’s meant to be the first command an agent runs at the start of a session, so the agent knows WarmHub’s concepts, wref syntax, and command surface before it does any work.

When to Use

• Session start — give the agent full CLI context before it begins work.
• After compaction — restore context that was dropped when the conversation history was compressed.
• New agent — bootstrap a fresh agent with everything it needs to operate.

How Agents Run It

wh prime is a normal CLI command, so any harness with shell access can run it. The goal is to feed its output into the agent’s context once, early.

Claude Code

Claude Code can run wh prime automatically with a SessionStart hook, so every new session begins with WarmHub context loaded. Pair it with a PreCompact hook to re-run wh prime and restore context after the conversation is compacted:

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "wh prime" }] }],
    "PreCompact":  [{ "hooks": [{ "type": "command", "command": "wh prime" }] }]
  }
}

Other harnesses

Any agent harness with shell access can run wh prime and include the output in its system prompt or first message. Two common patterns:

• System prompt — run wh prime once at startup and prepend the output to the agent’s system prompt.
• First turn — let the agent call wh prime as its first tool use, then continue with the result in context.

Use --json (below) when your harness ingests structured context rather than prose.

No shell? Use the MCP or SDK surface

Agents that can’t run a shell don’t use wh prime directly. The MCP equivalent is warmhub_capabilities, which returns the same kind of orientation (concepts, workflows, wref syntax, and a pointer to the write contract — call warmhub_repo_describe for the full contract and shape-specific examples). SDK callers don’t get a prose context dump — client.diagnostics.capabilities() returns version and feature-flag information for compatibility checks, not orientation prose; SDK agents read these docs instead. See the MCP Tools Reference for the MCP bootstrapping tool.

Usage

# Markdown output (human-readable)
wh prime

# Structured JSON output
wh prime --json

Flags

wh prime takes no command-specific flags. It accepts the standard global flags, of which two affect the output:

Flag	Effect on wh prime
--json	Emit structured JSON instead of Markdown (alias for --format json).
--format pretty|json|jsonl	Choose the output format.

wh prime emits the same CLI bootstrap context regardless of --repo or --profile — it describes the CLI itself, not a specific repo’s data. The Environment section reflects your configured default repo (from WARMHUB_REPO or wh use org/repo), and shows No default repo when none is set.

Markdown Output

The default output includes:

• Environment — your default repo, if one is configured.
• Core concepts — thing, assertion, shape, write, and wref definitions.
• Versioned things — logical thing vs pinned version (Shape/name vs Shape/name@vN).
• Wref quick reference — local and canonical forms, version modifiers, batch tokens.
• Key workflows — read, write, and query command patterns.

Example excerpt:

## Core Concepts
- **Thing**: A named entity versioned by write operations. **Assertion**: A claim about a thing with shape-validated data.
- **Shape**: Schema defining data structure. **Write**: One or more add/revise/retract operations with per-operation results.
- **wref**: Reference as `Shape/name` (e.g., `Player/alice`). Cross-repo: `wh:org/repo/Shape/name`.

## Versioned Things
- `Shape/name` identifies the logical thing. `Shape/name@vN` pins an exact version.

JSON Output

wh prime --json returns the same context as a structured object — each domain lists its verbs with args, flags, aliases, and status, so a harness can parse the command surface directly:

{
  "version": "0.2.0",
  "defaultOrg": null,
  "defaultRepo": null,
  "wrefSyntax": {
    "localExamples": ["GameState", "GameState@v3", "Player/alice", "GameState/round-1/state"],
    "canonicalFormat": "wh:org/repo/Shape/name",
    "versionModifiers": ["@HEAD", "@vN", "@ALL"],
    "batchTokens": { "allocate": "$N", "reference": "#N" }
  },
  "domains": [
    {
      "domain": "auth",
      "summary": "Authentication management",
      "verbs": [
        { "name": "login", "summary": "Log in via browser or --with-token for PATs", "args": "", "flags": ["--with-token", "--profile"], "status": "live" }
      ]
    }
  ]
}

Token Budget

The JSON output is approximately 4,800 tokens (about 19 KB); the Markdown output is a bit smaller, around 3,500 tokens (about 14 KB). Either way it leaves most of an agent’s context window free for reasoning and conversation. Measure the current size yourself with wh prime --json | wc -c and divide by ~4 for a rough token count before you budget for it.

Best Practice

Agents should run wh prime (CLI) or warmhub_capabilities (MCP) as their first action, then use targeted commands and tools for specific work. Loading context once up front avoids guessing at concepts or syntax and gives the agent accurate command contracts from the start.