UNITARES Governance

Governance client for UNITARES. This repo provides agent-facing skills, commands, and client adapters for connecting coding agents to a running UNITARES governance server.

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 commands
• 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.

Core Workflow

The intended workflow is:

1. onboard(force_new=true) to mint a fresh process identity
2. if continuing prior work, pass parent_agent_id=<prior uuid> and spawn_reason="new_session"
3. call process_agent_update() after meaningful work
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

The principle is simple: prefer high-signal governance over high-frequency governance. Meaningful check-ins beat noisy check-ins.

Commands

Command	Description
/governance-start	Create or declare lineage for a Codex/ChatGPT UNITARES session
/checkin	Manual check-in after meaningful work
/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

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:

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

Adapter Notes

Claude

The current Claude adapter includes session-start and post-edit hooks. Those hooks should be treated as an adapter convenience, not the canonical governance policy. In particular, frequent file writes should not automatically be interpreted as meaningful governance events.

Codex

Codex and ChatGPT support should stay minimal and explicit:

• package shared skills through .codex-plugin/plugin.json
• expose manual commands
• treat .unitares/session.json as the neutral local continuity cache
• use scripts/session_cache.py as the shared cache helper across adapters
• avoid client-specific auto-checkin behavior until there is a Codex-native reason to add it

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 process_agent_update calls at three trigger points. session-start is deliberately read-only: it checks server reachability, fetches the governance fundamentals excerpt, and prompts the agent to call onboard(force_new=true) itself.

Trigger	Hook script	Frequency	metadata.event
Claude turn ends	post-stop	per Claude turn	turn_stop
Edit threshold crossed	post-edit	every N edits or T seconds	auto_edit
Session closes	session-end	once per session	session_end

All emissions share one shared helper (scripts/checkin.py) that:

• Applies secret-pattern redaction to response_text before POST
• Truncates response_text to 512 chars
• Logs one status line per attempt to ~/.unitares/checkins.log
• Returns fire-and-forget: never raises, never blocks a Claude turn on failure

Kill switch

UNITARES_CHECKINS=off in the environment suppresses every plugin-emitted check-in. Disable a single trigger by removing its entry from hooks/hooks.json.

Diagnosing check-in behavior

tail -f ~/.unitares/checkins.log

Expected line format:

2026-04-17T02:45:12Z | slot=abc12345 | event=turn_stop | uuid=86ae619f | status=sent | latency_ms=42

Statuses: sent (accepted by governance), fail (POST failed — see err=...), skip_kill_switch (suppressed by UNITARES_CHECKINS=off), error (client-side exception; caller passed garbage values).

Known limitation

The edit-threshold auto-checkin previously supported UNITARES_HTTP_API_TOKEN for Bearer-token auth against remote governance. The refactored helper uses stdlib urllib and does not pass this header. Local-only deployments (the supported default) are unaffected.

Upgrading from plugin 0.2.0

Claude Code caches installed plugins at ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/. A cache at version 0.2.0 predates the check-in trigger hooks shipped in 0.3.0. To force a refresh:

rm -rf ~/.claude/plugins/cache/unitares-governance-plugin/unitares-governance/0.2.0/

The cache will repopulate on the next Claude Code launch. Verify the refresh landed by checking hooks/ contains post-stop and session-end under the new version path.

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.