gois-lite — QClaw Monitor (Lite)

Generative Orchestration Artificial Intelligence Swarm — lite edition

Health monitor, HTTP dashboard, and AI orchestration for QClaw, OpenClaw, and Hermes — with development-focused skills only (default port 9102). Full edition: gois.

Language	Document
🇺🇸 English	You are here
🇧🇷 Português	README.pt.md
🇨🇳 简体中文	README.zh-CN.md

---

Overview

gois watches QClaw (and related services) on macOS and Windows. It periodically checks process health and HTTP endpoints; after repeated failures, an LLM recovery agent diagnoses logs and attempts self-healing. It exposes an HTTP dashboard, Prometheus metrics, and deep integration with Hermes, OpenClaw, RuFlo, Kanban, WhatsApp, and 300+ QClaw skills.

flowchart TB
    subgraph Clients["Clients & Channels"]
        UI["Browser Dashboard :9101"]
        WA["WhatsApp (wacli)"]
        Cursor["Cursor IDE + MCP"]
    end

    subgraph Gois["gois Monitor"]
        MON["Health Monitor"]
        AGT["LLM Recovery Agent"]
        DASH["HTTP Dashboard"]
        MCP["MCP Servers"]
    end

    subgraph Stack["Vendor Stack (.stack/)"]
        OC["OpenClaw"]
        HM["Hermes Agent"]
        DB[("MongoDB / Redis / SQLite")]
    end

    subgraph External["External"]
        LLM["DeepSeek / OpenAI-compat"]
        PROM["Prometheus"]
    end

    UI --> DASH
    WA --> DASH
    Cursor --> MCP
    MON -->|"pgrep + HTTP + hang"| OC
    MON -->|"failure threshold"| AGT
    AGT --> LLM
    AGT --> OC
    DASH --> OC
    DASH --> HM
    DASH --> DB
    MCP --> DASH
    MON --> PROM

Loading

---

What it does

Component	Role
Monitor	pgrep, HTTP health probes, optional UI hang detection, log scanning
Recovery agent	OpenAI-compatible LLM (default DeepSeek) with tools to read logs, restart QClaw, etc.
Dashboard	UI at http://127.0.0.1:9101/ — status, chat, Hermes roles, Kanban, skills
MCP servers	qclaw-skills, qclaw-cards, qclaw-jobs, qclaw-swarm for Cursor / IDE
Metrics	Prometheus endpoint (configurable in config.yaml)
Skills	300+ QClaw skills — slides, AWS, WhatsApp, research, content, and more

Health-check flow

sequenceDiagram
    participant M as Monitor
    participant Q as QClaw / Gateway
    participant A as LLM Agent
    participant L as Logs

    loop Every interval_seconds
        M->>Q: pgrep + HTTP GET health_url
        alt Healthy
            M->>M: Reset failure counter
        else Unhealthy
            M->>M: Increment failures
            alt failures >= threshold
                M->>L: Tail log_paths
                M->>A: Diagnose + recover
                A->>L: Read evidence
                A->>Q: Restart (if needed)
            end
        end
    end

Loading

---

Requirements

Item	Version	Required
Python	3.11+	Yes
Git	2.x	Yes
DeepSeek API key	—	Yes (LLM agent + chat)
Node.js	22+	Yes (OpenClaw vendor)
MongoDB	7.x	Recommended
Redis	7.x	Recommended
macOS / Windows	—	Native install
Docker + Compose	v2	Optional (Linux / server)

---

Quick start

The repo is self-contained: Hermes (vendor/hermes-agent) and OpenClaw (vendor/openclaw) ship as Git submodules. ./scripts/start.sh bootstraps everything on first run.

git clone --recurse-submodules <repo-url> gois
cd gois
./scripts/start.sh

start.sh is idempotent. It:

1. Creates ./.venv and installs gois (pip install -e .[dev])
2. Runs ./scripts/unify-stack.sh (submodules, .stack/, vendor deps)
3. Ensures ./config.yaml and ./.env
4. Starts the monitor

Dashboard: http://127.0.0.1:9101/

Fast restart (skip vendor reinstall):

./scripts/start.sh --skip-vendor

Full install guide: docs/INSTALACAO.md

Docker

cp .env.example .env   # set DEEPSEEK_API_KEY
docker compose up -d --build

DeepSeek API key

Never commit .env. Copy from example:

DEEPSEEK_API_KEY=sk-your-key
DEEPSEEK_API_BASE=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

Or sync from a sibling project:

.venv/bin/python scripts/sync_deepseek_env.py

---

Project layout

flowchart LR
    subgraph Repo["Repository"]
        SRC["src/gois/"]
        SKL["skills/ (300+)"]
        VND["vendor/"]
        SCR["scripts/"]
    end

    subgraph Runtime[".stack/ (gitignored)"]
        SH["hermes/"]
        SO["openclaw/state/"]
        SB["openclaw/bundle/"]
        ACC["accounts/"]
        CH["chat/"]
    end

    VND --> HM["hermes-agent"]
    VND --> OC["openclaw"]
    SRC --> Runtime
    SCR --> Runtime

Loading

gois/
├── src/gois/           ← Python monitor + dashboard + MCP
├── skills/             ← QClaw skills (chat tools, batch slides, AWS, …)
├── vendor/
│   ├── hermes-agent/   ← Hermes (git submodule)
│   └── openclaw/       ← OpenClaw (git submodule)
├── .stack/             ← Runtime state (generated at boot)
│   ├── hermes/
│   ├── openclaw/
│   ├── accounts/
│   └── chat/
└── scripts/
    ├── start.sh
    └── unify-stack.sh

Migrate legacy state from ~/.hermes or ~/.qclaw-oversea:

./scripts/unify-stack.sh --migrate

Environment overrides:

Variable	Default
GOIS_STACK_ROOT	./.stack
GOIS_HERMES_HOME / HERMES_HOME	.stack/hermes
GOIS_OPENCLAW_SOURCE	./vendor/openclaw
GOIS_OPENCLAW_STATE_DIR	.stack/openclaw/state

---

MCP integration (Cursor / IDE)

flowchart LR
    Cursor["Cursor IDE"]
    SK["qclaw-skills"]
    CR["qclaw-cards"]
    JB["qclaw-jobs"]
    SW["qclaw-swarm"]
    RF["ruflo"]

    Cursor --> SK
    Cursor --> CR
    Cursor --> JB
    Cursor --> SW
    Cursor --> RF

    SK -->|"slides, AWS, files"| Gois
    CR -->|"Kanban, teams"| Gois
    JB -->|"cron, health"| Gois
    SW -->|"multi-agent"| Gois

Loading

MCP server	Tools (examples)
qclaw-skills	team_files_search, slides_batch_images, aws_overview, monitor_update
qclaw-cards	get_cards, move_card, list_teams, get_errors
qclaw-jobs	jobs_health, jobs_list_running, jobs_cron_list
qclaw-swarm	swarm_create, swarm_health, run_team_swarm
ruflo	Swarm orchestration for development

Setup RuFlo for Cursor:

./scripts/setup-ruflo-dev.sh

---

Dashboard URLs

URL	Description
/	Monitor status
/chat	OpenClaw / QClaw chat (DeepSeek + skills)
/chat/ruflo	RuFlo-integrated chat
/chat?whatsapp=1	WhatsApp session
/skills	OpenClaw skills catalog
/roles	Hermes role profiles
/kanban	Team Kanban boards
/whatsapp/status	wacli queue and listener state

---

WhatsApp bridge

flowchart LR
    Phone["Phone"]
    WACLI["wacli"]
    WH["POST /whatsapp/inbound"]
    Chat["/chat session"]
    Agent["DeepSeek + skills"]
    Send["wacli-send.sh"]

    Phone --> WACLI
    WACLI --> WH
    WH --> Chat
    Chat --> Agent
    Agent --> Send
    Send --> Phone

Loading

Enable in config.yaml under whatsapp_digest. See README.pt.md for detailed Portuguese setup notes, or config.example.yaml.

---

macOS auto-start

./scripts/start.sh --launchd

Logs: gois.stdout.log, gois.stderr.log

---

Tests

.venv/bin/pytest

---

Security

• Never commit .env, sk-… keys, or filled config.yaml
• Use config.example.yaml as template; revoke exposed keys immediately
• See SECURITY.md

---

License

See repository; treat as internal use until a LICENSE file is added.