Interactive ↔ Autonomous Agent Bridge

Seamlessly hand off work between Claude Code sessions and autonomous AILANG agents with production-grade reliability.

The Main Human-AILANG Interface

This is the primary way humans interact with AILANG—through Claude Code for exploration and autonomous agents for execution.

Ready to Use in AILANG Repo!

Already working in the AILANG repository? The hooks are configured and ready to go!

Pragmatic Workflow

SessionStart hooks run successfully but output doesn't reliably appear in Claude's context. Manual checking works well: Ask Claude to run ailang agent inbox --unread-only claude-code at the start of each session.

Test commands:

# Send test message
ailang agent send --to-user '{"message": "Test", "status": "ready"}'

# Check inbox (FLAGS BEFORE AGENT ID!)
ailang agent inbox --unread-only user
ailang agent inbox --unread-only claude-code

# Acknowledge messages
ailang agent ack --all

See Hooks Setup Guide for more details. :::

What It Does

The workflow:

Interactive: You explore with Claude Code, create design docs
Handoff: Stop session → agents receive the work automatically
Autonomous: Agents implement, test, and report back
Notification: Next session shows completed work in your inbox

Quick Start

Prerequisites

AILANG installed (ailang --version) Claude Code or VSCode with Claude extension Basic familiarity with hooks

Already configured in AILANG repo!

If you're working in the AILANG repository, the hooks are already configured in .claude/hooks.json. Skip to Step 3 to test them!

Installation (3 Steps)

Step 1: Enable hooks in Claude Code

Create .claude/hooks.json:

.claude/hooks.json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash scripts/hooks/agent_handoff.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash scripts/hooks/session_start.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Step 2: Make hooks executable

chmod +x scripts/hooks/*.sh

Step 3: Test the integration

# Send a test message to your inbox
ailang agent send --to-user '{"message": "Integration test", "status": "success"}'

# Check your inbox
ailang agent inbox user

It works!

You should see the test message in your inbox. Now you're ready to use the full workflow!

CLI Commands Reference

Send Messages

To User Inbox
To Agent
With Correlation ID

# Send notification to user
ailang agent send --to-user '{"message": "Task complete", "status": "success"}'

# Send task to sprint-planner
ailang agent send sprint-planner '{"task": "implement_design_doc", "design_doc": "design_docs/planned/M-FIX-123.md"}'

# Track related messages
ailang agent send --correlation-id "M-FIX-123" sprint-planner '{"task": "plan"}'

Check Inbox

User Inbox
Agent Inbox

# Check your messages
ailang agent inbox user

# Only unread
ailang agent inbox user --unread-only

# Archive after viewing
ailang agent inbox user --archive

# Check agent's pending messages
ailang agent inbox sprint-planner

# Limit results
ailang agent inbox sprint-planner --limit 5

Monitor System

# Show agent status and metrics
ailang agent top

# View dead letter queue
ailang agent dlq --list

# Retry failed message
ailang agent dlq --retry <message-id>

Debug & Utilities

# Compute file hash (for artifacts)
ailang debug hash design_docs/planned/M-FIX-123.md

# Output: sha256:a1b2c3d4e5f6...

Complete Workflow Example

Scenario: Fix Eval Failure

1. Interactive Exploration (Claude Code)

You: "Analyze the failing evals and create a design doc"

Claude Code investigates and creates:

design_docs/planned/M-FIX-FACTORIAL.md

You: "Looks good!" (session stops)

2. Automatic Handoff (Stop Hook)

The agent_handoff.sh hook automatically:

Detects the new design doc (modified < 5 min)
Stores it as a content-addressed artifact
Sends message to sprint-planner agent

What happens behind the scenes
# Hook detects design doc
DOC_HASH=$(ailang debug hash design_docs/planned/M-FIX-FACTORIAL.md)

# Sends message with artifact reference
ailang agent send sprint-planner '{
  "task": "implement_design_doc",
  "artifacts": [{
    "path": "design_docs/planned/M-FIX-FACTORIAL.md",
    "hash": "sha256:abc123..."
  }]
}'

3. Autonomous Execution (Agents)

sprint-planner receives message → creates implementation plan
sprint-executor receives plan → implements fix
Agents run tests, lint code, update docs
Completion message sent to user inbox

4. User Notification (SessionStart Hook)

Next time you start Claude Code, the SessionStart hook runs automatically and:

What you see (in terminal):

╔═══════════════════════════════════════════════════════════╗
║  📬 You have 1 unread message(s) from agents              ║
╚═══════════════════════════════════════════════════════════╝

To view messages, run:
  ailang agent inbox user

What Claude Code sees (after forwarding): The hook also forwards messages to .ailang/state/messages/claude-code/ inbox.

Important: Claude Can't See Messages Automatically

Due to Claude Code's architecture, hooks output to the terminal but cannot inject content into the AI's context.

To make Claude aware of messages:

Tell Claude: "Check for agent messages" or "Any messages from agents?"
Claude will then read .ailang/state/messages/claude-code/ inbox
Or Claude runs the session start routine automatically (if configured in CLAUDE.md)

Check messages:

View in Terminal
Show to Claude

# View your inbox (human-readable)
ailang agent inbox user

# Make messages visible to Claude Code assistant
ailang agent inbox user

Example output:

📬 User Inbox (1 message)
================================================================================

▶ Message 1/1
  ID: msg_20251025_143256_a1b2c3d4
  From: sprint-executor
  Type: completion
  Timestamp: 2025-10-25T14:32:56Z
  Payload: {
    "status": "success",
    "message": "Implemented M-FIX-FACTORIAL",
    "tests_passing": true,
    "files_modified": 3
  }

Production Features

Content-Addressed Artifacts

Large files (design docs, code) are stored separately and referenced by SHA256 hash:

{
  "artifacts": [
    {
      "path": "design_docs/planned/M-FIX-123.md",
      "hash": "sha256:a1b2c3d4e5f6...",
      "mime_type": "text/markdown"
    }
  ]
}

Benefits:

Deduplication (same file stored once)
Verification (detect corruption)
No message bloat

HMAC Message Signing

All messages are cryptographically signed to prevent spoofing:

{
  "message_id": "msg_123",
  "signature": "hmac-sha256:...",
  "kid": "key-001",
  "hmac_alg": "sha256"
}

Security:

Agent allowlist enforcement
Key rotation support
Tamper detection

Idempotent Delivery

Messages are processed exactly once, even if systems restart:

-- Each message_id is unique in SQLite
CREATE UNIQUE INDEX idx_message_id ON processed_messages(message_id);

Guarantees:

No duplicate work
Safe restarts
Crash recovery

Dead Letter Queue

Failed messages are captured with full diagnostic context:

# List failures
ailang agent dlq --list

# Example output:
DLQ Entry 1/2
  Message ID: msg_456
  Failed At: 2025-10-25T14:30:00Z
  Retry Count: 3
  Reason: agent_not_found
  Stack Trace: [...]

Recovery:

# Retry after fixing the issue
ailang agent dlq --retry msg_456

User Inbox Lifecycle

Messages flow through three states:

Example workflow:

# New messages appear in _unread/
ailang agent inbox user
# → Displays messages, moves to _read/

# Archive old messages
ailang agent inbox user --read-only --archive
# → Moves from _read/ to _archive/

Observability

Monitor the agent system in real-time:

ailang agent top

Example output:

AILANG Agent Status
================================================================================

Active Agents:
  • sprint-planner
    Status: active
    Last Heartbeat: 5s ago
    Pending Messages: 2
    Processed (last 1h): 15
    Errors (last 1h): 0

  • sprint-executor
    Status: active
    Last Heartbeat: 3s ago
    Pending Messages: 0
    Processed (last 1h): 12
    Errors (last 1h): 1

Dead Letter Queue: 1 message
Average Handoff Latency: 3.2s
Messages In (last 1h): 27
Messages Out (last 1h): 25

⚙️ Hook Configuration

Stop Hook (`agent_handoff.sh`)

What it does:

Detects design docs modified in last 5 minutes
Computes SHA256 hash for each doc
Stores as artifact
Sends message to sprint-planner

Configuration:

scripts/hooks/agent_handoff.sh
# Customize these variables
DESIGN_DOCS_DIR="design_docs/planned"
TARGET_AGENT="sprint-planner"
TIME_WINDOW=5  # minutes

SessionStart Hook (`session_start.sh`)

What it does:

Checks user inbox for unread messages
Displays count and preview
Guides user to ailang agent inbox user

Configuration:

scripts/hooks/session_start.sh
INBOX_DIR=".ailang/state/messages/inbox/user/_unread"

Success Metrics

From the design document (M-CLAUDE-CODE-INTEGRATION-V2):

Metric	Target	Status
Handoff latency (median)	<5s	Achieved
Message delivery	100%	Soak tested
Artifact storage	Hash-addressed	Implemented
Security	HMAC signed	Enabled
Test coverage	>90%	100% on new code

Testing the Integration

Test 1: Send & Receive

# Send test message
ailang agent send --to-user '{"test": "Integration check"}'

Output:

✓ Message sent successfully
  Message ID: msg_20251025_115551_f4d475e9e816
  To: user
  From: cli-sender
  Correlation ID: cycle_20251025_715
  File: ~/.ailang/state/messages/inbox/user/_unread/msg_...json

# Check inbox
ailang agent inbox user

Output:

📬 User Inbox (1 message)
================================================================================

▶ Message 1/1
  ID: msg_20251025_115551_f4d475e9e816
  From: cli-sender
  Type: request
  Timestamp: 2025-10-25T13:55:51Z
  Correlation: cycle_20251025_715
  Payload: {"test":"Integration check"}

Success! Message sent and received

Test 2: Hook Detection

# Create a test design doc
mkdir -p design_docs/planned
cat > design_docs/planned/test-doc.md << 'EOF'
# Test Design Doc
This is a test.
EOF

# Manually trigger the hook
bash scripts/hooks/agent_handoff.sh

# Check agent inbox
ailang agent inbox sprint-planner

Expected: Message sent to sprint-planner

Test 3: SessionStart Hook

# Trigger the SessionStart hook (simulates starting Claude Code)
bash scripts/hooks/session_start.sh

Output (when you have unread messages):

╔═══════════════════════════════════════════════════════════╗
║  📬 You have 1 unread message(s) from agents              ║
╚═══════════════════════════════════════════════════════════╝

To view messages, run:
  ailang agent inbox user

Preview (most recent):
  From: cli-sender
  Message ID: msg_20251025_115551_f4d475e9e816

Success! Hook notifies you of new messages

Test 4: End-to-End Workflow

Full workflow in the AILANG repository:

Create design doc in Claude Code session
Stop session (triggers Stop hook automatically)
Check sprint-planner inbox: ailang agent inbox sprint-planner
Start new session (triggers SessionStart hook automatically)
See notification and check user inbox

Troubleshooting

Hook not firing

Check hook logs:

tail -f ~/.ailang/state/hooks.log

Verify hook permissions:

ls -la scripts/hooks/*.sh
# Should show: -rwxr-xr-x (executable)

Test hook manually:

export CLAUDE_HOOK_JSON='{"sessionId": "test", "userId": "user", "event": "Stop"}'
bash scripts/hooks/agent_handoff.sh

Messages not appearing in inbox

Check message delivery:

# List all pending messages for user
ls -la .ailang/state/messages/inbox/user/_unread/

Verify state directory:

# Should exist with correct structure
ls -la .ailang/state/messages/inbox/user/
# → _unread/ _read/ _archive/

Agent not processing messages

Check agent status:

ailang agent top

View DLQ for failures:

ailang agent dlq --list

Hooks Setup Guide - Quick setup and configuration guide
Agent Workflows - Workflow examples and patterns

Design documents (GitHub):

M-CLAUDE-CODE-INTEGRATION-V2 - Complete design document
M-AGENT-PROTOCOL - Low-level protocol details

Best Practices

Keep design docs focused - One feature per doc
Use descriptive names - M-FIX-EVAL-FACTORIAL.md not fix.md
Review agent output - Check user inbox regularly
Monitor metrics - Run ailang agent top periodically
Archive old messages - Keep inbox manageable

Pro Tip

The agent system is production-ready with 100% delivery guarantees, HMAC signing, and comprehensive testing. Use it with confidence!

Next Steps:

Try it now: Create a design doc and stop your Claude Code session
Customize hooks: Modify scripts/hooks/*.sh for your workflow
Build agents: Create custom agents using the Agent Protocol

Questions?

GitHub Issues: https://github.com/sunholo-data/ailang/issues
Documentation: https://sunholo-data.github.io/ailang/

What It Does​

Quick Start​

Prerequisites​

Installation (3 Steps)​

CLI Commands Reference​

Send Messages​

Check Inbox​

Monitor System​

Debug & Utilities​

Complete Workflow Example​

Scenario: Fix Eval Failure​

Production Features​

Content-Addressed Artifacts​

HMAC Message Signing​

Idempotent Delivery​

Dead Letter Queue​

User Inbox Lifecycle​

Observability​

⚙️ Hook Configuration​

Stop Hook (agent_handoff.sh)​

SessionStart Hook (session_start.sh)​

Success Metrics​

Testing the Integration​

Test 1: Send & Receive​

Test 2: Hook Detection​

Test 3: SessionStart Hook​

Test 4: End-to-End Workflow​

Troubleshooting​

Hook not firing​

Messages not appearing in inbox​

Agent not processing messages​

Related Documentation​

Best Practices​