Skip to main content

Interactive ↔ Autonomous Agent Bridge

Hand off work between interactive Claude Code sessions and autonomous AILANG agents. This page explains the bridge concept and gets you to a working handoff; the pages it links own the details.

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.

What It Does​

The workflow:

  1. Interactive: You explore with Claude Code, create design docs
  2. Handoff: Send a message to an agent inbox via ailang messages send
  3. Autonomous: Coordinator assigns the task, agents implement in isolated worktrees, every merge goes through human approval
  4. Notification: Your next session shows the completed work via the SessionStart hook

Quick Start​

In the AILANG repository the hooks (.claude/settings.json) and coordinator config are already set up. Elsewhere, follow the Hooks Setup Guide first.

# Start server + coordinator
make services-start

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

# Check inbox, then acknowledge
ailang messages list --unread
ailang messages ack --all

A Complete Handoff, End to End​

  1. Explore interactively — Claude Code investigates a failure and writes design_docs/planned/M-FIX-FACTORIAL.md.
  2. Hand off: 
    ailang messages send sprint-planner "Plan sprint for M-FIX-FACTORIAL" \
      --title "Sprint: M-FIX-FACTORIAL" --from "user"
  3. Autonomous pipeline — sprint-planner drafts a plan in a worktree; on your approval it merges and triggers sprint-executor, which implements with TDD and files its own approval request.
  4. Notified next session — the SessionStart hook surfaces the completion message in your inbox.
  5. Review: 
    ailang messages read <id>          # the agent's report
    ailang chains view <chain-id> --spans
    ailang chains diff <chain-id>      # the actual code changes

Where the Details Live​

TopicPage
Full messaging CLI (send/read/ack/forward/search)Agent Messaging
Hook configuration (HTTP + command hooks, auth)Hooks Setup
Coordinator: agents, pipelines, approvalsCoordinator Guide
Worked multi-agent workflowsAgent Workflows
Cross-repo messaging via GitHubAgent Messaging
Chains, costs, dashboard, tracingTelemetry

Practices that matter: one feature per design doc; descriptive message titles (Sprint: M-FIX-EVAL-FACTORIAL, not fix); review diffs before approving; --type bug auto-creates GitHub issues.

If It Doesn't Work​

curl http://127.0.0.1:1957/health   # server up?
ailang coordinator status           # coordinator running?
tail -f ~/.ailang/state/hooks.log   # hooks firing?

More in the Hooks Setup troubleshooting section.