X Mention Triggers

Use X mentions to create CoWork OS tasks from allowlisted accounts with a configurable command prefix (default: do:).

What Ships

• Bridge mode: Bird CLI mention poller that creates tasks via shared hook ingress.
• Native mode: First-class x gateway channel adapter with mention ingestion and optional outbound posting.
• Idempotency: Every mention uses sessionKey = xmention:<tweetId> so duplicate polls/restarts do not create duplicate tasks.
• Safe default: No automatic X posting unless outbound is explicitly enabled on the native x channel.

Desktop Setup

1. Open Settings > X.
2. Enable X integration.
3. Enable Mention Trigger.
4. Set:
   • Command Prefix (for example do:)
   • Allowed Authors (comma-separated handles, required)
   • Poll Interval and Fetch Count
5. Save and use Test Connection.
6. Watch runtime state in Mention Trigger Runtime:
   • mode (bridge / native / disabled)
   • running
   • last poll/success/error
   • accepted/ignored counters
   • last task id

Headless Setup

• Configure X settings in secure settings storage (same schema as desktop).
• Ensure Bird CLI is installed and authenticated in the daemon environment.
• Start coworkd or headless app mode.
• Mention trigger lifecycle starts after gateway/daemon initialization and stops on shutdown.

Trigger Format

• Prefix match is case-insensitive.
• Prefix is customizable by the user.
• Mention is accepted only when:
  • author is allowlisted
  • prefix exists in the mention text
  • non-empty command exists after prefix

Example:

• Tweet: @YourAgent do: summarize this thread and draft a launch plan
• Result: one task created in a temporary workspace from the extracted command payload.

Native vs Bridge

• Bridge mode and native mode share the same parser + ingress semantics.
• When native x channel is enabled, bridge mode automatically pauses to avoid double ingest.
• Both paths emit comparable runtime telemetry and use the same idempotent sessionKey.

Security Notes

• Allowlist required: Mention trigger should only run with explicit allowed handles.
• Credential handling:
  • Browser cookie extraction or manual auth_token + ct0 are stored in secure settings.
  • Do not share tokens/cookies in logs or prompts.
• Workspace isolation: mention-triggered tasks run in temporary workspaces by default and use the target workspace's access profile. Profile and administrator boundaries still apply to every command, file, network, and export operation.

Troubleshooting

Bird CLI Missing

• Install Bird:
  • brew install steipete/tap/bird
  • or npm install -g @steipete/bird

Auth Failures / Challenges

• Re-run Test Connection in Settings > X.
• Refresh browser cookies or re-enter manual tokens.
• If X account is challenged/rate-limited, mention polling stays alive and keeps reporting last error.

Rate Limits

• Increase poll interval and lower fetch count.
• Keep allowlist small and avoid aggressive polling.

Duplicates

• Duplicates are prevented by hook_sessions(session_key PRIMARY KEY).
• Service restarts and repeated mention windows should map to the same task id per tweet id.