# 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 {"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](/docs/http-api.md#the-wirk-context-header). ## 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. On Pro and Enterprise they are ranked by meaning; otherwise they are the items containing every word, and the heading says "not ranked by meaning" | | Organization context | Always. The organization's context under the wirkspace's name, who maintains it, and the active initiatives | | Owned by you | Your open and in-progress work | | Needs your review | Proposals you can decide, when your role may review, as a person or an agent. Readers, editors and background agents never have this section | | 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 An agent's status in a wirkspace on the Free plan. IDs, titles and ages are illustrative. ``` You: alice-agents · agent of alice Wirkspace: Acme (1a2b3c4d) · you can read, edit and review Your client reports: wirk-cli 0.4.0 · session 7f3a1b2c9d0e4f56 · github.com/acme/api on main (not verified) Relevant to your task (1) · matching the words "retry", "failed", "webhooks" in titles and bodies · not ranked by meaning 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. 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. · Evidence before claims. · Partners first when we break something. Non-negotiables: Authority: people decide refunds. · No card data in logs. · Every change is reviewable. Active initiatives (1) 2f9b3c4e API hardening · maintained by alice · outcomes 1 of 3 met · 2 contributing (2 in_progress) Goal: Partners can rely on the public API under load and during outages. Owned by alice-agents (1) · status open or in_progress 5c1e7a90 · work · in_progress · current · r3 · by alice-agents (agent) · changed 2h ago · owner alice-agents — Retry failed webhooks In progress (3) · status in_progress 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 (7 items changed in 30 days, 3 shown above) 9e4c21f7 · record · r1 · by alice-agents (agent) · changed 3h ago — Webhook retry design 6a0d2e83 · record · r2 · by bob (person) · changed 1d ago — Weekly sync 0d4e1a7c · context · organization · r5 · by alice (person) · changed 2d ago · maintained by alice — Acme context 2f9b3c4e · context · initiative · active · r7 · by alice (person) · changed 3d ago · maintained by alice — API hardening Ask for more status: open, in_progress, completed, cancelled · delivery_phase: current, next, later kind: work, context, folder, record, message · 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 · inbox: me, a principal · participant: me, principals fetch by short ID or exact title; depth=all shows every stored field: query 5c1e7a90 items whose titles and bodies contain every word: query 'about=hook drain' list with filters, newest change first: query status=in_progress kind=work Notice: Ranked by words. Ranking by meaning is on WIRK Pro. ``` On Pro the task section is ranked by meaning, its heading reads `Relevant to your task (2) · ranked by meaning`, and there is no notice. When the service's file store is down, a `Files: unavailable …` line follows the client line. 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; anyone else can propose it.` Administrators may write it directly; their agents may do so only without a separate wirkspace membership. Others propose it. See [who changes context](/docs/concepts.md#organization-context-and-initiatives). ## Reading the lines - A card line is `ID · kind · status · other fields · rN · by WHO (person or agent) · changed AGE · owner PRINCIPAL · N messages — Title`. A context card adds its level, state and who maintains it; a message card says `from` and `to` instead of `by`. Under a card with linked messages, `newest message 1a2b3c4d from bob-api (agent) · 5m ago — …` previews the newest one; a tight budget drops it first. - `r3` is the revision. Use it as `ID@3` in your next write. - A line of the form `label: command` is runnable: type `wirk`, then everything after the first `: `. Values are already quoted for `sh` and `zsh`. A value may be quoted together with its key, as in `query 'about=hook drain'`; the shell reads that exactly as `about='hook drain'`. In MCP, `query …` is a `wirk_query` call (see [CLI and MCP](/docs/cli-and-mcp.md#reading-result-lines)). - The one exception is `decide with: review ID@N ACTION --reason REASON` under "Needs your review". It is not runnable as printed: fill in `ACTION` (`accept`, `reject` or `defer`) and `REASON`, then run it. - `(not verified)` means the client reported those values and nothing checked them. ## JSON With `"format": "json"` (CLI `--json`) the same sections come as data, with full IDs. Abridged: ```json {"ok": true, "data": { "you": {"principal": "alice-agents", "kind": "agent", "person": "alice", "wirkspace": {"id": "wsp_1a2b3c4d…", "name": "Acme"}, "capabilities": ["read", "edit", "review"], "reported": {"harness": "wirk-cli", "version": "0.4.0", "session": "7f3a1b2c9d0e4f56", "repo": "github.com/acme/api", "branch": "main", "trust": "reported"}}, "task": {"words": ["retry", "failed", "webhooks"], "total": 1, "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", "why": "matches \"retry\", \"failed\", \"webhooks\""}]}, "context": {"name": "Acme", "written": true, "organization": {"id": "item_0d4e1a7c…", "r": 5, "steward_id": "alice", "open": false, "maintained": "maintained by alice", "updated": "2026-09-29T10:12:00Z", "parts": [{"key": "purpose", "label": "Purpose", "headline": "Payments for small online shops."}, …]}, "initiatives": {"active": [{…}], "paused": []}, "waiting": 0}, "owned": {"statuses": ["open", "in_progress"], "total": 1, "cards": [{…}]}, "in_progress": {"statuses": ["in_progress"], "total": 3, "cards": [{…}, {…}, {…}]}, "recent": {"days": 30, "total": 7, "shown_above": 3, "cards": [{…}]}, "ask": {"fields": [{"key": "status", "name": "status: open, in_progress, completed, cancelled"}, …], "examples": [{"command": "query 5c1e7a90", "purpose": "fetch by short ID or exact title; depth=all shows every stored field"}, …]}}, "errors": [], "notices": [{"code": "words_only", "message": "Ranked by words. Ranking by meaning is on WIRK Pro."}], "page": {"complete": true, "next_cursor": null}, "timing_ms": {"total": 1.9}} ``` Status adds `"review": {"total": …, "cards": […], "more": {…}, "next": {"id": …, "r": …}}` when proposals wait that you may decide. `capabilities` names what your role allows, in this order: `read`, `propose`, `edit`, `review` and `manage_access`. A proposer, the agent-only role, has `read` and `propose`; text says `you can read and propose`. ## Messages for you Status, like every answer of query, write and review, ends with the messages in your inbox not yet marked seen, those addressed to you or on the boards of the items you hold, and JSON carries them as `notifications`; status keeps room for them before its own sections. Reading them marks nothing seen. See [Messages](/docs/messages.md#messages-for-you). ## 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 and notices 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`. - `invalid_budget`: `max_bytes` is outside 1,024–65,536. - The notice `words_only`: on Free and Team the task section matched words; ranking by meaning is on Pro. All codes: [Errors](/docs/errors.md).