# Agentinbox > Use the local AgentInbox service to onboard the current runtime/session, manage shared sources and subscriptions, connect external providers such as GitHub through UXC, and operate the agent inbox. - Skill: `holon-run/agentinbox` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add holon-run/agentinbox` - Raw SKILL.md: https://api.skillmd.com/api/skills/holon-run/agentinbox/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: holon-run (https://skillmd.com/u/holon-run) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/holon-run/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: ```bash npm install -g @holon-run/agentinbox ``` Install `uxc` if GitHub or Feishu adapters are needed: ```bash 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: ```bash 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: ```bash 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: ```bash agentinbox agent register --agent-id --webhook-url ``` 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. ```bash agentinbox agent register agentinbox follow github pr --agent-id --arg owner=holon-run --arg repo=agentinbox --arg number=87 --arg withCi=true agentinbox inbox read --agent-id agentinbox inbox ack --agent-id --through ``` Ack discipline: - prefer `agentinbox inbox ack --agent-id --through ` 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: ```bash agentinbox follow github repo --agent-id --arg owner=holon-run --arg repo=agentinbox agentinbox follow github pr --agent-id --arg owner=holon-run --arg repo=agentinbox --arg number=87 --arg withCi=true agentinbox follow github issue --agent-id --arg owner=holon-run --arg repo=agentinbox --arg number=180 agentinbox follow github pr --agent-id --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: ```bash agentinbox follow feishu mentions --agent-id --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=` only when following mentions for a different user or bot. Use the chat-scoped templates when the task is explicitly limited to one group: ```bash agentinbox follow feishu chat --agent-id --arg chatId= --config-json '{"uxcAuth":"feishu-default"}' agentinbox follow feishu mention --agent-id --arg chatId= --arg openId= --config-json '{"uxcAuth":"feishu-default"}' ``` Feishu inbox items include `metadata.chatId`, `metadata.messageId`, and a `deliveryHandle`. Use `source invoke` for local context before replying: ```bash agentinbox source invoke --operation get_message_context --input-json '{"messageId":"","chatId":"","windowBefore":5,"windowAfter":5}' agentinbox deliver invoke --handle-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: ```bash # List attachments for a message agentinbox source invoke \ --operation list_message_attachments \ --input-json '{"messageId":""}' # Save one attachment by messageId + attachmentId agentinbox source invoke \ --operation save_attachment \ --input-json '{"messageId":"","attachmentId":"","outputDir":"/tmp/agentinbox-feishu"}' # Save with explicit output path and identity agentinbox source invoke \ --operation save_attachment \ --input-json '{"messageId":"","attachmentId":"","outputPath":"/tmp/report.pdf","identity":"bot"}' ``` Output formats by attachment kind: | Kind | Default | `format` options | |---|---|---| | `image` / `file` | original binary | `"original"` only | | `doc` / `docx` / `wiki` | `.md` (Markdown) | N/A | | `sheet` | `.xlsx` | `"csv"` (requires `subId`) | | `bitable` / `base` | `.base` | `"csv"` (requires `subId`) | | `drive_file` | original file | `"original"` only | 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: ```bash agentinbox source list agentinbox source show agentinbox source schema agentinbox source add repo_events / --config-json '{"owner":"holon-run","repo":"agentinbox"}' agentinbox source add ci_runs / --config-json '{"owner":"holon-run","repo":"agentinbox","pollIntervalSecs":30}' agentinbox subscription add --shortcut pr --shortcut-args-json '{"number":87}' agentinbox subscription add --filter-json '{"metadata":{"headBranch":"main","conclusion":"failure"}}' agentinbox subscription list --agent-id agentinbox subscription remove ``` 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: ```bash agentinbox inbox read --agent-id agentinbox inbox ack --agent-id --through agentinbox inbox send --agent-id --message "Please review PR #87" agentinbox inbox watch --agent-id agentinbox inbox ack --agent-id --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 ` Use `ack --all` only after explicitly verifying every current item should be cleared. Use `inbox send` for local operator/direct text ingress. Manage timers: ```bash agentinbox timer add --agent-id --at --message "Check the morning build" agentinbox timer add --agent-id --every 24h --message "Review today's open PRs" agentinbox timer add --agent-id --cron "0 8 * * *" --timezone Asia/Shanghai --message "Daily triage" agentinbox timer list agentinbox timer list --agent-id agentinbox timer pause agentinbox timer resume agentinbox timer remove ``` 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: ```bash agentinbox agent target list agentinbox agent target add webhook --url http://127.0.0.1:8787/webhook agentinbox agent target remove ``` 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: ```bash agentinbox --version agentinbox daemon status agentinbox daemon start agentinbox agent register --agent-id --force-rebind agentinbox agent register --agent-id --webhook-url --force-rebind ``` If GitHub-backed sources fail, verify UXC and imported GitHub auth only after the failure points there: ```bash uxc --version gh auth status uxc auth credential import github --from gh ```