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 the Coordinator for autonomous execution.

Ready to Use in AILANG Repo!

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

Quick test:

# Start server + coordinator
make services-start

# Send test message
ailang messages send user "Test message" --title "Integration test" --from "claude-code"

# Check inbox
ailang messages list --unread

# Acknowledge
ailang messages ack --all

See Hooks Setup Guide for HTTP hook details.

What It Does

The workflow:

Interactive: You explore with Claude Code, create design docs
Handoff: Send a message to an agent inbox via ailang messages send
Autonomous: Coordinator assigns task, agents implement in isolated worktrees
Notification: Next session shows completed work via SessionStart hook

Quick Start

Prerequisites

AILANG installed (ailang --version) Claude Code or VSCode with Claude extension Coordinator configured (~/.ailang/config.yaml)

Already configured in AILANG repo!

If you're working in the AILANG repository, hooks are configured in .claude/settings.json and the coordinator config is ready. Skip to testing!

Setup (3 Steps)

Step 1: Configure hooks in .claude/settings.json

HTTP hooks are configured alongside command hooks:

.claude/settings.json (excerpt)
{
  "hooks": {
    "SessionStart": [{
      "hooks": [
        {
          "type": "command",
          "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/hooks/session_start.sh"
        },
        {
          "type": "http",
          "url": "http://127.0.0.1:1957/api/hooks/claude",
          "timeout": 5
        }
      ]
    }],
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "http",
        "url": "http://127.0.0.1:1957/api/hooks/claude",
        "timeout": 5
      }]
    }]
  }
}

Step 2: Start the server and coordinator

make services-start    # Starts ailang serve + coordinator daemon

Step 3: Test the integration

# Send a test message
ailang messages send user "Integration test" --title "Test" --from "claude-code"

# Check inbox
ailang messages list --unread

# Acknowledge
ailang messages ack --all

It works!

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

CLI Commands Reference

Send Messages

To User Inbox
To Agent
Bug Report

# Send notification to user
ailang messages send user "Task complete" --title "Done" --from "agent-name"

# Send task to sprint-planner
ailang messages send sprint-planner "Plan sprint for M-FIX-123" \
  --title "Sprint: M-FIX-123" --from "user"

# Bug report (auto-creates GitHub issue)
ailang messages send user "Parser crashes on empty input" \
  --type bug --title "Bug: Parser crash" --from "user"

Check Inbox

User Inbox
Agent Inbox

# Check your messages
ailang messages list --unread

# Read specific message
ailang messages read <message-id>

# Read without marking as read
ailang messages read <message-id> --peek

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

# JSON output (for scripting)
ailang messages list --inbox sprint-planner --json

Manage Messages

# Acknowledge (mark as read)
ailang messages ack <id>              # Single message
ailang messages ack --all             # All messages

# Un-acknowledge (move back to unread for retry)
ailang messages unack <id>

# Forward to different inbox
ailang messages forward --to design-doc-creator <id>

# Cleanup old messages
ailang messages cleanup --older-than 7d
ailang messages cleanup --expired

Monitor System

# Coordinator status
ailang coordinator status

# View execution chains
ailang chains list --since 24h
ailang chains active

# View chain details
ailang chains view <chain-id> --spans
ailang chains tree <chain-id> --detailed

# Cost and token stats
ailang chains stats --by-agent

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! Send to sprint-planner"

2. Send to Coordinator Pipeline

ailang messages send sprint-planner "Plan sprint for M-FIX-FACTORIAL" \
  --title "Sprint: M-FIX-FACTORIAL" --from "user"

3. Autonomous Execution (Coordinator)

The coordinator handles the pipeline automatically:

sprint-planner receives message → creates sprint plan in worktree
Human approves plan → merges to dev, triggers sprint-executor
sprint-executor implements fix with TDD → creates approval request
Human reviews code → approves merge

4. User Notification (SessionStart Hook)

Next time you start Claude Code:

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

ID: abc12345-...
From: sprint-executor
Title: Implementation complete: M-FIX-FACTORIAL
Time: 2026-03-05T14:30:00Z
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💡 Use 'ailang messages read <id>' to view full content

5. Review:

# Read message details
ailang messages read abc12345

# View execution chain
ailang chains list --agent sprint-executor --since 24h
ailang chains view <chain-id> --spans

# View code changes
ailang chains diff <chain-id>

Production Features

HTTP Hook Telemetry

All Claude Code events (tool use, session lifecycle, subagent activity) are captured via HTTP hooks and stored in the observatory:

{
  "type": "http",
  "url": "http://127.0.0.1:1957/api/hooks/claude",
  "headers": {
    "X-Ailang-Task-Id": "${AILANG_TASK_ID}",
    "X-Ailang-Chain-Id": "${AILANG_CHAIN_ID}"
  },
  "timeout": 5
}

Benefits:

No shell script dependencies (cloud-ready)
Full JSON payload storage
Real-time dashboard via WebSocket
Correlation ID tracking across chains

Hook Token Authentication

For cloud deployments, secure the hook endpoint:

# Set token on the server
export AILANG_HUB_TOKEN="your-secret-token"
ailang serve

When configured, hooks must include Authorization: Bearer <token>. In local mode (no token set), all requests pass through.

Coordinator Approval Workflow

Every agent task goes through human review:

# List pending approvals
ailang coordinator pending

# Interactive review
# a=approve  r=reject  d=diff  c=chat  q=quit

Approval types:

Type	On Approve
`merge`	Merges code to dev branch
`merge_handoff`	Merges AND triggers next agent

Message Storage

All messages stored in SQLite (~/.ailang/state/collaboration.db):

Shared between CLI, dashboard, and coordinator
Full-text and semantic search
GitHub issue sync
Deduplication support

Observability

Chain Monitoring

# View all execution chains
ailang chains list --since 7d

# Active chains
ailang chains active

# Chain details with spans
ailang chains view <chain-id> --spans

# Cost tracking
ailang chains stats --by-agent --hours 168

Dashboard

make services-start
# Open http://localhost:1957

Features:

Live task execution streaming
Approval queue with git diff viewer
Session monitoring via HTTP hooks
Cost and token tracking

Audit Agent Work

# View conversation (reasoning + tool calls)
ailang coordinator logs <task-id> --limit 500

# View git changes
ailang chains diff <chain-id>

# Quick health check
ailang chains diagnose <chain-id>

⚙️ Hook Configuration

HTTP Hooks (Primary)

HTTP hooks send Claude Code events to the AILANG server for telemetry and monitoring. They fire for all 7 event types: SessionStart, PreToolUse, PostToolUse, PostToolUseFailure, SubagentStart, SubagentStop, Stop.

See Hooks Setup Guide for full configuration.

Command Hooks (Supplementary)

These command hooks run alongside HTTP hooks:

Hook	Script	Purpose
SessionStart	`session_start.sh`	Check inbox, set up environment
SessionStart	`cloud_setup.sh`	Cloud environment setup
PostToolUse	`format_go.sh`	Auto-format Go files on Edit/Write
Stop	`session_end_speak.sh`	Text-to-speech session summary

Troubleshooting

Messages not appearing

# Check server is running
curl http://127.0.0.1:1957/health

# Check database
ailang messages list --unread

# Send test message
ailang messages send user "test" --title "Test" --from "debug"

Coordinator not picking up tasks

# Check coordinator is running
ailang coordinator status

# Start if not running
ailang coordinator start

# Check config
cat ~/.ailang/config.yaml

Hooks not firing

# Check hook logs
tail -f ~/.ailang/state/hooks.log

# HTTP hooks fail silently - check server is running
curl http://127.0.0.1:1957/health

Getting Started — Installation and first steps
Hooks Setup Guide — HTTP hook configuration
Agent Workflows — Workflow examples and patterns
Coordinator Guide — Agent orchestration and task delegation
Cross-Project Messaging — Inter-project communication
Telemetry Guide — Distributed tracing and observability

Best Practices

Keep design docs focused — One feature per doc
Use descriptive message titles — Sprint: M-FIX-EVAL-FACTORIAL not fix
Review agent output — Check inbox regularly, review diffs before approving
Monitor chains — Run ailang chains active to track progress
Use GitHub sync for bugs — --type bug auto-creates GitHub issues

Next Steps:

Try it now: Send a message to sprint-planner and watch the pipeline
Monitor: Open http://localhost:1957 for the dashboard
Customize: Edit ~/.ailang/config.yaml for your agent configuration

Questions?

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

What It Does​

Quick Start​

Prerequisites​

Setup (3 Steps)​

CLI Commands Reference​

Send Messages​

Check Inbox​

Manage Messages​

Monitor System​

Complete Workflow Example​

Scenario: Fix Eval Failure​

Production Features​

HTTP Hook Telemetry​

Hook Token Authentication​

Coordinator Approval Workflow​

Message Storage​

Observability​

Chain Monitoring​

Dashboard​

Audit Agent Work​

⚙️ Hook Configuration​

HTTP Hooks (Primary)​

Command Hooks (Supplementary)​

Troubleshooting​

Messages not appearing​

Coordinator not picking up tasks​

Hooks not firing​

Related Documentation​

Best Practices​