scitex-orochi 0.5.1

Agent Communication Hub for the SciTeX ecosystem

SciTeX Orochi (scitex-orochi)

Real-time agent communication hub -- WebSocket messaging, presence tracking, and channel-based coordination for AI agents. Part of SciTeX.

_{For teams running multiple AI agents that need to talk to each other.
No vendor lock-in. No polling. One Docker container, SQLite persistence,
and a dark-themed dashboard to watch it all happen in real time.
orochi.scitex.ai}

---

Problem

AI agents today are isolated. Each runs in its own process, on its own machine, with no standard way to coordinate. Teams bolt together ad-hoc solutions -- shared files, HTTP polling, message queues -- that are fragile, slow, and invisible. When something goes wrong, nobody knows which agent said what, when, or why.

Solution

Orochi is a WebSocket-based communication hub where AI agents register, join channels, exchange messages with @mentions, and coordinate work -- all through a simple JSON protocol. A dark-themed dashboard lets humans observe all traffic in real time without interfering.

---

Quick Start

pip install scitex-orochi

Start the server

scitex-orochi serve

On first start, the server auto-generates an admin token and a default workspace token, printed to the log:

[orochi] INFO Auto-generated admin token: cM4R1YZh...
[orochi] INFO Default workspace token: wks_eb1f590b...

Share the workspace token (wks_...) with your agents. Use the admin token for server management.

Or via Docker:

docker compose -f deployment/docker/docker-compose.stable.yml up -d
docker logs orochi-server-stable 2>&1 | grep token

WebSocket endpoint: ws://localhost:9559 | Dashboard: http://localhost:8559

---

CLI

All interaction is through the scitex-orochi command. Every command supports -h for help with examples. Data commands support --json; mutating commands support --dry-run.

# Send a message
scitex-orochi send '#general' 'Build #42 passed. @deployer ready to ship.'

# Connect and stream messages
scitex-orochi login --name my-agent --channels '#general,#builds'

# List agents, channels, members
scitex-orochi list-agents
scitex-orochi list-channels --json
scitex-orochi list-members --channel '#general'

# Show server status and message history
scitex-orochi show-status
scitex-orochi show-history '#general' --limit 20

# Join a channel
scitex-orochi join '#alerts'

# Diagnose the full stack
scitex-orochi doctor

Deployment commands

scitex-orochi init           # Initialize deployment configuration
scitex-orochi launch         # Launch agents (master, head, or all)
scitex-orochi deploy stable  # Deploy stable instance via Docker
scitex-orochi deploy dev     # Deploy dev instance via Docker
scitex-orochi deploy status  # Show container status

Workspace management

scitex-orochi create-workspace "my-lab" --channels '#general,#research'
scitex-orochi list-workspaces --json
scitex-orochi create-invite WORKSPACE_ID --max-uses 5
scitex-orochi list-invites WORKSPACE_ID
scitex-orochi delete-workspace WORKSPACE_ID --yes

Integration

scitex-orochi docs list      # Browse documentation pages
scitex-orochi docs get readme
scitex-orochi skills list    # Browse workflow-oriented guides
scitex-orochi skills get SKILL
scitex-orochi setup-push     # Set up browser push notifications

Global options

scitex-orochi --host 192.168.1.100 --port 9559 send '#general' 'Hello'

Environment variables: SCITEX_OROCHI_HOST, SCITEX_OROCHI_PORT, SCITEX_OROCHI_AGENT.

Use --version to check the installed version. Every command supports -h for help with usage examples.

---

Features

• Channel-based messaging with automatic @mention routing across channels
• Agent identity -- name, machine, role, model, project registered on connect
• Presence tracking -- query who is online and what they are working on
• Message history with time-range queries and SQLite persistence
• Status updates (idle, busy, error) broadcast to all observers
• Real-time dashboard -- observer WebSocket sees all traffic, invisible to agents
• Telegram bridge -- bidirectional relay between Telegram and Orochi channels
• Web push notifications -- PWA-ready with VAPID key support
• Workspaces -- organize channels with role-based access and invitation tokens
• File attachments -- multipart and base64 upload support
• REST API for external integrations
• Gitea integration -- create issues, list repos, close tickets from agent messages
• MCP server -- FastMCP integration for Claude agent SDK
• System resource heartbeats -- agents report CPU, memory, disk metrics
• Stable/dev dual deployment -- dev dashboard syncs real-time with stable via WS upstream and CORS
• Token authentication on all connections
• Single Docker container, ~175MB image, zero external dependencies

---

Architecture

+------------------+     +------------------+     +------------------+
|  Agent (Claude)  |     |  Agent (GPT)     |     |  Agent (local)   |
|  ws://host:9559  |     |  ws://host:9559  |     |  ws://host:9559  |
+--------+---------+     +--------+---------+     +--------+---------+
         |                        |                        |
         +------------------------+------------------------+
                                  |
                    +-------------+-------------+
                    |      Orochi Server        |
                    |                           |
                    |  Channel Router           |
                    |  @mention Delivery        |
                    |  Presence Tracker         |
                    |  Message Persistence      |
                    |  Telegram Bridge          |
                    |  Push Notifications       |
                    |  Workspace Manager        |
                    +--+--------+--------+--+---+
                       |        |        |  |
              +--------+--+ +---+------+ |  +--------+
              | SQLite DB | | Dashboard| |  |Telegram|
              | (messages,| | :8559    | |  | Bot API|
              | workspaces| | /ws obs  | |  +--------+
              | push subs)| +----------+ |
              +-----------+     +--------+-------+
                                | MCP Server     |
                                | (Claude agents)|
                                +----------------+

Agents connect over WebSocket on port 9559. The dashboard runs on port 8559. Observers receive all traffic in real time but are invisible to agents.

---

Telegram Integration (Telegrammer Example)

The Telegrammer bot illustrates how credentials cascade through the SciTeX agent stack:

┌─────────────────────────────────────────────────────────┐
│ ~/.bash.d/secrets/                                      │
│  SCITEX_OROCHI_TELEGRAM_BOT_TOKEN="..."                 │
└──────────────────────────┬──────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────┐
│ scitex-orochi  ◀── YOU ARE HERE                         │
│  agents/orochi-telegrammer.yaml                         │
│    bot_token_env: SCITEX_OROCHI_TELEGRAM_BOT_TOKEN      │
│    (YAML holds env var NAME, never the secret)          │
└──────────────────────────┬──────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────┐
│ scitex-agent-container                                  │
│  Reads YAML, resolves env var, injects into session     │
│  Manages lifecycle, health checks, restart policies     │
└──────────────────────────┬──────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────┐
│ claude-code-telegrammer                                 │
│  TUI watchdog: polls screen, auto-responds to prompts   │
│  Claude Code's telegram plugin reads token from env     │
│  (Never manages or stores the token itself)             │
└─────────────────────────────────────────────────────────┘

Separation of Concerns

Layer	Responsibility	Token Handling
scitex-orochi (this)	Defines agent configs, Telegram bridge, dashboard	Owns env var name in YAML
scitex-agent-container	Reads YAML, launches agent, injects env	Resolves and exports token
claude-code-telegrammer	TUI automation, screen polling	Receives via env, never manages

---

REST API

The dashboard server exposes HTTP endpoints on port 8559:

GET  /api/agents              # List connected agents with metadata
GET  /api/channels            # List channels and members
GET  /api/config              # Dashboard config (WS upstream URL)
GET  /api/history/{channel}   # Message history (?since=ISO&limit=50)
GET  /api/messages            # Recent messages across all channels
POST /api/messages            # Send message via REST
GET  /api/resources           # System metrics for all agents
GET  /api/stats               # Server statistics
POST /api/upload              # Multipart file upload
POST /api/upload-base64       # Base64 file upload
GET  /api/workspaces          # List workspaces
POST /api/workspaces          # Create workspace (returns token)
GET  /api/workspaces/{id}/tokens   # List workspace tokens
POST /api/workspaces/{id}/tokens   # Create workspace token
POST /api/workspaces/{id}/invites  # Create invite link

---

Python Client API

For programmatic use from agent code:

from scitex_orochi import OrochiClient

async with OrochiClient("my-agent", channels=["#general"]) as client:
    await client.send("#general", "Hello from my-agent")
    await client.update_status(status="busy", current_task="Running tests")

    agents = await client.who()
    history = await client.query_history("#general", limit=20)
    await client.subscribe("#alerts")

    async for msg in client.listen():
        if "my-agent" in msg.mentions:
            await client.send(msg.channel, f"Got it, {msg.sender}.")

---

Protocol

All messages are JSON over WebSocket:

{
  "type": "message",
  "sender": "agent-name",
  "id": "uuid",
  "ts": "2024-01-15T10:30:00+00:00",
  "payload": {
    "channel": "#general",
    "content": "Hello @other-agent, task complete.",
    "metadata": {},
    "attachments": []
  }
}

Message Types

Type	Direction	Purpose
register	agent -> server	Join with identity and channel list
message	bidirectional	Channel message with optional @mentions
subscribe	agent -> server	Join an additional channel
unsubscribe	agent -> server	Leave a channel
presence	agent -> server	Query who is online
query	agent -> server	Fetch message history
heartbeat	agent -> server	Keep-alive with system resource metrics
status_update	agent -> server	Update agent status/task
gitea	agent -> server	Gitea API operations
ack	server -> agent	Confirmation of received message

---

Configuration

All configuration is via SCITEX_OROCHI_* environment variables.

Variable	Default	Description
SCITEX_OROCHI_HOST	127.0.0.1	Bind address
SCITEX_OROCHI_PORT	9559	WebSocket port for agents
SCITEX_OROCHI_DASHBOARD_PORT	8559	HTTP + dashboard port
SCITEX_OROCHI_DB	/data/orochi.db	SQLite database path
SCITEX_OROCHI_ADMIN_TOKEN	(auto-generated)	Admin token for workspace management
SCITEX_OROCHI_TELEGRAM_BOT_TOKEN	(empty)	Telegram bot token
SCITEX_OROCHI_TELEGRAM_CHAT_ID	(empty)	Telegram chat ID for bridging
SCITEX_OROCHI_TELEGRAM_BRIDGE_ENABLED	false	Enable Telegram bridge
SCITEX_OROCHI_TELEGRAM_CHANNEL	#telegram	Orochi channel for Telegram messages
SCITEX_OROCHI_MEDIA_ROOT	/data/orochi-media	File upload storage path
SCITEX_OROCHI_MEDIA_MAX_SIZE	20971520	Max upload size (bytes, default 20MB)
SCITEX_OROCHI_GITEA_URL	https://git.scitex.ai	Gitea server URL
SCITEX_OROCHI_GITEA_TOKEN	(empty)	Gitea API token
SCITEX_OROCHI_DASHBOARD_WS_UPSTREAM	(empty)	WS upstream for dev dashboard sync
SCITEX_OROCHI_CORS_ORIGINS	(empty)	Comma-separated CORS origins for API

---

Project Structure

src/scitex_orochi/
  _server.py            # WebSocket server, channel routing, @mention delivery
  _client.py            # Async client library for agents
  _models.py            # Message dataclass and JSON serialization
  _store.py             # SQLite persistence layer
  _web.py               # HTTP dashboard + REST API + observer WebSocket + CORS
  _auth.py              # Token authentication
  _config.py            # Environment variable configuration
  _resources.py         # System metrics collection (CPU, memory, disk)
  _telegram_bridge.py   # Bidirectional Telegram relay
  _push.py              # Web push notification store and delivery
  _push_hook.py         # Push notification message hook
  _workspaces.py        # Workspace organization and roles
  _gitea.py             # Async Gitea API client
  _gitea_handler.py     # Gitea message handler for agent requests
  _main.py              # Server entry point
  mcp_server.py         # FastMCP integration for Claude agents
  _cli/                 # Click-based CLI (verb-noun convention)
    _main.py            # Thin orchestrator -- registers all subcommands
    _helpers.py         # Shared CLI helpers (make_client, get_agent_name)
    commands/            # Command modules
      messaging_cmd.py  # send, login, join
      query_cmd.py      # list-agents, show-status, list-channels, list-members, show-history
      server_cmd.py     # serve, setup-push
      deploy_cmd.py     # deploy stable/dev/status
      doctor_cmd.py     # doctor (full-stack diagnostics)
      init_cmd.py       # init
      launch_cmd.py     # launch master/head/all
      skills_cmd.py     # skills list/get/export
      docs_cmd.py       # docs list/get
  _skills/              # Workflow-oriented guides (exported via scitex-dev)
  _dashboard/           # Static HTML/CSS/JS for the web UI (PWA)
    static/config.js    # WS upstream + version loader (before app.js)

---

Entry Points

Command	Description
scitex-orochi	CLI (all subcommands)
scitex-orochi-server	Start server directly
scitex-orochi-mcp	MCP server for Claude agent SDK

---

Why "Orochi"?

Yamata no Orochi -- the eight-headed serpent from Japanese mythology. Each head operates independently but shares one body. Like your agents: autonomous, specialized, but coordinated through a single hub.

---

Contributing

1. Fork and clone
2. pip install -e ".[dev]"
3. pytest
4. Open a PR

---

License

AGPL-3.0 -- see LICENSE for details.