docs(skill): expand imsg agent skill with full CLI surface by omarshahine · Pull Request #154 · openclaw/imsg

omarshahine · 2026-07-04T22:39:37Z

Summary

Rewrites .agents/skills/imsg/SKILL.md so agents get an accurate, complete picture of the CLI. The previous version covered only chats/history/search/send, hardcoded a machine-specific repo path (~/Projects/imsg), and never mentioned the standard-vs-bridge capability split.

Changes (verified against imsg completions llm and docs/):

Two-tier capability model up front: standard commands (chats/group/history/watch/search/send/react + --local lookups) vs bridge commands (send-rich, tapback, poll, edit/unsend, chat-*), gated on imsg status --json, with explicit guidance to fall back to standard equivalents rather than suggest disabling SIP.
Progressive disclosure: points agents at imsg completions llm for the full flag reference so the skill stays short.
Keeps the original's key insight (resolve UI-visible people via chats/contact_name, not search) and adds what was missing: group before automating, --start/--end inclusive/exclusive semantics, --since-rowid as the watch cursor, --convert-attachments, SMS fallback behavior, and react's most-recent-message-only limitation with tapback as the bridge alternative.
Requires per-action user confirmation for destructive bridge commands (unsend, delete-message, chat-delete, chat-leave, chat-remove-member).
Verification now uses ./bin/imsg (the source-build output) for live read proof.

Review fix (540c803): default nickname moved to the bridge tier; the SIP-free tier and example now use nickname --local, with a note that --local returns your own AddressBook label rather than the iMessage-shared nickname. Matches Sources/imsg/Commands/BridgeIntroCommands.swift and the CLI help below.

Poll docs scope (decoupled from #155): an earlier revision documented the poll question echoing as a visible caption, the --comment override, and inbound question backfill. That behavior lives in #155, not on shipped main — imsg poll --help on 0.12.2 exposes only --question/--option, no --comment. Those claims were removed so this skill documents only shipped behavior and merges independently; #157 tracks re-adding them once #155 lands.

Validation transcript

Run against imsg 0.12.2 (Homebrew) on macOS:

$ imsg --version
0.12.2

$ imsg completions llm | grep -c "^### "   # command sections in the agent reference
33

$ imsg poll --help | grep -E '^\s+--'      # shipped poll surface: no --comment
  --db <value>	Path to chat.db (defaults to ~/Library/Messages/chat.db)
  --chat <value>	chat guid or rowid
  --chat-id <value>	chat rowid
  --question <value>	poll question
  --option <value>	poll option text; pass at least twice
  --option-id <value>	vote: UUID of the option to select
  --option-index <value>	vote: 1-based option number to select

$ imsg nickname --help | head -11
imsg nickname
Show contact-card / nickname info for a handle

The default mode reads the contact-card nickname the correspondent shared
over iMessage via the IMCore bridge (requires `imsg launch`, SIP disabled).

--local is a SIP-free alternative that returns YOUR local AddressBook
contact name for the handle. NOTE: this is a different datum — it is your
own contact label, not the iMessage-shared nickname/photo, which is only
available through the bridge.

$ imsg status --json | jq '{sip, v2_ready, basic_features, typing_indicators, read_receipts}'
{
  "sip": "enabled",
  "v2_ready": false,
  "basic_features": true,
  "typing_indicators": false,
  "read_receipts": false
}

(The status output above is from a SIP-enabled machine — exactly the state where the skill's fallback guidance applies.)

jq chat-filter example validated against synthetic NDJSON matching docs/json.md's Chat schema:

$ printf '%s\n' '{"id":1,"contact_name":"Beatrix Smith","identifier":"+15551234567"}' '{"id":2,"name":"Other"}' \
    | jq -s '.[] | select((.contact_name // .display_name // .name // .identifier // "" | ascii_downcase) | contains("beatrix")) | .id'
1

🤖 Generated with Claude Code

clawsweeper · 2026-07-04T22:40:19Z

Codex review: needs maintainer review before merge. Reviewed July 5, 2026, 12:24 PM ET / 16:24 UTC.

Summary
The PR updates .agents/skills/imsg/SKILL.md to document the current imsg CLI command tiers, JSON/read workflows, bridge-only commands, send/react safety guidance, and validation commands.

Reproducibility: not applicable. this is a skill documentation PR, not a runtime bug report. The prior poll-doc finding no longer reproduces on the current head because the unsupported terms are absent and the remaining claims match current docs/source inspection.

Review metrics: 2 noteworthy metrics.

Diff scope: 1 file modified, +48/-32. The review surface is limited to the bundled imsg skill and does not alter runtime code, dependencies, CI, or release scripts.
Prior blocker check: 0 current-head matches. The unsupported poll caption/comment/backfill terms raised in earlier review cycles are absent from the current PR head.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

none.

Next step before merge

[P2] No repair lane is needed because the current head is a focused skill-doc update with sufficient terminal proof and no actionable finding.

Security
Cleared: The diff changes only repo-local skill documentation and does not alter code execution, dependencies, CI, secrets, permissions, or release scripts.

Review details

Best possible solution:

Merge the focused skill update after normal maintainer review and status checks, while leaving the unshipped poll-caption/backfill guidance to https://github.com/openclaw/imsg/issues/157 after https://github.com/openclaw/imsg/pull/155 lands.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a skill documentation PR, not a runtime bug report. The prior poll-doc finding no longer reproduces on the current head because the unsupported terms are absent and the remaining claims match current docs/source inspection.

Is this the best way to solve the issue?

Yes. Updating the bundled skill is the narrow maintainable path for this agent guidance, and unshipped poll-caption behavior is now deferred to the linked follow-up instead of being documented early.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 9ac97ab1d242.

Label changes

Label justifications:

P3: This is a low-risk skill documentation update with limited blast radius and no remaining correctness finding.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes copied terminal output from a real macOS/Homebrew imsg 0.12.2 run plus a jq validation transcript for the documented filter example.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes copied terminal output from a real macOS/Homebrew imsg 0.12.2 run plus a jq validation transcript for the documented filter example.

Evidence reviewed

What I checked:

Repository policy read: AGENTS.md was read fully and its focused PR-validation and CLI documentation guidance was applied to this skill-doc review. (AGENTS.md:1, 9ac97ab1d242)
Current main still has the shorter skill: Main's bundled imsg skill still documents only a small read/send workflow and a machine-specific repo path, so the PR is not already implemented on main. (.agents/skills/imsg/SKILL.md:8, 9ac97ab1d242)
PR head adds the capability split and full-reference pointer: The PR head documents standard vs bridge tiers, bridge fallback guidance, and imsg completions llm as the full command reference. (.agents/skills/imsg/SKILL.md:12, 4e5aa724008b)
Prior poll-doc blocker is removed: The current PR head has zero matches for the earlier unsupported poll --comment, caption, or backfill guidance; the previous 809395b head still had those terms. (.agents/skills/imsg/SKILL.md:75, 4e5aa724008b)
Shipped poll CLI surface matches the decoupled docs: Current main's poll command exposes --question, repeated --option, vote selectors, and --reply-to, with no --comment option. (Sources/imsg/Commands/PollCommand.swift:19, 9ac97ab1d242)
Nickname local-vs-bridge guidance matches source: Current main says default nickname uses the IMCore bridge and --local returns the local AddressBook label, matching the corrected PR text. (Sources/imsg/Commands/BridgeIntroCommands.swift:274, 9ac97ab1d242)

Likely related people:

steipete: GitHub commit history shows recent bundled imsg skill refreshes and the generated completions command, and local blame shows the current main skill content comes through the v0.12.2 release commit. (role: recent skill and CLI-completions area contributor; confidence: high; commits: 405aa23f5d50, 9202d9701f6c, faa998e39f11; files: .agents/skills/imsg/SKILL.md, Sources/imsg/Commands/CompletionsCommand.swift)
omarshahine: Prior merged history includes native poll voting and the BlueBubbles private-API bridge, which are key command areas summarized by this skill beyond the PR author's current branch. (role: bridge and poll-adjacent contributor; confidence: high; commits: 617d941f7b1e, c56c24d488ef; files: Sources/imsg/Commands/PollCommand.swift, Sources/imsg/Commands/BridgeMessagingCommands.swift, Sources/imsg/Commands/BridgeIntroCommands.swift)
ranaroussi: GitHub history shows the SIP-free --local lookup modes and SMS fallback behavior were added in the same command surface the PR now documents. (role: local lookup and SMS fallback contributor; confidence: medium; commits: 5bac5ce24784; files: Sources/imsg/Commands/BridgeIntroCommands.swift, Sources/imsg/Commands/SendCommand.swift)
veteranbv: GitHub history shows native poll creation/readback work that informs the poll examples and the deferred poll-doc follow-up. (role: native poll feature contributor; confidence: medium; commits: 0c9d85db44f0, 9a21cdbe9017, 2529aa7ad011; files: Sources/IMsgCore/MessagePolls.swift, Sources/imsg/Commands/PollCommand.swift, docs/history.md)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (7 earlier review cycles)

reviewed 2026-07-04T22:42:52.014Z sha ee02e6c :: needs real behavior proof before merge. :: [P2] Correct the SIP-free nickname example
reviewed 2026-07-04T22:50:47.977Z sha 540c803 :: needs maintainer review before merge. :: none
reviewed 2026-07-04T22:54:58.024Z sha 540c803 :: needs maintainer review before merge. :: none
reviewed 2026-07-05T00:46:08.332Z sha 7b0f07b :: needs real behavior proof before merge. :: [P2] Remove the unsupported poll comment option
reviewed 2026-07-05T01:42:41.118Z sha 809395b :: needs real behavior proof before merge. :: [P2] Remove the unsupported poll caption option
reviewed 2026-07-05T10:30:37.572Z sha 809395b :: needs real behavior proof before merge. :: [P2] Remove unsupported poll caption guidance
reviewed 2026-07-05T16:19:51.249Z sha 4e5aa72 :: needs maintainer review before merge. :: none

omarshahine · 2026-07-04T22:51:17Z

@clawsweeper re-review

clawsweeper · 2026-07-04T22:51:20Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

omarshahine · 2026-07-05T16:17:01Z

Decoupled from #155 per maintainer decision. The poll caption echo, --comment override, and inbound question backfill live in #155, not shipped main (imsg poll --help on 0.12.2 exposes only --question/--option, no --comment). Those claims are removed (4e5aa72) so this skill documents only shipped behavior; #157 tracks re-adding them after #155 lands. PR body updated with the shipped-poll-surface proof.

@clawsweeper re-review

clawsweeper · 2026-07-05T16:17:04Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

The skill covered only a fraction of the CLI and hardcoded a machine-specific repo path. Rewrite it around the two capability tiers (standard SQLite/AppleScript vs SIP-disabled IMCore bridge) so agents check `imsg status` before reaching for bridge commands and fall back to standard equivalents instead of suggesting SIP changes. - Point to `imsg completions llm` for the full flag reference - Add watch/--since-rowid cursor, group, date-range semantics, attachment conversion, and --local lookups - Document react's most-recent-message limitation with tapback as the bridge alternative - Require per-action confirmation for destructive bridge commands - Drop the ~/Projects/imsg path; verify with ./bin/imsg after builds Co-Authored-By: Claude Fable 5 <[email protected]>

Per review: default `imsg nickname` reads the iMessage-shared contact card via the IMCore bridge; only `--local` (your own AddressBook label, a different datum) works without SIP disabled. Move default-mode nickname to the bridge tier and add --local to the SIP-free example. Co-Authored-By: Claude Fable 5 <[email protected]>

Messages never renders the poll title on the balloon, so `poll send` now echoes --question as a reply comment; document that recipients see the question and that --comment overrides it. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

Reflect that poll send now sends the caption as a plain message (not a threaded reply) and that inbound native polls have their question backfilled from the caption on read. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

The poll caption echo, --comment override, and inbound question backfill live in openclaw#155, not on main (shipped imsg 0.12.2 'poll --help' has no --comment). Drop those claims so the skill documents only shipped behavior and can merge independently of openclaw#155. Tracked by openclaw#157 to re-add once openclaw#155 lands. Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_011dTDUtxanzs8NDhTD862QV

steipete · 2026-07-06T08:43:43Z

Landed as e771b0c. Thank you, @omarshahine.

Maintainer proof:

rebased onto current main
YAML frontmatter parsed and bundled skill validator passed
live imsg poll --help and imsg completions llm matched the documented caption and --comment behavior
branch-wide autoreview found one unsafe fallback rule; fixed it, then reran to a clean result
exact-head macOS and Linux CI passed

omarshahine mentioned this pull request Jul 5, 2026

skill: re-add poll caption/backfill/--comment docs after #155 lands #157

Closed

clawsweeper Bot mentioned this pull request Jul 5, 2026

fix(poll): make the poll question visible both directions (echo out, backfill in) #155

Merged

omarshahine and others added 3 commits July 6, 2026 09:36

omarshahine and others added 4 commits July 6, 2026 09:36

docs(skill): document native poll captions

287de04

docs(skill): guard bridge fallback semantics

06d49c4

steipete force-pushed the docs/improve-imsg-skill branch from 4e5aa72 to 06d49c4 Compare July 6, 2026 08:41

steipete merged commit e771b0c into openclaw:main Jul 6, 2026
2 checks passed

omarshahine deleted the docs/improve-imsg-skill branch July 8, 2026 04:35

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(skill): expand imsg agent skill with full CLI surface#154

docs(skill): expand imsg agent skill with full CLI surface#154
steipete merged 7 commits into
openclaw:mainfrom
omarshahine:docs/improve-imsg-skill

omarshahine commented Jul 4, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

omarshahine commented Jul 4, 2026

Uh oh!

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

omarshahine commented Jul 5, 2026

Uh oh!

clawsweeper Bot commented Jul 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

steipete commented Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

omarshahine commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation transcript

Uh oh!

clawsweeper Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

omarshahine commented Jul 4, 2026

Uh oh!

clawsweeper Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

omarshahine commented Jul 5, 2026

Uh oh!

clawsweeper Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

steipete commented Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

omarshahine commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 5, 2026 •

edited

Loading