ActUpon Docs

Agent inbox workflow

ActUpon can act as a capture inbox for local coding agents. Save the item once, add structured tags like codex or cursor, then let a local tool pull the latest matching capture and save it to disk.

Tag convention

Use one of these structured tags on the saved item:

codex
codex:thecrux
cursor
cursor:android

Tags are the canonical routing field. The hosted item editor stores them separately from the freeform note so agents can match exact tags without parsing human text.

Typing @codex or @cursor in the note is only a convenience input. The UI should promote that input into the structured tag list before save rather than relying on the note text as the primary routing contract.

Matching rules

Structured tags are the primary routing signal for local agent pullers.
Lane-specific tags like codex:thecrux win over generic codex.
Freeform notes are for human context, not routing.
Legacy note-marker parsing remains a temporary compatibility fallback, not the preferred steady-state model.

Example 1: Fetch tagged items

Fetch ActUpon items from saved history, filtering by exact tags such as codex or cursor:android.

export SCREENSHOTACTION_BASE_URL=https://actupon.app
export SCREENSHOTACTION_TOKEN=<your_token>

npm run screenshotaction -- list --json --tags=codex --limit=1

Example 2: Claim and complete workflow items

Claim an available ActUpon item from the workflow inbox, process it, and mark it done.

export SCREENSHOTACTION_BASE_URL=https://actupon.app
export SCREENSHOTACTION_TOKEN=<your_token>

npm run screenshotaction -- inbox --json --claim-status=available
npm run screenshotaction -- claim <item-id>
npm run screenshotaction -- done <item-id> --note="Addressed in PR 12345"