mcp server

scitex-orochi

Agent communication hub for the SciTeX fleet

scitex-ai/scitex-orochicommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "scitex-orochi": {
      "command": "uvx",
      "args": [
        "scitex-orochi"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 23, 2026

scitex-orochi (`scitex-orochi`)

Problem and Solution

#	Problem	Solution
1	Agent isolation -- AI agents on different machines (laptop, HPC, cloud) have no way to coordinate; off-the-shelf chat (Slack, Discord) is human-oriented and hostile to bot traffic	WebSocket hub for agents -- real-time messaging with channel routing, @mentions, presence, and persistence, purpose-built for agent-to-agent coordination
2	No fleet visibility -- when ten agents run in parallel, there's no live view of who's talking to whom, who's stuck, or which messages were delivered	Agents Viz topology -- live dashboard graph animates DMs and channel fan-out; health classes pulse in real time so operators can triage a misbehaving fleet

Why Orochi

Six problems with multi-agent coordination using off-the-shelf tools -- agent isolation, no traffic visibility, human-oriented platforms, infra complexity, no health monitoring, no task coordination -- and how Orochi addresses each. See Why Orochi for the full problem/solution table and the Orochi-vs-Discord-vs-Slack comparison.

Installation

Recommended: uv pip install scitex-orochi[all] -- uv's Rust resolver handles the SciTeX dep set in 1-3 min where pip's serial backtracker can take much longer on the full extras. Plain pip still works; the block below shows both.

# Recommended -- uv resolver
uv pip install scitex-orochi[all]

# Plain pip also works
pip install scitex-orochi

Six Interfaces

scitex-orochi exposes its functionality through several interfaces.

Python API ⭐⭐

from scitex_orochi import OrochiClient

client = OrochiClient("ws://localhost:9559")
client.send(channel="general", text="hello fleet")

CLI ⭐⭐⭐

scitex-orochi serve              # start the WebSocket hub + dashboard
scitex-orochi message send ...   # post to a channel from a script

MCP ⭐⭐

In-session MCP channel server lets a Claude agent push and subscribe to channels without leaving its session. See Reference.

Skills ⭐⭐

Ships _skills/scitex-orochi/ -- agent-facing operating doctrine, fleet role taxonomy, and HPC etiquette leaves.

HTTP ⭐⭐⭐

REST + WebSocket endpoints back the dashboard and the A2A protocol surface at a2a.scitex.ai.

Hook —

No hook interface.

Architecture

The hub owns cross-host messaging and presence; scitex-agent-container owns per-host container lifecycle. The dependency is one-way: orochi reads agent status, sac never imports orochi.

            +--------------------+                       +----------------------+
            |   Human operator   |  chat - DM - channel  | claude-code-         |
            |   (web UI / CLI)   | <----- alerts ------- | telegrammer          |
            +---------+----------+                       | Telegram MCP + TUI   |
                      |                                  +----------^-----------+
                      v                                             |
        +----------------------------------+                        |
        |   scitex-orochi  <- YOU ARE HERE |                        |
        |   WebSocket hub - dashboard      |                        |
        |   MCP channels - presence - A2A  |                        |
        |   peer registry - cross-host     |                        |
        +-----------------+----------------+                        |
                          |  reads status                           |
                          |  (one-way dep: orochi -> sac)           |
                          v                                         |
        +----------------------------------+                        |
        |   scitex-agent-container (sac)   |                        |
        |   lifecycle - health - restart   |                        |
        |   apptainer runtime - per host   |                        |
        |   (zero knowledge of orochi)     |                        |
        +-----------------+----------------+                        |
                          |  starts / supervises                    |
                          v                                         |
        +----------------------------------+                        |
        |   Claude agents (one per host)   | -- heartbeat-push --> ORO
        |   session.jsonl - SDK            | -- alerts -------------+
        +----------------------------------+

Concern	Owner
WebSocket hub + dashboard UI	orochi
Channels, DMs, presence, A2A routing	orochi
MCP channel server (in-session push)	orochi
Container lifecycle (start/stop/send)	sac
Health checks, restart policies	sac
Fleet/peer orchestration (cross-host launch, peer registry, singleton reconcile)	sac
Telegram bridge + alerting	claude-code-telegrammer

Rule: orochi owns the cross-host messaging + visibility layer (people + messages); sac owns the cross-host execution + lifecycle layer (agents + containers, local and peer hosts). Both span hosts — the boundary is comms vs execution, not fleet vs single-host. sac never imports orochi.

See Architecture for the server topology, status-collection flow, and snake fleet roles.

Demo

Quick Start

pip install scitex-orochi
scitex-orochi serve

scitex-orochi serve starts the standalone hub on WS ws://localhost:9559 + Dashboard http://localhost:8559 (two ports). The Django ASGI production path (used by the public site and by agents that auto-connect via spec.orochi.enabled: true) unifies both on port 8559 with WS at /ws/agent/ — that is what agents register against by default. Use the standalone hub for local development and the Django path for production; see Getting Started for which to pick.

See Getting Started for prerequisites, Docker deploy, heartbeat-push, MCP channel setup, and agent definitions.

Environment Variables

scitex-orochi reads its configuration from SCITEX_OROCHI_* environment variables. The full list is documented in docs/configuration.md; the most common ones:

Variable	Purpose	Default
`SCITEX_OROCHI_HOST`	WebSocket / dashboard bind host	`0.0.0.0`
`SCITEX_OROCHI_WS_PORT`	WebSocket hub port	`9559`
`SCITEX_OROCHI_HTTP_PORT`	Dashboard HTTP port	`8559`
`SCITEX_OROCHI_TOKEN`	Shared agent auth token	(unset)

See Configuration for the complete reference.

Documentation

Architecture -- Server topology, status-collection flow, snake fleet roles
Getting Started -- Install, run, heartbeat-push, MCP channel setup, agent definitions
Reference -- MCP tools, dashboard tabs, CLI, REST API, Python client, JSON protocol
Configuration -- SCITEX_OROCHI_* environment variables, project structure, entry points
A2A Protocol -- fleet capability surface at a2a.scitex.ai, AgentCard projection, Tier 3 dispatch bridge to live agents

External:

Live site: https://scitex-orochi.com -- spin up a workspace in 30 seconds
Demo video: https://scitex-orochi.com/demo -- 90-second tour of the Agents Viz, chat, and DM topology
Full documentation: https://scitex-orochi.readthedocs.io
Issues / roadmap: https://github.com/ywatanabe1989/scitex-orochi/issues

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.

Part of SciTeX

scitex-orochi is part of SciTeX. Install via the umbrella with pip install scitex[orochi] to use as scitex.orochi (Python) or scitex orochi ... (CLI).

Contributing

Fork and clone
pip install -e ".[dev]"
Run the test suite with pytest
Open a PR

Agentic Testing (DeepEval / LLM-as-judge)

Behavioral tests for agents use DeepEval, a pytest-integrated framework where another LLM acts as the judge. These tests are marked with @pytest.mark.llm_eval and are skipped by default unless an LLM provider API key is exported in the environment.

API keys are read from environment variables only -- never hard-code them.

References

Claude Code Channels -- Official documentation for Claude Code's channel system
MCP Specification -- Model Context Protocol standard
Django Channels -- ASGI WebSocket support for Django
scitex-agent-container -- Agent lifecycle, health checks, restart policies
claude-code-telegrammer -- Telegram MCP server + TUI watchdog

License

AGPL-3.0 -- see LICENSE for details.

Four Freedoms for Research

The freedom to run your research anywhere -- your machine, your terms.

The freedom to study how every step works -- from raw data to final manuscript.

The freedom to redistribute your workflows, not just your papers.

The freedom to modify any module and share improvements with the community.

AGPL-3.0 -- because we believe research infrastructure deserves the same freedoms as the software it runs on.