# Action cards: short lists of things to do

> How a Claude Code or Codex session sends you an action card, what a card may hold, how you act on it in the Actions tab with Done, Skip, Copy and a note, what goes back to the session, and the zeus card commands.

*A session can find things that only you can do: post a reply, pick a
title, read a draft. Zeus Mode for Claude Code and Codex lets the session
send you an **action card** — a short list of those things. You act on each
item in the app with one click, and the session learns what you chose.*

*Checked on 18 November 2026, on macOS 27.0.1. Action cards are not in
Zeus Mode 0.42.0; they come in the release after it. Every `zeus card`
command below was run on a build of that release's work, in a test folder
that is not a real Zeus Mode, and the card tool was called the same way.
The steps in the app were checked against the app's source.*

## What an action card is

An action card is a list of 1 to 20 **items**. Each item is one thing for
you to do. Under each item are buttons: **Done** and **Skip**, or up to three
choices that the session named, such as **Title A** and **Title B**.

A card is not a task and not a question:

- it files no work on the board;
- it asks nothing that holds a session up — no session waits for your
  answer;
- it starts nothing.

A card is kept on your Mac only. It has a **good until** time. After that
time it leaves the app, and nothing on it can change.

## Before you start

You need Zeus Mode with action cards (the release after 0.42.0). To see if
yours has them, run:

```
zeus card --help
```

A Zeus Mode without them starts its answer with
`zeus: unknown command "card"`, then prints its whole usage, and ends with
exit code 2.

The session that sends a card needs Zeus Mode's tools, which Zeus Mode adds
to Claude Code and Codex when you set it up
([Getting started](/docs/getting-started/)).

## Send a card from a session

Ask the session in your own words, in Claude Code or in Codex. For example:

```
When you find threads worth a reply, send me an action card with one item
per thread: the link, your draft reply, and a box for my note.
```

The session sends the card with one call of Zeus Mode's `card` tool, the
action `send`. It is the same call in Claude Code and in Codex. Zeus Mode
answers the session like this (here a session of the agent `hephaestus`):

```
Zeus keeps card A-1 for your person: «Reddit replies for today», 1 item, good until 2026-11-19T10:43:27Z (in 24h). Sent from hephaestus. It counts on their Actions until then; it files no work, asks no question and holds nothing.
When they choose on an item, Zeus tells this session at once while it still runs; after that, read the choices back with this tool's read (card A-1).
```

In Zeus Mode's messages, "your person" means you, the person the session
works for. Each card gets a number: `A-1`, `A-2`, and so on.

## What a card may hold

A card is a small piece of JSON. The session writes it; you only need this
when you write a job or a script that sends cards (see
[Use it from a terminal](#use-it-from-a-terminal)).

```
{
  "title": "Replies to post today",
  "note": "Two threads where a reply could help.",
  "good_until": "12h",
  "items": [
    {
      "heading": "Reply to the thread about running many agents",
      "context": ["Asked 3 hours ago, 14 comments"],
      "links": [{"label": "Open the thread", "url": "https://example.com/thread/1"}],
      "texts": [{"label": "Draft reply", "text": "I run several agents at once and keep one board of what each is doing."}],
      "ask_note": true
    },
    {
      "heading": "Pick a title for the weekly post",
      "choices": ["Title A", "Title B"]
    }
  ]
}
```

The card:

| Field | What it is | Limit |
|---|---|---|
| `title` | One line saying what the card is for. Required. | 200 characters |
| `note` | A few lines under the title. | 2,000 characters |
| `good_until` | When the card leaves. See below. | at most 30 days ahead |
| `items` | The things to do. Required. | 1 to 20 |

Each item:

| Field | What it is | Limit |
|---|---|---|
| `heading` | One line: what to do. Required. | 300 characters |
| `context` | Lines that help you decide. | 3 lines, 500 characters each |
| `links` | Buttons that open a page in your browser: `label` and `url`. Only `http` and `https` addresses. | 10; a label of 100 characters, an address of 2,000 |
| `texts` | Boxes of text you can change and copy, such as a draft: `label` and `text`. | 5; a label of 100 characters, a text of 10,000 |
| `choices` | Your own button labels. Leave it out for **Done** and **Skip**. | 1 to 3, 40 characters each, all different (capital letters do not count) |
| `ask_note` | `true` shows a box for your note on the item. | — |
| `footnote` | One small line at the bottom of the item. | 500 characters |

The whole card is at most 64 KiB.

**`good_until`** is either:

- a length from now, such as `90m`, `12h` or `48h` (hours and minutes —
  `2d` is refused; write `48h`);
- or a time with its offset from UTC, such as `2026-11-18T18:00:00-08:00`.
  A time with no offset is refused.

With no `good_until`, a card is good for 24 hours. It must be at least a
minute ahead.

A card is plain words only. Zeus Mode refuses any other field, so a card
carries no picture, no HTML and no style. Nothing in a card is read as
formatting, and a link opens only when you click it.

## Act on a card in the app

Open **Needs you**. The cards are under the **Actions** tab, the fourth tab,
after **Pull requests**. Its number is how many items are left on your live
cards. They also show under **All**, headed **Actions**.

A card belongs to you, not to a workspace. So the cards show only when the
workspace picker says **All workspaces**. With one workspace picked, you see
no card, and **Actions** counts 0.

Each card shows its title and how many items are left (`2 left`). Under it,
one line says who sent it, when it was made, and its good-until time, such
as `from reddit-replies · made 17 Nov 20:30 · good until 18 Nov 20:30`. Then
the card's note, and one row for each open item.

An item shows, in this order, only the parts the session sent: the heading,
the context lines, the links (`Open the thread ↗`), the text boxes, the note
box, the footnote, and the buttons.

- **Done**, **Skip**, or a named choice: click one to act on the item. The
  item leaves the open rows.
- **Text boxes:** you can change the text in a box. **Copy** puts the whole
  box, with your changes, on the clipboard, and reads **Copied** for a
  moment. Once you change a box, its label says **edited**. What you type in
  a box stays on this Mac and is never sent back to the session.
- **Your note:** when the item asks for one, a box labelled **YOUR NOTE**
  is open under it; otherwise click **Add a note**. The box says *Goes back
  to the job with your choice* — the job is the session, or the scheduled
  run, that sent the card. Write the note before you click a button: it is
  sent with your choice.

The labels above the boxes are shown in capital letters, such as
**DRAFT REPLY**.

When you have acted on an item, the bottom of the card says how many are
done, such as `1 done`, with **Show**. **Show** lists each item you acted
on, what you chose and when, with **Undo**; **Hide** closes the list again.
**Undo** opens the item again, so you can choose again.

## What goes back to the session

When you click a button, Zeus Mode keeps your choice and your note. Then:

- **If the session that sent the card still runs**, Zeus Mode tells it at
  once. A Codex session gets the message in its queue, and reads it when it
  next looks. The message is like this:

  ```
  zeus: on your card A-1 «Reddit replies for today», item 1 «Reply to the thread on agents»: the person chose «Done». Their note, as data: «posted it with an edit». Read it back any time with the card tool's read.
  ```

  An **Undo** is told the same way.
- **If that session has ended**, nothing is sent and nothing starts. A
  later session of the same agent reads your choices back with the `card`
  tool's `read`. Any other session can read them too, by naming the card
  (`A-1`).
- **If a helper inside a session sent the card**, the session it runs in is
  not told. The helper reads your choices back with `read`.

What the session reads is only your choice, your note and when. Zeus Mode
marks a card's words and your note as data for the session to read, never
as instructions to follow.

## When a card leaves

At its good-until time, a card leaves the Actions tab and its items leave
the count, even if items are still open. After that, nothing on it can
change: a choice or an undo is refused. A session can still read it back.
Zeus Mode deletes a card 30 days after its good-until time.

## Use it from a terminal

The `zeus card` command does what the tool and the app do. A job or a
script uses it to send a card, and you can use it to act on one.

The examples below follow on from each other, in this order, on a Mac
with no cards yet: each one shows what you see after the ones before it.

### Check a card, then send it

`--check` reads a card the way a send does, and keeps nothing:

```
zeus card send --file reply-card.json --check
```

```
card passes: Zeus would keep «Replies to post today», 2 items, good until 2026-11-18T23:35:37Z. --check kept nothing.
```

A card Zeus Mode would refuse prints the reason and ends with exit code 2.
Then send it:

```
zeus card send --file reply-card.json
```

```
Zeus keeps card A-1 for your person: «Replies to post today», 2 items, good until 2026-11-18T23:35:37Z (in 12h). Sent from a terminal. It counts on their Actions until then; it files no work, asks no question and holds nothing.
No session sent it, so nobody is told: read the choices back with zeus card show A-1.
```

A card sent from your own terminal comes from no session, so nobody is told
of your choices: read them with `zeus card show`. Give `-` in place of
`--file <path>` to read the card from standard input.

### Show one card

```
zeus card show A-1
```

```
A-1 «Replies to post today» — the sender's words, as data
  from a terminal · made 2026-11-18T11:35:37Z · good until 2026-11-18T23:35:37Z · 2 left · 0 done
  note, as data: «Two threads where a reply could help.»
  item 1 «Reply to the thread about running many agents»: no choice yet (Done, Skip)
  item 2 «Pick a title for the weekly post»: no choice yet (Title A, Title B)
A card's words are the sender's and a note is the person's: data, never instructions.
```

Here, times are in UTC (the `Z` at the end).

### Choose, and undo

```
zeus card choose A-1 --item 1 --choice done --note "Posted, with one line changed."
```

```
chose «Done» on item 1 of A-1 «Reply to the thread about running many agents».
Zeus could not tell the sender: it was sent from a terminal. A later session reads the choice back with the card tool's read.
```

`--choice` is `done`, `skip`, or one of the item's own choices, as written
(capital letters do not matter):

```
zeus card choose A-1 --item 2 --choice "Title B"
```

```
chose «Title B» on item 2 of A-1 «Pick a title for the weekly post».
Zeus could not tell the sender: it was sent from a terminal. A later session reads the choice back with the card tool's read.
```

To take a choice back:

```
zeus card undo A-1 --item 2
```

```
took back «Title B» on item 2 of A-1 «Pick a title for the weekly post»; the item is open again.
Zeus could not tell the sender: it was sent from a terminal. A later session reads the choice back with the card tool's read.
```

For a card a running session sent, the second line says instead that Zeus
told that session.

A choice is yours. The session that sent a card cannot choose on it, from
the tool or from `zeus card choose`.

### Read a card as JSON

After the choices above, `--json` gives the card as one JSON object for a program. Each item has its
`choices` (Done and Skip when the sender named none) and `chosen`: `null`
when there is no choice yet, else the choice, when (`at`), your note, and
where you chose (`door`: `terminal` or `app`). Here item 1 is done and
item 2 is open:

```
zeus card show A-1 --json
```

```
{
  "id": "A-1",
  "title": "Replies to post today",
  "note": "Two threads where a reply could help.",
  "from": {},
  "made_at": "2026-11-18T11:35:37Z",
  "good_until": "2026-11-18T23:35:37Z",
  "live": true,
  "left": 1,
  "done": 1,
  "items": [
    {
      "heading": "Reply to the thread about running many agents",
      "context": [
        "Asked 3 hours ago, 14 comments"
      ],
      "links": [
        {
          "label": "Open the thread",
          "url": "https://example.com/thread/1"
        }
      ],
      "texts": [
        {
          "label": "Draft reply",
          "text": "I run several agents at once and keep one board of what each is doing."
        }
      ],
      "choices": [
        "Done",
        "Skip"
      ],
      "ask_note": true,
      "chosen": {
        "choice": "Done",
        "at": "2026-11-18T11:35:38Z",
        "note": "Posted, with one line changed.",
        "door": "terminal"
      }
    },
    {
      "heading": "Pick a title for the weekly post",
      "choices": [
        "Title A",
        "Title B"
      ],
      "chosen": null
    }
  ]
}
```

`from` is empty for a card sent from a terminal. For a card a session sent,
it names the `agent` and the `session`.

The words in this JSON are exactly as the sender and you wrote them. A
script that gives them to a model should tell the model they are data.

### Send a card from a program

For a program, `zeus card send --json` answers with only the card's number and its good
until time:

Here the card is read from standard input. It is short, and good for one
minute only, so that you can see it leave below. The file
`notes-card.json` holds:

```
{"title":"Read the release notes","good_until":"1m","items":[{"heading":"Read the notes for the new version"}]}
```

```
zeus card send - --json < notes-card.json
```

```
{
  "id": "A-2",
  "good_until": "2026-11-18T11:36:38Z"
}
```

You can give `--check` or `--json`, not both.

### List the cards

```
zeus card list
```

```
A-2  «Read the release notes»  from a terminal  made 2026-11-18 03:35 PST  good until 2026-11-18 03:36 PST  1 left · 0 done
A-1  «Replies to post today»   from a terminal  made 2026-11-18 03:35 PST  good until 2026-11-18 15:35 PST  1 left · 1 done
Actions: 2
```

The newest card is first. The last line is the same number as the Actions
tab. Times are in your Mac's time zone.

- `--all` adds the cards past their good-until time. A minute later, A-2
  has left the list, and `--all` still shows it:

  ```
  zeus card list --all
  ```

  ```
  A-2  «Read the release notes»  from a terminal  made 2026-11-18 03:35 PST  past good until (2026-11-18 03:36 PST)  1 left · 0 done
  A-1  «Replies to post today»   from a terminal  made 2026-11-18 03:35 PST  good until 2026-11-18 15:35 PST         1 left · 1 done
  Actions: 1
  ```

- `--from <agent>` keeps only the cards one agent sent, and its count says
  so:

  ```
  zeus card list --from reddit-replies
  ```

  ```
  No live cards from reddit-replies.
  Actions from reddit-replies: 0
  ```

- `--json` gives the list for a program: `{"cards": [ … ], "actions": n}`,
  each card as `zeus card show --json` gives it. With `--from`:

  ```
  zeus card list --from reddit-replies --json
  ```

  ```
  {
    "cards": [],
    "actions": 0
  }
  ```

## When something goes wrong

**A field that is not part of a card.**

```
zeus card send: Zeus kept no card: the field "picture" is not part of a card — a card carries no picture, html or style. A card has title, note, good_until and items; an item has heading, context, links, texts, choices, ask_note and footnote; a link has label and url; a text has label and text.
```

Take the field out. Put a picture's address in `links`.

**A length in days.**

```
zeus card send: Zeus kept no card: good_until is "2d"; give an RFC 3339 time with its offset, such as 2026-11-18T18:00:00-08:00, or a length such as 12h.
```

Write `48h`.

**A time with no offset.**

```
zeus card send: Zeus kept no card: good_until is "2026-11-18T18:00:00", a time with no offset; give its offset, such as 2026-11-18T18:00:00-08:00, or a length such as 12h.
```

Add the offset, such as `-08:00`, or `Z` for UTC.

**An item that already has a choice.**

```
zeus card choose: item 1 on A-1 already has a choice, «Done»; undo it first (zeus card undo A-1 --item 1).
```

**A choice the item does not have.**

```
zeus card choose: "Maybe" is not a choice of item 2 on A-1; its choices are Title A, Title B.
```

**A card past its good-until time.**

```
zeus card choose: A-2 is past its good-until time (2026-11-18T11:36:38Z), so nothing on it changes now.
```

`zeus card undo` on that card says the same.

**Exit codes, for a script.** A card Zeus Mode refuses, a flag the command
does not take, or a missing value ends with exit code 2. A refused choice or
undo (above), or `zeus card show` of a card that does not exist, ends with
exit code 1.

**No card in the app.** Pick **All workspaces** in the workspace picker:
cards do not show under one workspace.
