Agentinbox

AgentInbox Skill

Use this skill when a Codex, Claude Code, Holon, or other supported agent runtime should set up or use the local agentinbox daemon.

Primary docs:

• https://agentinbox.holon.run/guides/onboarding-with-agent-skill
• https://agentinbox.holon.run/guides/getting-started
• https://agentinbox.holon.run/guides/review-workflows
• https://agentinbox.holon.run/reference/cli

Install

Install agentinbox if it is not already available:

npm install -g @holon-run/agentinbox

Install uxc if GitHub or Feishu adapters are needed:

brew tap holon-run/homebrew-tap
brew install uxc

UXC repository:

• https://github.com/holon-run/uxc

First-Run Onboarding

Recommended first-run sequence:

1. if GitHub access is needed and gh is already authenticated, import that auth into uxc
2. register the current runtime/session
3. follow the required sources or resources using the docs examples

If GitHub-backed adapters are needed:

gh auth status
uxc auth credential import github --from gh

This gh import path requires uxc 0.15.3 or newer.

Register the current runtime/session:

agentinbox agent register

In Holon, the no-arg form uses HOLON_AGENT_ID and HOLON_EXTERNAL_TRIGGER_URL when they are available and registers a webhook activation target. If the trigger URL is not in the environment, pass it explicitly:

agentinbox agent register --agent-id <holonAgentId> --webhook-url <externalTriggerUrl>

Treat the returned agentId as the stable identity for later commands.

Usage Discipline

Defaults:

• do not create one GitHub source per PR unless the source itself must be PR- scoped
• prefer shared repo/repo-CI sources plus narrow follows or subscriptions
• prefer agentinbox follow over manual subscription add when a follow template exists
• if a source exposes only subscription shortcuts, prefer the shortcut over manually reconstructing the same filter and lifecycle fields
• treat unused task-specific subscriptions as cleanup debt
• if GitHub polling volume looks high, inspect old subscriptions and duplicate temporary sources before adding more

This matches the AgentInbox model: sources are shared hosting units, while subscriptions carry agent-specific filtering and delivery intent.

Default Async Lifecycle

Default to AgentInbox when the work is not purely synchronous in the current session.

Typical cases:

• delayed follow-up that should happen after you stop actively looking at the terminal
• waiting for PR review, CI completion, issue replies, or other external events
• anything that must survive session boundaries instead of living only in chat memory
• reminders that should fire at a specific time or on a recurring schedule

Important boundary:

• inbox items, subscriptions, and timers can outlive the current runtime session
• activation delivery does not automatically survive every session boundary just because the inbox state does
• if the original runtime/terminal or webhook trigger disappears, items may keep accumulating in the inbox while notifications stop reaching you
• if a later session should resume the same logical agent, re-register or explicitly rebind that agent to the current terminal or webhook target before assuming prompt delivery is live again

Lifecycle:

1. register once per live runtime/session
2. reuse broad shared sources
3. add narrow task-scoped follows, subscriptions, or timers
4. read inbox items in bounded batches and ack only the reviewed batch
5. clean up task-scoped subscriptions/timers after merge, closure, or abandonment

For PR and review workflows, prefer follow templates. They reuse shared sources, expand the source-specific filters, and attach cleanup behavior:

For Holon, ensure HOLON_EXTERNAL_TRIGGER_URL is set or use --webhook-url when registering.

agentinbox agent register
agentinbox follow github pr --agent-id <agentId> --arg owner=holon-run --arg repo=agentinbox --arg number=87 --arg withCi=true
agentinbox inbox read --agent-id <agentId>
agentinbox inbox ack --agent-id <agentId> --through <lastEntryId>

Ack discipline:

• prefer agentinbox inbox ack --agent-id <agentId> --through <lastEntryId> after reading a reviewed batch
• avoid ack --all unless you explicitly verified that every current item should be cleared
• do not ack speculative future work just because the current terminal message was seen

Timer intent:

• use agentinbox timer add when the trigger is time-based rather than source-based
• prefer timers over inventing fake local events for reminders like "check CI in 30 minutes" or "revisit this PR tomorrow morning"

Core Commands

Follow high-level templates:

agentinbox follow github repo --agent-id <agentId> --arg owner=holon-run --arg repo=agentinbox
agentinbox follow github pr --agent-id <agentId> --arg owner=holon-run --arg repo=agentinbox --arg number=87 --arg withCi=true
agentinbox follow github issue --agent-id <agentId> --arg owner=holon-run --arg repo=agentinbox --arg number=180
agentinbox follow github pr --agent-id <agentId> --args-json '{"owner":"holon-run","repo":"agentinbox","number":87,"withCi":true}'

Use follow as the default path for GitHub repo, PR, and issue tracking. Drop to source schema plus subscription add only when you need a custom filter or the source has no follow template.

Feishu/Lark follows require a UXC credential that can host the Feishu app connection. For bot mention workflows, prefer the global mention template so the user does not need to discover a group chat_id or bot open_id first:

agentinbox follow feishu mentions --agent-id <agentId> --config-json '{"uxcAuth":"feishu-default"}'

When openId is omitted, AgentInbox resolves the configured app bot's open_id through UXC before creating the subscription. Pass --arg openId=<openId> only when following mentions for a different user or bot.

Use the chat-scoped templates when the task is explicitly limited to one group:

agentinbox follow feishu chat --agent-id <agentId> --arg chatId=<chatId> --config-json '{"uxcAuth":"feishu-default"}'
agentinbox follow feishu mention --agent-id <agentId> --arg chatId=<chatId> --arg openId=<botOpenId> --config-json '{"uxcAuth":"feishu-default"}'

Feishu inbox items include metadata.chatId, metadata.messageId, and a deliveryHandle. Use source invoke for local context before replying:

agentinbox source invoke <sourceId> --operation get_message_context --input-json '{"messageId":"<messageId>","chatId":"<chatId>","windowBefore":5,"windowAfter":5}'
agentinbox deliver invoke --handle-json '<deliveryHandle-json>' --operation send_text --input-json '{"text":"Acknowledged","uxcAuth":"feishu-default"}'

Feishu messages may carry files, images, or cloud document links. List the attachments first and then save them locally:

# List attachments for a message
agentinbox source invoke <sourceId> \
  --operation list_message_attachments \
  --input-json '{"messageId":"<messageId>"}'

# Save one attachment by messageId + attachmentId
agentinbox source invoke <sourceId> \
  --operation save_attachment \
  --input-json '{"messageId":"<messageId>","attachmentId":"<attachmentId>","outputDir":"/tmp/agentinbox-feishu"}'

# Save with explicit output path and identity
agentinbox source invoke <sourceId> \
  --operation save_attachment \
  --input-json '{"messageId":"<messageId>","attachmentId":"<attachmentId>","outputPath":"/tmp/report.pdf","identity":"bot"}'

Output formats by attachment kind:

Optional save_attachment parameters: outputPath, outputDir, fileName, format, subId, identity ("user" or "bot"), overwrite.

Rich text and file replies are available through send_post, send_file, and send_file_from_path delivery operations. Use deliver actions to inspect available schemas.

Advanced source/subscription commands:

agentinbox source list
agentinbox source show <sourceId>
agentinbox source schema <sourceId>
agentinbox source add <hostId> repo_events <owner>/<repo> --config-json '{"owner":"holon-run","repo":"agentinbox"}'
agentinbox source add <hostId> ci_runs <owner>/<repo> --config-json '{"owner":"holon-run","repo":"agentinbox","pollIntervalSecs":30}'
agentinbox subscription add <sourceId> --shortcut pr --shortcut-args-json '{"number":87}'
agentinbox subscription add <sourceId> --filter-json '{"metadata":{"headBranch":"main","conclusion":"failure"}}'
agentinbox subscription list --agent-id <agentId>
agentinbox subscription remove <subscriptionId>

Use manual subscriptions for advanced filters, custom source kinds, or when debugging template expansion. If subscriptionSchema.shortcuts is non-empty but no follow template is available, prefer those shortcut entries first.

Read and ack the inbox:

agentinbox inbox read --agent-id <agentId>
agentinbox inbox ack --agent-id <agentId> --through <lastEntryId>
agentinbox inbox send --agent-id <agentId> --message "Please review PR #87"
agentinbox inbox watch --agent-id <agentId>
agentinbox inbox ack --agent-id <agentId> --all

Default to a batch-bounded ack flow:

1. read the inbox items you intend to process
2. identify the last item you actually reviewed in that batch
3. ack with --through <lastEntryId>

Use ack --all only after explicitly verifying every current item should be cleared. Use inbox send for local operator/direct text ingress.

Manage timers:

agentinbox timer add --agent-id <agentId> --at <RFC3339_TIMESTAMP> --message "Check the morning build"
agentinbox timer add --agent-id <agentId> --every 24h --message "Review today's open PRs"
agentinbox timer add --agent-id <agentId> --cron "0 8 * * *" --timezone Asia/Shanghai --message "Daily triage"
agentinbox timer list
agentinbox timer list --agent-id <agentId>
agentinbox timer pause <scheduleId>
agentinbox timer resume <scheduleId>
agentinbox timer remove <scheduleId>

Activation targets:

agent register normally creates or refreshes the current runtime activation target automatically: a terminal target for terminal-backed runtimes, or a webhook target for Holon when a trigger URL is available. Add manual activation targets only when needed:

agentinbox agent target list <agentId>
agentinbox agent target add webhook <agentId> --url http://127.0.0.1:8787/webhook
agentinbox agent target remove <agentId> <targetId>

For filtering strategy and review workflow setup, follow the docs links above instead of re-explaining the full architecture here.

Troubleshooting

Do not start every task by checking daemon status; normal CLI commands should auto-connect or surface actionable errors. Use these checks after the first AgentInbox command fails, notifications stop arriving, or you suspect a stale terminal or webhook binding:

agentinbox --version
agentinbox daemon status
agentinbox daemon start
agentinbox agent register --agent-id <agentId> --force-rebind
agentinbox agent register --agent-id <holonAgentId> --webhook-url <externalTriggerUrl> --force-rebind

If GitHub-backed sources fail, verify UXC and imported GitHub auth only after the failure points there:

uxc --version
gh auth status
uxc auth credential import github --from gh