agent-inbox

Check and process messages from autonomous AILANG agents. Use when starting a session, after agent handoffs, or when checking for completion notifications.

SKILL.md

GitHub

Agent Inbox

Check for messages from autonomous agents at session start and process completion notifications.

Quick Start

Most common usage:

# List all messages
ailang messages list

# Show only unread messages
ailang messages list --unread

# Read full message content
ailang messages read MSG_ID

# Acknowledge (mark as read)
ailang messages ack MSG_ID
ailang messages ack --all

# Send a message
ailang messages send user "Your message" --title "Title" --from "agent-name"

# Send with semantic envelope (v0.8.1+)
ailang messages send executor "Fix bug" --title "Bug" \
  --envelope-code internal/parser/parser.go \
  --envelope-context "reviewing ast type switches"

# Search by envelope space (v0.8.1+)
ailang messages search --space code "internal/types"
ailang messages search --space intent "fix crash"

# Triage unread messages by similarity (v0.8.1+)
ailang messages triage --cluster-by code

# Send bug/feature to GitHub (for cross-instance visibility)
ailang messages send user "Bug report" --type bug --github

Expected output (at session start):

📬 AGENT INBOX: 2 unread message(s) from autonomous agents
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ID: msg_20251210_143021_abc123
From: sprint-executor
Title: Sprint M-S1 complete
Time: 2025-12-10T14:30:21Z

ID: msg_20251210_143055_def456
From: stapledon
Title: Parser Bug
Time: 2025-12-10T14:30:55Z
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

When to Use This Skill

Invoke this skill when:

  • Session starts - First action in every Claude Code session (required by CLAUDE.md)
  • After handoffs - When you've sent work to autonomous agents
  • Periodic checks - User asks "any updates from agents?"
  • Debugging - To see agent communication history

Storage Backend — TWO stores, and the default is the private one

Store Selected by Who sees it
Canonical cloud (prod Firestore, ailang-multivac) AILANG_STORAGE_MESSAGING=gcp + AILANG_MESSAGES_PROJECT=ailang-multivac every machine
Local SQLite (~/.ailang/state/collaboration.db) default only this machine

Public feedback, package feedback, coordinator completions and other machines' agent traffic all land in the canonical store. A bare ailang messages list reads local SQLite and will not show any of it — measured 2026-08-26, the session banner reported 16 unread while the canonical store held 74.

Any listing against a non-local store prints its store in the header:

  store: gcp (Firestore, project ailang-multivac, via AILANG_STORAGE_MESSAGING)

No store: line means you are reading local only. Two causes: the vars are not set, or the binary predates the plane switch (M-V1-SIMPLIFY-S3 M3) and ignores them silently. Control for the second — an invalid value must be REFUSED:

AILANG_STORAGE_MESSAGING=not-a-real-store ailang messages list --unread
# current binary: errors "invalid storage selection: AILANG_STORAGE_MESSAGING=..."
# old binary:     lists normally  -> your counts are local-only
  • Accessible via: CLI (ailang messages) and Collaboration Hub dashboard
  • Message statuses: unread, read, archived, deleted

Traps

  • messages read <id> marks it read as a side effect — triaging by reading drains the queue. Read bodies from --json to inspect without acking.
  • The list view truncates IDs to 8 chars, so every cloud message shows as (inbox_17). Take full IDs from --json. An ambiguous prefix errors loudly rather than acking the wrong message.
  • ack --all spans every inbox by default, including other people's package feedback. Scope with --inbox, or ack by ID.

Available Commands

List Messages

ailang messages list                    # All messages
ailang messages list --unread           # Only unread
ailang messages list --inbox user       # Filter by inbox
ailang messages list --from agent-name  # Filter by sender
ailang messages list --json             # JSON output
ailang messages list --limit 50         # Limit results

Read Full Message

ailang messages read MSG_ID             # Full content, marks as read
ailang messages read MSG_ID --peek      # View without marking read
ailang messages read MSG_ID --json      # JSON output

Acknowledge Messages

ailang messages ack MSG_ID              # Mark specific message as read
ailang messages ack --all               # Mark all as read
ailang messages ack --all --inbox user  # Mark all in inbox as read

Un-acknowledge (Mark Unread)

ailang messages unack MSG_ID            # Move back to unread

Send Messages

# Basic send (local only - for coordination)
ailang messages send INBOX "message" --title "Title" --from "agent"

# With semantic envelope (v0.8.1+ - attaches embeddings for multi-space search)
ailang messages send INBOX "Fix bug" --title "Bug" \
  --envelope-code internal/parser/parser.go          # embeds code context
ailang messages send INBOX "Fix bug" --title "Bug" \
  --envelope-context "reviewing ast type switches"   # embeds session context

# With GitHub sync (for bugs/features - cross-instance visibility)
ailang messages send INBOX "message" --type bug --github
ailang messages send INBOX "message" --type feature --github
ailang messages send INBOX "message" --github --repo owner/repo

Import from GitHub

ailang messages import-github                    # Import from default repo
ailang messages import-github --repo owner/repo  # Specific repo
ailang messages import-github --labels bug,help  # Filter by labels
ailang messages import-github --dry-run          # Preview without importing

Workflow

1. Session Start Check (REQUIRED)

SessionStart hook runs automatically and shows unread messages.

If messages exist:

  • Read and summarize each message to user
  • Identify message type (completion, error, handoff)
  • Ask user if they want action taken
  • Acknowledge after handling: ailang messages ack --all

2. Process Completion Notifications

When agent reports completion:

# 1. Read the full message
ailang messages read MSG_ID

# 2. Review results mentioned in payload
ls -la eval_results/baselines/v0.4.2/

# 3. Report to user
echo "Sprint complete! Results at: eval_results/baselines/v0.4.2/"

# 4. Acknowledge after processing
ailang messages ack MSG_ID

3. Handle Error Reports

When agent reports errors:

# 1. Read the full error details
ailang messages read MSG_ID

# 2. Check logs if mentioned
cat .ailang/state/logs/sprint-executor.log

# 3. Diagnose and report to user
echo "Agent encountered error: Tests failing at milestone 3/5"

# 4. Either fix manually or send corrective instructions

4. Respond to Agent or User

# Send response to an agent
ailang messages send sprint-executor "Approved, proceed" \
  --title "Approval" --from "user"

# Send notification to user inbox
ailang messages send user "Issue resolved" \
  --title "Status update" --from "claude-code"

GitHub Integration (Bi-directional)

Message Types and Routing

Type Purpose Goes to GitHub?
bug Bug report Yes (with --github)
feature Feature request Yes (with --github)
general Coordination No (local only)

Routing guidance:

  • Bugs and features → Use --github for visibility across all AILANG instances
  • Coordination messages → Local only, for agent-to-agent communication
  • Instructions from humans → Create GitHub issues, they'll be imported automatically

Sending to GitHub (Agent → GitHub)

# Bug reports and feature requests go to GitHub for visibility
ailang messages send user "Parser crash" --type bug --github
ailang messages send user "Need async support" --type feature --github

Importing from GitHub (GitHub → Local)

# Runs automatically on session start (if auto_import: true in config)
ailang messages import-github

# Or manually with filters
ailang messages import-github --labels help-wanted

Human Instructions via GitHub

You can write instructions as GitHub issues and have agents pick them up:

  1. Create issue on GitHub with ailang-message label
  2. Next session, import-github runs automatically
  3. Issue appears in agent's inbox as a message
  4. Agent reads and acts on the instructions

Configuration

Create ~/.ailang/config.yaml:

github:
  expected_user: YourGitHubUsername   # REQUIRED: Must match gh auth status
  default_repo: sunholo-data/ailang   # Default repo for issues
  create_labels:
    - ailang-message
  watch_labels:
    - ailang-message
  auto_import: true                   # Auto-import on session start

Prerequisites:

  1. Install GitHub CLI: brew install gh
  2. Authenticate: gh auth login
  3. Check account: gh auth status
  4. Switch if needed: gh auth switch --user USERNAME

Auto-label creation: Labels are automatically created if they don't exist:

  • from:agent-name (purple) - who sent the message
  • bug (red), feature (cyan), general (light blue)
  • ailang-message (blue) - identifies AILANG messages

Correlation IDs

Messages support correlation IDs for tracking handoff chains:

{
  "message_id": "msg_20251210_103045_abc123",
  "correlation_id": "sprint_M-S1",
  "from_agent": "sprint-executor",
  "to_inbox": "user",
  "title": "Sprint complete",
  "payload": "All milestones complete"
}

Benefits:

  • Track entire workflow: design-doc → sprint-plan → execution
  • Filter messages by workflow
  • Debug multi-agent interactions
  • Resume work from where you left off

For complete specification, see resources/message_format.md

Message Types (Payloads)

Completion Notification

{
  "type": "sprint_complete",
  "correlation_id": "sprint_M-S1",
  "payload": {
    "sprint_id": "M-S1",
    "milestones_complete": 5,
    "result": "All tests passing"
  }
}

Error Report

{
  "type": "error",
  "correlation_id": "sprint_M-S1",
  "payload": {
    "error": "Tests failing: 5 benchmarks broken",
    "details": ".ailang/state/logs/sprint-executor.log"
  }
}

Handoff Instruction

{
  "type": "plan_ready",
  "correlation_id": "sprint_M-S1",
  "payload": {
    "sprint_id": "M-S1",
    "plan_path": "design_docs/planned/M-S1-plan.md"
  }
}

Resources

Message Format Reference

See resources/message_format.md for complete message format specification.

Troubleshooting Guide

See resources/troubleshooting.md for common issues and solutions.

CLI Command Reference

Command Purpose
ailang messages list View all messages
ailang messages list --unread View only unread
ailang messages read MSG_ID View full message
ailang messages ack MSG_ID Mark as read
ailang messages ack --all Mark all as read
ailang messages unack MSG_ID Mark as unread
ailang messages send INBOX "msg" Send message
ailang messages send ... --envelope-code FILE Send with code envelope (v0.8.1+)
ailang messages send ... --envelope-context "desc" Send with context envelope (v0.8.1+)
ailang messages search "query" Semantic search
ailang messages search --space SLOT "query" Search specific envelope space (v0.8.1+)
ailang messages triage Cluster unread messages by similarity (v0.8.1+)
ailang messages dedupe Find duplicate messages
ailang messages reply MSG_ID "text" Reply to GitHub issue thread
ailang messages import-github Import from GitHub
ailang messages watch Watch for new messages
ailang messages cleanup Remove old messages

Aliases: msg is an alias for messages

ailang msg list        # Same as: ailang messages list

Package Coordination Messages (M-PKG-MSG)

Package-scoped messages use typed inbox addressing for multi-agent coordination:

Command Purpose
ailang pkg notify-upgrade sunholo/auth@0.2.0 Emit upgrade-available message
ailang pkg affected-by sunholo/auth List workspaces depending on package
ailang messages list --inbox pkg:sunholo/auth View package-scoped messages
ailang messages list --inbox workspace:docparse View workspace messages

Inbox addressing: pkg:vendor/name, workspace:name, team:name

Auto-emitted on publish: upgrade-available, interface-change-notice, effect-widening-warning

11 message kinds: upgrade-available, interface-change-notice, effect-widening-warning, compatibility-request, compatibility-report, contract-regression, migration-request, deprecation-notice, upgrade-complete, blocked, superseded

Lifecycle: open → acknowledged → in_progress → completed (or blocked/rejected/superseded)

Notes

  • Required by CLAUDE.md: Session start check is mandatory
  • SQLite backend: All messages in ~/.ailang/state/collaboration.db
  • Hook integration: SessionStart hook auto-imports GitHub issues and shows unread
  • Auto-marking: Messages marked as read when using ailang messages read
  • Message lifecycle: Unread → Read → Archived (optional)
  • GitHub sync: Optional, for bugs/features that need cross-instance visibility

Похожие навыки: agents

agent-memory-yamadashy-repomix

Use this skill when the user asks to save, remember, recall, or organize memories. Triggers on: 'remember this', 'save t...

Автор: yamadashy
21,427

openai-whisper-api

Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞

Автор: clawdbot
7,675

video-frames

Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞

Автор: clawdbot
7,675