Skip to main content

Cross-Project Messaging Guide

Send improvement requests, bug reports, and feedback from your AILANG-using project back to AILANG core.

This enables a feedback loop where projects using AILANG can automatically report issues, request features, and suggest improvements that get routed to AILANG developers.

Quick Start​

From any project with AILANG installed, send a message to the global user inbox:

ailang messages send user "Your feedback here" \
  --title "Improvement request" \
  --from "your-project-name"

That's it! The message is stored in ~/.ailang/state/collaboration.db and will be picked up by AILANG developers in their next session.

With GitHub Sync​

For visibility across all AILANG instances, sync to GitHub Issues:

# Bug report (creates GitHub issue with "bug" label)
ailang messages send user "Parser crashes on nested records" \
  --title "Parser bug" --from "your-project" --type bug --github

# Feature request
ailang messages send user "Need async/await support" \
  --title "Async support" --from "your-project" --type feature --github

Message Types​

Use the --type flag for automatic categorization:

TypeUse ForGitHub Label
bugSomething brokenRed
featureFeature suggestionsCyan
generalOther feedbackLight blue

Full Message Format​

For structured feedback, include these fields:

ailang messages send user "When a string literal spans multiple lines, the parser loses track of line numbers. Expected: parse successfully. Actual: Parser error at line -1. Version: 0.4.7, macOS 14.2" \
  --title "Parser fails on multi-line strings" \
  --from "game-engine-project" \
  --type bug \
  --github

The message payload can contain any text including JSON if you need structured data.

Examples​

Report a Bug​

ailang messages send user "Type inference fails on recursive ADTs. Code: type Tree = Leaf(int) | Node(Tree, Tree). Error: cannot unify Tree with Tree" \
  --title "Type inference fails on recursive ADTs" \
  --from "my-compiler-project" \
  --type bug \
  --github

Request a Feature​

ailang messages send user "Building a web framework and need non-blocking IO. Current effect system requires explicit continuation passing." \
  --title "Add async/await syntax" \
  --from "web-framework" \
  --type feature \
  --github

Report Compatibility Issue​

ailang messages send user "Binary crashes with SIGILL on startup on Ubuntu 22.04 ARM64 (Graviton3). AILANG version: 0.4.7" \
  --title "Binary crashes on Ubuntu 22.04 ARM64" \
  --from "ci-pipeline" \
  --type bug \
  --github

Suggest Documentation Improvement​

ailang messages send user "The teaching prompt has basic ADT examples but lacks complex nested pattern matching examples. Students struggle with this." \
  --title "Need more ADT examples" \
  --from "tutorial-project" \
  --type feature

GitHub Configuration​

For GitHub sync to work, create ~/.ailang/config.yaml:

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

Prerequisites​

  1. Install GitHub CLI: brew install gh (macOS) or see cli.github.com
  2. Authenticate: gh auth login
  3. Verify account: gh auth status
  4. Switch if needed: gh auth switch --user YourUsername

How Messages Are Processed​

  1. You send a message from your project
  2. Message stored in SQLite (~/.ailang/state/collaboration.db)
  3. Optionally synced to GitHub Issues if --github flag used
  4. AILANG developer starts a Claude Code session
  5. SessionStart hook checks for unread messages and imports GitHub issues
  6. Developer reviews and decides on action
  7. Message acknowledged with ailang messages ack <message-id>

Message Lifecycle​

Your Project                    AILANG Core
    |                               |
    |  ailang messages send user    |
    |-------------------------------&gt;|
    |                               |
    |              collaboration.db (SQLite)
    |                               |
    |  --github flag (optional)     |
    |-------------------------------&gt;|
    |              GitHub Issue #42 |
    |                               |
    |                    [SessionStart hook fires]
    |                               |
    |                    [import-github runs]
    |                               |
    |                    [Developer sees message]
    |                               |
    |                    [Issue fixed / closed]
    |                               |
    |              ailang messages ack
    |                               |
    |              status: read     |

Checking Messages​

View messages from the AILANG core project:

# All messages
ailang messages list

# Only unread
ailang messages list --unread

# From specific sender
ailang messages list --from your-project-name

# Full JSON output
ailang messages list --json

Storage​

Messages are stored in a SQLite database (not files):

~/.ailang/state/
└── collaboration.db       # Unified database
    ├── inbox_messages     # All messages
    └── schema_version     # Database version

This database is shared between:

  • CLI (ailang messages)
  • Collaboration Hub dashboard
  • All AILANG instances on the machine

Best Practices​

  1. Be specific - Include version numbers, OS, and exact error messages
  2. Include reproducible examples - Code that demonstrates the issue
  3. Use --type appropriately - bug for broken things, feature for requests
  4. Use consistent project names - Makes it easy to track feedback sources
  5. Include context - What you're building helps prioritize fixes
  6. Use --github for important issues - Creates visibility across all AILANG instances

Automated Feedback (Advanced)​

Set up automatic feedback when your CI/CD detects AILANG issues:

#!/bin/bash
# In your CI pipeline

# Run AILANG tests
if ! ailang run --caps IO --entry main tests/integration.ail 2>error.log; then
    # Send failure report
    ERROR=$(cat error.log | head -50)
    VERSION=$(ailang --version)
    OS=$(uname -a)

    ailang messages send user "CI failure: $ERROR. Version: $VERSION, OS: $OS" \
      --title "CI failure on $(git rev-parse --short HEAD)" \
      --from "my-project-ci" \
      --type bug \
      --github
fi

Find messages by meaning, not just exact text. AILANG uses SimHash by default for fast, free semantic search:

# Search messages
ailang messages search "parser error handling"

# Use neural search (requires Ollama running locally)
ailang messages search "type inference bugs" --neural

# Find similar messages
ailang messages list --similar-to MSG_ID

# Hide duplicates
ailang messages list --collapsed

For neural search, configure Ollama in ~/.ailang/config.yaml:

embeddings:
  provider: ollama
  ollama:
    model: nomic-embed-text
    endpoint: http://localhost:11434

See Agent Messaging - Neural Embeddings for full setup.