@magclaw/notify

@magclaw/notify lets an Agent send a concise, structured task summary to a user-selected Feishu group. It is a sender-only package: it contains the sender CLI, Agent Skill, Claude Desktop MCP tools, summary templates, and sender-local audit commands.

Nothing is sent implicitly. The user must explicitly request MagClaw Notify, name the target group, and authorize the send in the current turn.

Install and sign in

One command downloads the current Client, opens Feishu login, binds the Bot contained in the Owner Token, makes it the current project's default connection, and installs integrations for detected Agent hosts:

npx --yes @magclaw/notify@latest setup --token "OWNER_TOKEN"

For an official MagClaw Relay, OWNER_TOKEN is a short connection code:

MCN-T-7KQ4-P9DX-3M2F-8R6T

The T or P segment selects the official testing or production Relay. The remaining 16 characters are an 80-bit random credential. The code contains no Bot name, group, user identity or local-device information. Existing long mcn_setup_... Tokens remain valid, and custom Relay URLs keep that format.

No connection name, default flag, Relay URL, or separate install command is needed. Bootstrap installs and verifies the current CLI version before login. The Owner Token already selects the Bot and Relay. It is a secret: send it only through a private channel.

Connections are scoped to the local Git project. Running setup with another Owner Token adds that Bot connection and makes it the project default. Advanced management remains available:

magclaw-notify connections list
magclaw-notify connections use monkey

With one connection it is selected automatically. With several, the project default is used; without a default the CLI requires --connection and never guesses. Project paths, hostnames, operating-system details and device fingerprints are never sent to the Owner or Relay.

The command opens a Feishu authorization page. It displays the target Bot, request time and your Feishu identity, but no hostname, operating system, project path or device fingerprint. Confirm only when you initiated the login.

Install integrations for the Agent hosts used on this computer:

magclaw-notify install --targets codex,claude-code,claude-desktop

• Codex and Claude Code receive a magclaw-notify Skill that is disabled for implicit model invocation.
• Claude Desktop receives two MCP tools: magclaw_notify_preview and magclaw_notify_send.
• Installation updates only the MagClaw Notify entry. Existing Claude Desktop configuration is preserved and backed up before a successful write.

Explicit send

The user must name the group in the current turn. The CLI never lists private group names and does not accept raw Feishu identifiers.

magclaw-notify send \
  --group "研发群" \
  --summary-json-file ./notify-summary.json \
  --authorized-current-turn

Plain Markdown is also supported:

magclaw-notify send \
  --group "研发群" \
  --markdown-file ./notify-summary.md \
  --authorized-current-turn

--authorized-current-turn is not remembered. A previous approval, an earlier conversation turn, or the Agent's own suggestion is never sufficient.

Structured summary

Prefer a structured summary so mixed tasks remain short and clear:

{
  "headline": "完成角色创建稳定性修复",
  "taskTypes": ["bugfix"],
  "sections": [
    {
      "type": "bugfix",
      "title": "问题描述",
      "items": [
        { "status": "info", "text": "短英文角色名被误判为占位内容，导致创角流程无法完成" }
      ]
    },
    {
      "type": "bugfix",
      "title": "修复结果",
      "items": [
        { "status": "done", "text": "短专有名词现可作为合法角色名，英文占位短语和完整句子仍会被拦截" }
      ]
    }
  ],
  "links": [
    { "label": "变更说明", "url": "https://example.com/change" }
  ],
  "images": [
    { "url": "https://example.com/result.png", "alt": "修复结果" }
  ]
}

Supported task types are feature, bugfix, performance, investigation, design, deployment, research, documentation, and custom. For software changes, default to 问题描述 and 修复结果. Keep the headline factual, retain material impact and unresolved risks, and omit routine merge, test, validation, and deployment details unless they change what teammates need to do.

Images must use public HTTPS URLs. Links and images are validated before the request is accepted.

Statuses

The initial response and status command expose only the state the sender needs:

| Status | Meaning | Sender action | |---|---|---| | processing | The request was accepted and is being processed. | Do not resend; poll status. | | awaiting_owner_approval | The destination needs owner approval. | Do not resend; poll status. | | sent | Delivery completed. | No further action. | | failed | Delivery failed. | Explain the failure; retry only after a new explicit user instruction. | | rejected | The request was rejected. | Do not retry without a new explicit user instruction. | | approval_expired | Approval was not completed before expiry. | Ask the user to submit a new explicit request. |

Check a request returned by send:

magclaw-notify status REQUEST_ID

Claude Desktop MCP tools

magclaw_notify_preview formats a non-sending preview. After the user confirms that exact preview in the current turn, magclaw_notify_send may be called with userAuthorizedCurrentTurn: true.

The send tool must not be called because a task completed, because similar messages were sent before, or because the Agent believes notification would be helpful.

Sender commands

magclaw-notify targets
magclaw-notify whoami
magclaw-notify audit status
magclaw-notify audit tail --limit 100
magclaw-notify logout

Sender audit files contain correlation metadata and outcomes, not message bodies or credentials. Local credentials must never be committed, pasted into task summaries, or shared with another user.

Automatic updates

Startup schedules a detached update check at most once every six hours; sends never wait for it. The exact npm version is verified before activation and the previous verified version is retained for rollback.

magclaw-notify update status
magclaw-notify update check
magclaw-notify update apply --target-version 0.8.0
magclaw-notify update rollback

Set MAGCLAW_NOTIFY_AUTO_UPDATE=0 to disable automatic checks.

License

MIT