Metadata-Version: 2.4
Name: hermes-global
Version: 0.1.0
Summary: Open-source multi-agent orchestration CLI — spin up a 5-role AI team with automatic topology selection, model freedom, and white-box observability
Author: Nous Research
License-Expression: MIT
Project-URL: Homepage, https://hermes-agent.nousresearch.com
Project-URL: Documentation, https://hermes-agent.nousresearch.com/docs
Project-URL: Repository, https://github.com/NousResearch/hermes-agent
Project-URL: Issues, https://github.com/NousResearch/hermes-agent/issues
Keywords: ai-agent,multi-agent,orchestration,cli,llm,open-source,dev-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9,>=8.1
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: rich<15,>=13.0
Requires-Dist: python-dotenv<2,>=1.0
Requires-Dist: requests<3,>=2.32
Dynamic: license-file

# Hermes Global — Open-Source Multi-Agent Orchestration CLI

> **The white-box alternative to Sakana Fugu.** Not a black-box router — a
> transparent AI team you can see, control, and customize.

[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Hermes](https://img.shields.io/badge/powered%20by-Hermes%20Agent-purple)](https://hermes-agent.nousresearch.com)

---

## What It Is

A CLI tool that spins up a team of **5 specialized AI agents** — CEO, PM, Dev,
CSO, and Ops — to tackle coding tasks collaboratively. You bring your own API
keys. You see every decision. You control every model.

## Why It Exists

**Fugu proves multi-agent > single-agent** (93.2% LiveCodeBench). But Fugu is:

- ❌ Closed-source — you can't see how routing decisions are made
- ❌ Expensive — $30/1M output tokens for Ultra tier
- ❌ Model-locked — you can't choose which models are used

**Google Antigravity is promising but:**

- ❌ Google-controlled — single vendor lock-in
- ❌ New (May 2026) — unproven at scale

**Hermes Global is:**

- ✅ **Open source** (MIT) — audit every line
- ✅ **Model-free** — use DeepSeek, GLM, GPT, Claude, or any OpenAI-compatible API
- ✅ **Observable** — every agent decision is logged and replayable
- ✅ **Local-first** — runs on your machine, not our servers
- ✅ **Extensible** — add your own agents, tools, and skills

---

## Quick Start

### Prerequisites

- **Python 3.11+** (check with `python --version`)
- **Hermes Agent** installed (`pip install hermes-agent` or see [hermes-agent.nousresearch.com](https://hermes-agent.nousresearch.com))
- An API key from your preferred LLM provider

### Installation

```bash
# Install from PyPI
pip install hermes-global

# Or with uv
uv tool install hermes-global
```

### Initial Setup

```bash
# Interactive setup wizard — picks provider, creates 5-agent team
hermes-global init
```

The wizard will guide you through:
1. Choosing your model provider (OpenAI / Anthropic / DeepSeek / Zhipu / Custom)
2. Entering your API key
3. Configuring proxy settings (important for users in China)
4. Creating the 5 agent profiles
5. Initializing the kanban board

### Run Your First Task

```bash
# Delegate a task to the AI team
hermes-global run "Build a REST API for user authentication"

# Simple tasks get fast, direct execution
hermes-global run "Fix typo in utils.py line 42"

# See what's happening with your team
hermes-global status
```

---

## The 5-Role AI Team

| Role | Icon | Responsibility |
|------|------|---------------|
| **CEO** | 🧠 | Strategic direction, GO/NO-GO decisions, scope management |
| **PM** | 📋 | Requirements clarification, spec writing, priority ordering |
| **Dev** | 💻 | Code implementation, TDD, bug fixing |
| **CSO** | 🔒 | Security audit, CVE scanning, secret detection |
| **Ops** | 🚀 | CI/CD, testing, release management, monitoring |

Every agent has its own profile, model configuration, and skill set. The
orchestrator automatically routes tasks through the appropriate agents based on
task complexity and security requirements.

---

## 5 Dynamic Topologies

The system automatically selects the best execution pattern for your task:

| Topology | Use Case | Pipeline |
|----------|----------|----------|
| **Direct** ⚡ | Simple fixes, typos | Dev only |
| **Serial** ➡️ | Complex, security-critical | CEO→PM→Dev→CSO→Ops |
| **Parallel** ∥ | Medium complexity | PM→(Dev∥CSO)→Ops |
| **Tree** 🌳 | Multi-faceted tasks | CEO→parallel sub-pipelines |
| **Decompose** 🧩 | Large, multi-module tasks | CEO→independent workstreams |

You can also force a specific topology:

```bash
hermes-global run --topology direct "Rename variable x to count"
hermes-global run --topology serial "Refactor auth system to OAuth 2.0"
```

---

## Full Observability

Every orchestration step is visible in real time:

```
📋 Task Analysis
  Task:      Add JWT login to the API
  Topology:  PARALLEL
  Reasoning: Medium-complexity task. Parallel Dev+CSO review for efficiency.
  Pipeline:  PM → DEV ∥ CSO → OPS

  ✅ [🧠 CEO] GO — approved (0.3s)
  ✅ [📋 PM]  Spec written (2.1s)
  ✅ [💻 DEV] Code implemented (8.4s)
  ✅ [🔒 CSO] Audit PASS — 0 CRITICAL (1.5s)
  ✅ [🚀 OPS] Tests passed, packaged (3.2s)

═══ Orchestration Complete ═══
  Topology: parallel
  Steps: 5 (5 ✅, 0 ❌)
  Total time: 15.5s
  Est. tokens: ~4,200
```

---

## Model Freedom

Configure any provider per agent. Mix and match to optimize cost and quality:

```yaml
# In ~/.hermes-global/config.yaml
agents:
  ceo:
    provider: anthropic
    model: claude-sonnet-4-20250514    # best reasoning
  dev:
    provider: deepseek
    model: deepseek-v4-pro             # best coding
  ops:
    provider: openai
    model: gpt-4o-mini                 # cheap for CI/CD
```

Supported providers: **OpenAI**, **Anthropic**, **DeepSeek**, **Zhipu AI (GLM)**,
and any **OpenAI-compatible API** (Ollama, vLLM, Groq, OpenRouter, etc.)

---

## Commands

```bash
hermes-global init              # Interactive setup wizard
hermes-global run <task>        # Execute a task through the AI team
hermes-global status            # Show team status, kanban, capabilities
hermes-global --help            # Show all commands and options
hermes-global run --help        # Show run command options
```

---

## Configuration

Configuration lives at `~/.hermes-global/config.yaml`. See
[config_template.yaml](config_template.yaml) for a fully documented example.

API keys are stored in `~/.hermes-global/.env` (never committed to git):

```bash
DEEPSEEK_API_KEY=sk-...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
```

---

## Tech Stack

- **Python 3.11+** / **uv** for package management
- **Click** for CLI
- **Rich** for terminal output
- **5 specialized agents** (CEO/PM/Dev/CSO/Ops)
- **5 dynamic topologies** (direct/serial/parallel/tree/decompose)
- **Auto prompt engineering** (4-layer: role/context/format/pitfalls)
- **3-level recursive self-correction** (Dev↔CSO loop)
- **Capability matrix-driven routing** (learns who's good at what)

---

## Comparison

| | Hermes Global | Fugu | Antigravity |
|---|---|---|---|
| **Open source** | ✅ MIT | ❌ | ❌ |
| **Model freedom** | ✅ Any API | ❌ Sakana only | ❌ Google only |
| **Observable** | ✅ Full tracing | ❌ Black box | 🟡 Partial |
| **Pricing** | Your API keys | $5-30/1M tokens | Free (for now) |
| **Topologies** | 5 (direct/serial/parallel/tree/decompose) | Unknown | Parallel agents |
| **Custom agents** | ✅ Yes | ❌ | ❌ |
| **Local-first** | ✅ | ❌ | ❌ |

---

## Roadmap

- [x] P0: CLI (init/run/status) + 5 topologies + 5 roles + observability
- [ ] P1: Recursive self-correction + capability-matrix routing + auto prompt engineering
- [ ] P2: Kanban management CLI + completion scripts + JSON/Markdown export
- [ ] P3: Docker deployment + community skill marketplace + multi-language UI

---

## Security

API keys are stored in `~/.hermes-global/.env`. **This file is plaintext** — treat it
like a password manager master key:

- **Unix:** Run `chmod 600 ~/.hermes-global/.env` after `init`
- **Windows:** Run `icacls "%USERPROFILE%\.hermes-global\.env" /inheritance:r /grant:r "%USERNAME%:F"`
- Never commit `.env` to git (it's in `.gitignore` by default)
- For production use, consider a secrets manager (Bitwarden, HashiCorp Vault)

**Prompt injection warning:** Hermes Global accepts natural-language task descriptions
and delegates them to AI agents with code execution capabilities. For untrusted input,
use the `--sandbox` flag (coming in P2) or run with a containerized backend.

**Known framework dependencies:** Hermes Global builds on Hermes Agent, which carries
its own security posture. See [Hermes Agent Security](https://hermes-agent.nousresearch.com/docs/security)
for the full threat model.

---

## Contributing

Hermes Global is part of the **[Hermes Agent](https://hermes-agent.nousresearch.com)**
ecosystem by **[Nous Research](https://nousresearch.com)**.

- **Issues:** [GitHub Issues](https://github.com/NousResearch/hermes-agent/issues)
- **Docs:** [hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs)
- **License:** MIT

---

<p align="center">
  <sub>Built with ❤️ by the Hermes Agent community</sub>
</p>
