Skip to content

feat: add scry skill for querying ship state#4

Draft
wca4a wants to merge 5 commits intomainfrom
feat/urbit-scry-skill
Draft

feat: add scry skill for querying ship state#4
wca4a wants to merge 5 commits intomainfrom
feat/urbit-scry-skill

Conversation

@wca4a
Copy link
Copy Markdown
Owner

@wca4a wca4a commented Jan 26, 2026

Summary

Adds an urbit-scry skill that enables agents to query Urbit ship state via the scry interface.

Features

Shortcuts

  • --groups - List all groups
  • --channels - List all channel subscriptions
  • --contacts - List all contacts
  • --dms - List DM conversations
  • --apps - List installed apps

Message History

  • --history <nest> [count] - Last N messages from a channel
  • --older <nest> <id> [count] - Pagination (messages older than ID)
  • --thread <nest> <id> - Get post and its replies

Raw Scry

  • Any scry path ending in .json

Caching

  • File-based cache in ~/.clawdbot/cache/tlon-scry/
  • Configurable TTL by path type
  • Posts/history are never cached (always fresh)

Usage Examples

# List groups
node skills/urbit-scry/scry.mjs --groups

# Get last 20 messages from a channel
node skills/urbit-scry/scry.mjs --history chat/~bitbet-bolbel/urbit-community 20

# Get a thread
node skills/urbit-scry/scry.mjs --thread chat/~host/channel 170.141.184.505...

# Raw scry
node skills/urbit-scry/scry.mjs "/contacts/all.json"

Known Limitations

  • DM history scry may not work on all ships (Tlon uses subscriptions for DMs)
  • --dm command tries multiple paths but may fail

Test plan

  • Test --groups returns group list
  • Test --channels returns channel subscriptions
  • Test --history returns formatted messages
  • Test --older pagination works
  • Test --thread returns post and replies
  • Test caching works (second call shows [cache hit])
  • Test --no-cache bypasses cache

🤖 Generated with Claude Code

william arzt and others added 3 commits January 26, 2026 17:40
Adds a skill that allows the agent to query Urbit ship state via scry:

- List groups, channels, contacts, DMs, installed apps
- Fetch channel message history with pagination
- Get thread posts and replies
- Raw scry for arbitrary paths
- File-based caching with configurable TTL

Commands:
  --groups, --channels, --contacts, --dms, --apps
  --history <nest> [count]
  --older <nest> <id> [count]
  --thread <nest> <id>
  <raw-scry-path>

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Add formatUd() for @ud number formatting (dotted notation)
- Fix channel post paths: /v4/{id}/posts/{mode}/{cursor?}/{count}/{format}
- Fix DM paths: /v3/dm/{id}/writs/... (not /chat/dm/{ship}/...)
- Add --older, --newer, --post commands for pagination and single posts
- Add --dm, --club commands for DM/group DM history
- Add --replies flag to include nested replies
- Enhance formatters to extract and display nested replies
- Fix DM formatter to handle 'essay' field (newer API)
- All commands tested and working

Paths derived from tloncorp/tlon-apps production code.

Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>
@wca4a wca4a changed the title feat: add urbit-scry skill for querying ship state feat: add scry skill for querying ship state Jan 27, 2026
william arzt and others added 2 commits January 27, 2026 08:44
- Document group structure (top-level keys = group IDs)
- Show how to count groups with Object.keys().length
- Add example for extracting group titles from meta field

Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>
- Document group terminology: fleet, cabals, sects, cordon, zones
- Add examples for extracting member lists from groups
- Show how to get group count, list members, and analyze roles
- Add full group analysis helper function

From tloncorp/tlon-apps groups.ts official types.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant