Document retry/idempotency characteristics and add pagination hints
@scottlovegrove is already working on this.
Since Apr 5, 2026.
- Dominant language
- TypeScript
- Stars
- 3
- Forks
- 1
- Avg merge
- 2h 4m
- Merged PRs (30d)
- 14
Description
Priority: Low
Context
Based on 7 Principles for Agent-Friendly CLIs:
- Principle 4 (Safe Retries): "Agents retry, resume, and replay commands more frequently than humans. For append/send/trigger operations where exact idempotence proves impossible, mutation boundaries should remain explicit with identifiers letting agents determine if work repeated."
- Principle 7 (Bounded, High-Signal Responses): "When truncating, CLIs should teach agents how to narrow queries."
Part 1: Document retry/idempotency in skill content
Problem
Agents don't know which commands are safe to retry. Creating a thread twice makes two threads. Archiving an already-archived thread is a no-op. An agent has no way to know this without experimenting.
Proposed solution
Add a section to SKILL_CONTENT in src/lib/skills/content.ts documenting retry behaviour:
## Retry Safety
Commands that are safe to retry (idempotent):
- `thread done`, `conversation done` — archiving an already-archived item is a no-op
- `thread mute`, `thread unmute` — setting the same mute state is a no-op
- `conversation mute`, `conversation unmute` — same
Commands that produce duplicates on retry:
- `thread create` — creates a new thread each time
- `thread reply` — posts a new comment each time
- `conversation reply` — sends a new message each time
Use `--dry-run` to preview mutations before executing. All create/send commands return the created object's `id` in `--json` mode, which can be used to detect unintended duplicates.
Part 2: Add pagination hints to human-readable output
Problem
When results are paginated, the JSON/NDJSON output includes nextCursor metadata, but the human-readable output doesn't tell the user (or agent) that there are more results or how to get them. An agent falling back to human output won't know results were truncated.
Proposed solution
Add a footer line to paginated human-readable output when there are more results:
── 25 threads shown. More results available — use --limit, --since, or --until to adjust. ──
or when a cursor is available:
── Showing first 50 results. Use --json or --ndjson for cursor-based pagination. ──
This applies to:
tw inboxtw thread view(comments list)tw conversation view(messages list)tw conversation listtw search
Implementation would go in the output formatting section of each command, after the main results are printed, checking if nextCursor is non-null.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.