UNITARES Governance Plugin
cirwel/unitares-governance-plugin
Governa frotas de agentes IA com check-ins, dialética e telemetria em tempo real
Ver no GitHubPlugin 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-plugin1 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
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
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
unitarescontains the runtime, MCP server, storage, health checks, and governance logicunitares-governancecontains 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
| Document | What it covers |
|---|---|
| CODEX_START.md | Preferred 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.md | Branch/PR convention and review standard |
Core Workflow
The intended workflow is:
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- if continuing prior work, pass
parent_agent_id=<prior uuid>andspawn_reason="new_session" - 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 - call
get_governance_metrics()for read-only state - use
identity(agent_uuid=..., continuity_token=..., resume=true)only for same-owner proof-owned rebinds - call
identity()andhealth_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
| Command | Description |
|---|---|
/governance-start | Create or declare lineage for a Codex/ChatGPT UNITARES session |
/checkin | Manual turn-baseline check-in, plus meaningful milestones |
/diagnose | Show current governance state plus identity/health diagnostics when needed |
/dialectic | Request a dialectic review |
Skills
| Skill | When to Use |
|---|---|
unitares-governance:governance-fundamentals | Understanding EISV, coherence, verdicts, and calibration |
unitares-governance:governance-lifecycle | Onboarding, continuity, check-ins, and recovery |
unitares-governance:dialectic-reasoning | Participating in dialectic sessions |
unitares-governance:knowledge-graph | Searching and contributing to shared memory |
unitares-governance:discord-bridge | Operating the Discord integration |
Prerequisites
- A running UNITARES governance server
- 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:
| Variable | Default | Description |
|---|---|---|
UNITARES_SERVER_URL | http://localhost:8767 | Governance server base URL |
UNITARES_AGENT_PREFIX | claude | Prefix for generated client-side names in Claude hooks |
UNITARES_AUTO_ONBOARD | on | Let Claude post-stop lazily create a slot-scoped identity before its first turn summary if the agent did not manually onboard |
UNITARES_FILE_LEASES_ENABLED | 1 | Enable Claude Edit/Write/MultiEdit file-lease guard |
UNITARES_FILE_LEASES_REQUIRED | 0 | Block edits when lease infrastructure is missing/unreachable |
LEASE_PLANE_BASE_URL | http://127.0.0.1:8788 | BEAM lease-plane HTTP base URL |
LEASE_PLANE_BEARER_TOKEN | unset | Bearer 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:
- create a short-lived branch
- keep the change focused
- push the branch
- open a PR
- merge after review or self-review
See CONTRIBUTING.md for the repo convention.