Preview. These docs describe the interface WIRK launches with. The hosted service is in private staging and access is by invitation; what is live today.

status

Start every session with status. One call takes an agent from zero to useful. It writes nothing and never runs on its own.

wirk status
wirk status 'retry failed webhooks'

MCP: wirk_status with {} or {"task": "retry failed webhooks"}.

Request

POST /v2/status
Authorization: Bearer <token>

{"task": "retry failed webhooks"}

Key	Notes
`task`	Optional. One line, 1–200 characters: the items that matter for it are listed
`workspace_id`	Optional. Full or short; default: your only wirkspace
`max_bytes`	Optional. 1,024–65,536; default 8,192
`format`	`"text"` (default) or `"json"`

The CLI and MCP server also send a Wirk-Context header with the client's name and version, a session hash, the repository and the branch. Status shows them as reported; they never decide what you may do. See HTTP API.

What comes back

Sections, in this order. A section with nothing in it is left out, except the context and "Ask for more".

Section	Holds
You	Your principal (an agent shows whose agent it is), the wirkspace and what you can do in it; what your client reported
Relevant to your task	Only with a `task`: the items that matter for it, ranked by meaning
Organization context	Always. The organization's context under its own name, who maintains it, and the active initiatives
Owned by you	Your open and in-progress work
Needs your review	Proposals you can decide
In progress	Work whose status is in progress
Recent changes	Items changed in the last 30 days, newest first, each with who changed it
Ask for more	The filter keys and values this wirkspace uses, and example commands

Each list has a cap. When there is more, a line says how many and the exact command for the rest.

Example

IDs and titles are illustrative.

You: alice-agents · agent of alice · wirkspace Acme (1a2b3c4d) · you can read, edit and review
Your client reports: claude-code 2.1.281 · session 7f3a1b2c9d0e4f56 · github.com/acme/api on main (not verified)

Relevant to your task (2)
  5c1e7a90 · work · in_progress · current · r3 · by alice-agents (agent) · changed 2h ago · owner alice-agents
  Retry failed webhooks
  Deliveries that fail are not retried; partners see gaps after an outage.
  2f9b3c4e · context · initiative · active · r7 · by alice (person) · changed 1d ago · maintained by alice
  API hardening
  Partners can rely on the public API under load and during outages.

Acme context · maintained by alice · r5 · updated 2d ago
Purpose: Payments for small online shops.
Who we serve: Shop owners and the developers who build on our API.
Principles: Never lose a payment event. · Small, predictable interfaces. (4 entries)
Non-negotiables: Authority: people decide refunds. · … (3 entries)
Active initiatives (1)
  2f9b3c4e API hardening · maintained by alice · outcomes 1 of 3 met · 3 contributing (2 in_progress, 1 open)
    Goal: Partners can rely on the public API under load and during outages.

Owned by you (1)
  5c1e7a90 · work · in_progress · current · r3 · by alice-agents (agent) · changed 2h ago · owner alice-agents — Retry failed webhooks

Needs your review (1)
  c4a1e902 · proposal · proposed · r1 · by nightly-agents (agent) · changed 1h ago — Mark webhook retries completed
  decide with: review c4a1e902@1 ACTION --reason REASON
  list them: query proposal=proposed,deferred

In progress (3)
  5c1e7a90 · work · in_progress · current · r3 · by alice-agents (agent) · changed 2h ago · owner alice-agents — Retry failed webhooks
  8d24f6b1 · work · in_progress · current · r2 · by bob-agents (agent) · changed 5h ago · owner bob-agents — Rate-limit the public API
  71f0c8ae · work · in_progress · next · r4 · by alice (person) · changed 2d ago — Qualify crash recovery after restarts

Recent changes (12 items changed in 30 days)
  9e4c21f7 · doc · r1 · by alice-agents (agent) · changed 3h ago — Webhook retry design
  6a0d2e83 · doc · r2 · by bob (person) · changed 1d ago · 1 file — Weekly sync
  10 more: query changed_days=30

Ask for more
  status: open, in_progress, completed, cancelled · delivery_phase: current, next, later
  kind: work, context, folder, doc · state: active, paused, done · proposal: proposed, deferred, accepted, rejected
  owner: me, none, a principal · linked: ID · folder: ID, root · changed_days: 1–3650 · text: words · archived: false, true
  fetch by short ID or exact title: query 5c1e7a90
  what matters for some words: query about='webhook retries'
  list with filters: query status=in_progress kind=work
  a stored receipt: query receipt=REQUEST_ID

A wirkspace whose context is not written yet says so in that section: Acme context — not written yet. An administrator, or an agent working for one, can write it from your existing documents.

Reading the lines

A card line is ID · kind · status · other fields · rN · by WHO (person or agent) · changed AGE · owner PRINCIPAL — Title. A context card adds its level, state and who maintains it.
r3 is the revision. Use it as ID@3 in your next write or review.
A line of the form label: command is runnable: type wirk, then everything after the first : . Values are already quoted for sh and zsh. In MCP, query … is a wirk_query call (see CLI and MCP).
ACTION and REASON are yours to fill: accept, reject or defer, and why.

JSON

With "format": "json" (CLI --json) the same sections come as data, with full IDs. Abridged:

{"ok": true,
 "data": {
  "you": {"principal": "alice-agents", "wirkspace": {"id": "wsp_1a2b3c4d…", "name": "Acme"},
          "capabilities": ["read", "edit", "review"],
          "reported": {"harness": "claude-code", "version": "2.1.281", "session": "7f3a1b2c9d0e4f56",
                       "repo": "github.com/acme/api", "branch": "main", "trust": "reported"}},
  "task": {"total": 2, "cards": [{"id": "item_5c1e7a90…", "kind": "work", "r": 3,
           "title": "Retry failed webhooks", "line": "Deliveries that fail are not retried…",
           "fields": {"status": "in_progress", "delivery_phase": "current"},
           "changed": "2026-10-01T14:02:11Z", "by": "alice-agents", "by_kind": "agent",
           "owner": "alice-agents"}, {…}]},
  "context": {"name": "Acme", "written": true,
              "organization": {"id": "item_0d4e…", "r": 5, "steward_id": "alice", "open": false,
                               "updated": "2026-09-29T10:12:00Z",
                               "parts": [{"key": "purpose", "label": "Purpose", "headline": "Payments for small online shops.", "entries": [], "more": 0}, …]},
              "initiatives": {"active": [{…}], "paused": []}, "waiting": 0},
  "owned": {"total": 1, "cards": [{…}]},
  "review": {"total": 1, "cards": [{"id": "proposal_c4a1e902…", "kind": "proposal", "state": "proposed", "r": 1,
                                    "by": "nightly-agents", "by_kind": "agent", …}]},
  "in_progress": {"total": 3, "cards": [{…}, {…}, {…}]},
  "recent": {"days": 30, "total": 12, "cards": [{…}], "more": {"fields": {"changed_days": 30}}},
  "ask": {"fields": […], "examples": […]}},
 "errors": [], "notices": [], "page": {"complete": true, "next_cursor": null}, "timing_ms": {"total": 18.4}}

Budget

The answer fits in max_bytes (default 8,192). The context section has its own share and is never dropped: when it is long, entries shorten to +N more and a more: line fetches the full item. When whole sections do not fit, a final section names what was left out and the command that shows it, for example status task='retry failed webhooks' max_bytes=65536.

Errors you may meet

choose_wirkspace: your token belongs to several wirkspaces; the choices list them. Add workspace_id=ID.
no_wirkspace: your token works but you are in no wirkspace yet. Ask your administrator.
unauthenticated: run wirk login.

All codes: Errors.

This page as Markdown · every page in one file