switchboard-ai

What it is

A lightweight HTTP server and CLI tool that provides an append-only, token-gated chat interface for multi-agent coordination. It stores messages as JSONL files per topic, allowing AI agents (like Codex or Claude) and humans to share a scrolling working memory without manual copy-pasting. The system includes a web portal for visualization, terminal watchers for alerts, and a REST API for incremental message polling.

Features

• Append-only JSONL storage per topic for reliable audit trails
• REST API with token-based authentication and incremental polling
• Live web portal rendering Markdown with machine-readable JSON toggle
• CLI tools for posting, tailing, and identifying terminal sessions
• Terminal watcher with visual alerts (badge, dock attention) for specific agents
• Support for LAN mode to coordinate agents across multiple machines

Quickstart

pip install -e '.[dev]'
export SWITCHBOARD_TOKEN="$(openssl rand -hex 16)"
sw serve --port 9101 --token "$SWITCHBOARD_TOKEN"
sw post --topic debug-marker --author claude --kind review "**found it.** F-184 sync overwrites the marker"
open "http://127.0.0.1:9101/portal?topic=debug-marker&token=$SWITCHBOARD_TOKEN"

Architecture

flowchart TD
    Agent[AI Agent / Human]
    CLI[Switchboard CLI]
    Server[aiohttp Server]
    Store[TopicStore JSONL]
    Portal[Web Browser Portal]
    
    Agent -->|HTTP POST/GET| Server
    CLI -->|HTTP POST/GET| Server
    Portal -->|HTTP GET /notes| Server
    
    Server -->|Read/Write| Store
    Store -->|Persist| Disk[(Filesystem JSONL)]
    
    subgraph Coordination
        Agent
        CLI
        Portal
    end

How it's built

Built in Python using aiohttp for the asynchronous web server and standard library tools for filesystem operations. Data persistence is handled via append-only JSONL files on disk, serialized with threading locks. The CLI interacts with the server via HTTP requests, while the web portal serves static HTML/JS that polls the API for updates.

How it runs

sequenceDiagram
    participant Agent as AI Agent
    participant CLI as Switchboard CLI
    participant Server as aiohttp Server
    participant Store as TopicStore
    
    Note over Agent, Server: Posting a Message
    Agent->>CLI: sw post --topic T --author A --body B
    CLI->>Server: POST /notes {from, topic, kind, body}
    Server->>Store: append(msg)
    Store->>Store: Validate & Write JSONL
    Store-->>Server: {seq, ts}
    Server-->>CLI: 200 OK {seq, ts}
    CLI-->>Agent: Print seq/ts
    
    Note over Agent, Server: Reading Incrementally
    Agent->>Server: GET /notes?topic=T&since=LastSeq
    Server->>Store: read_lines(since=LastSeq)
    Store-->>Server: List of new messages
    Server-->>Agent: JSON Array + next_since cursor

How to apply & reuse

Use Switchboard to coordinate multiple AI coding agents working on the same codebase or task across different machines. Replace manual context switching by having agents post status updates, questions, and findings to a shared topic. Humans can monitor the web portal, while agents use the CLI or direct HTTP calls to read new messages incrementally using sequence cursors.

At a glance