convez.ai
MCP ServerAutomaçãoAvançado
cirwel

UNITARES Governance Plugin

cirwel/unitares-governance-plugin

Governa frotas de agentes IA com check-ins, dialética e telemetria em tempo real

Ver no GitHub
InicialPluginScore · de 0 a 100

Plugin MCP que integra agentes de IA (Claude Code, Codex, ChatGPT) à camada de governança UNITARES, fornecendo check-ins, revisão dialética e telemetria de runtime. Funciona como cliente e camada de integração para coordenação de frotas heterogêneas de agentes com rastreamento de estado, métricas e ciclo de vida.

Instalação

$npx convez-ai cirwel/unitares-governance-plugin

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 1 dia
Versão
v0.4.31
Issues abertas
0
Contribuidores
2

Casos de uso

  • Onboarding de agentes IA em sistemas de governança corporativa
  • Sincronização de estado e métricas entre múltiplos agentes colaborativos
  • Revisão dialética de decisões e output de agentes antes de execução

Veredito

Plugin robusto para orquestração e governança de múltiplos agentes IA em ambientes corporativos. Bem documentado e com suporte a múltiplas plataformas (Claude, Codex, ChatGPT), mas requer compreensão profunda de arquitetura de agentes e ciclo de vida para implementação efetiva.

README

A tradução para o português deste README ainda está na fila.

UNITARES Governance

License: Apache 2.0 Claude Code Plugin Codex Plugin Version

Client and integration layer for UNITARES — the runtime telemetry and coordination layer for heterogeneous AI-agent fleets. This repo provides agent-facing skills, command guidance, and adapters for connecting coding agents (Claude Code, Codex/ChatGPT, others) to a running UNITARES governance server. The runtime itself lives in cirwel/unitares.

Purpose

This repo is not the governance engine itself. It is the client and integration layer.

Use it to:

  • onboard agents into UNITARES
  • inspect governance state and operator diagnostics
  • request dialectic review
  • work with the knowledge graph
  • adapt UNITARES workflows to Codex, ChatGPT, Claude, and other clients

What Lives Elsewhere

  • unitares contains the runtime, MCP server, storage, health checks, and governance logic
  • unitares-governance contains the agent-facing plugin and integration layer
  • optional bridges like Discord can remain separate integrations

This repo should not duplicate server business logic or become the source of truth for thresholds that already live in the runtime.

Current Adapters

  • Codex/ChatGPT adapter: plugin packaging plus shared skills and explicit command guidance
  • Claude adapter: hooks, session helpers, and command docs

The shared value in this repo is the workflow guidance and client integration surface, not a second copy of the governance model.

Start Here

If you are using ChatGPT or Codex, start with CODEX_START.md.

That path is now the preferred default. Claude hook automation remains supported, but it is no longer the canonical mental model for UNITARES usage.

Documentation

DocumentWhat it covers
CODEX_START.mdPreferred entry path for Codex/ChatGPT — modes, recommended flow, continuity cache
docs/Documentation index and design-rationale notes (why the plugin is shaped this way)
skills/Agent-facing capability docs — governance fundamentals, lifecycle, dialectic, knowledge graph, Discord bridge
commands/Slash-command guidance — /governance-start, /checkin, /diagnose, /dialectic
CONTRIBUTING.mdBranch/PR convention and review standard

Core Workflow

The intended workflow is:

  1. start_session(force_new=true) as your first step in the session, to mint a fresh process identity (onboard(...) is the canonical equivalent) — until you onboard, your work this session is invisible to governance, which is the main source of uninitialized, 0-update agents
  2. if continuing prior work, pass parent_agent_id=<prior uuid> and spawn_reason="new_session"
  3. call sync_state() once per assistant turn as a behavioral baseline, and after meaningful work (process_agent_update(...) is the canonical equivalent) — an identity that never checks in produces no governance signal
  4. call get_governance_metrics() for read-only state
  5. use identity(agent_uuid=..., continuity_token=..., resume=true) only for same-owner proof-owned rebinds
  6. call identity() and health_check() when diagnosis is needed

On servers with the agent-experience envelope enabled, friendly alias responses lift next_action, state_summary, risk_summary, memory_suggestions, and recovery_hint when present while preserving the canonical payload under raw_governance. Older compatibility surfaces may return the canonical payload directly. Use memory_suggestions as retrieval cues, and prefer recovery_hint before inventing a recovery path.

The principle is simple: prefer regular behavioral baselines over raw activity noise. One real check-in per assistant turn is useful; per-tool or per-edit check-ins are usually not.

Commands

CommandDescription
/governance-startCreate or declare lineage for a Codex/ChatGPT UNITARES session
/checkinManual turn-baseline check-in, plus meaningful milestones
/diagnoseShow current governance state plus identity/health diagnostics when needed
/dialecticRequest a dialectic review

Skills

SkillWhen to Use
unitares-governance:governance-fundamentalsUnderstanding EISV, coherence, verdicts, and calibration
unitares-governance:governance-lifecycleOnboarding, continuity, check-ins, and recovery
unitares-governance:dialectic-reasoningParticipating in dialectic sessions
unitares-governance:knowledge-graphSearching and contributing to shared memory
unitares-governance:discord-bridgeOperating the Discord integration

Prerequisites

  1. A running UNITARES governance server
  2. The governance MCP endpoint reachable by the client

This repo is a client adapter only — it does not include the governance engine. You need a server running before any of these commands or skills do anything useful.

Easiest server bring-up — Docker Compose:

git clone https://github.com/CIRWEL/unitares.git
cd unitares
docker compose up
# server now at http://localhost:8767/mcp/

That single command brings up Postgres+AGE+pgvector, Redis, and the governance server. The Pi/Lumen embodiment side is optional — governance runs standalone. For bare-metal install (Homebrew Postgres, native AGE compile) see unitares/README.md.

Once the server is up, point this plugin's MCP client at it:

{
  "mcpServers": {
    "unitares-governance": {
      "type": "url",
      "url": "http://localhost:8767/mcp/"
    }
  }
}

If your server is on a different host or port, set UNITARES_SERVER_URL (see Configuration below).

Configuration

Environment variables:

VariableDefaultDescription
UNITARES_SERVER_URLhttp://localhost:8767Governance server base URL
UNITARES_AGENT_PREFIXclaudePrefix for generated client-side names in Claude hooks
UNITARES_AUTO_ONBOARDonLet Claude post-stop lazily create a slot-scoped identity before its first turn summary if the agent did not manually onboard
UNITARES_FILE_LEASES_ENABLED1Enable Claude Edit/Write/MultiEdit file-lease guard
UNITARES_FILE_LEASES_REQUIRED0Block edits when lease infrastructure is missing/unreachable
LEASE_PLANE_BASE_URLhttp://127.0.0.1:8788BEAM lease-plane HTTP base URL
LEASE_PLANE_BEARER_TOKENunsetBearer used for lease-plane acquire, heartbeat, and release calls

Adapter Notes

Adapters are a convenience layer over the governance server, not the canonical policy — the server stays the source of truth and the client stays thin.

  • Claude — session-start, pre-edit, post-edit, and session-end hooks, plus BEAM file leases.
  • Codex/ChatGPT — minimal and explicit; shared skills, manual command flows, slot-scoped continuity cache.
  • Sidecar — a dependency-free local proxy for clients without lifecycle hooks.

Full details, endpoints, and configuration are in docs/adapters.md. The Codex/ChatGPT quickstart is CODEX_START.md.

Non-Goals

This repo should not:

  • redefine the governance math
  • duplicate server-side threshold logic
  • auto-checkin every trivial file write by default
  • override runtime verdicts locally

Check-In Triggers

The Claude adapter emits canonical process_agent_update calls at three trigger points (turn_stop, auto_edit, session_end) through one shared helper (scripts/checkin.py) that redacts secrets, truncates, logs, and is fire-and-forget. A UNITARES_CHECKINS=off kill switch suppresses all of them.

For the trigger table, the diagnostic log format, the protective audit, the known token-auth limitation, and plugin-cache upgrade steps, see docs/check-ins.md.

Development Workflow

Use a lightweight branch and PR flow for normal changes:

  1. create a short-lived branch
  2. keep the change focused
  3. push the branch
  4. open a PR
  5. merge after review or self-review

See CONTRIBUTING.md for the repo convention.

License

Apache License 2.0 — see LICENSE and NOTICE.

Ver o original no GitHub

Bom para

Relacionados