aiZee

Your AI agent ships hallucinated APIs and secrets.
aiZee blocks them — enforced, not advised.

Read this in Arabic · Changelog · Installer Guide · llms.txt

See it block something

$ aizee check 'Bash' --args '{"command":"git add .env && git commit -m keys"}'
{
  "ok": false,
  "decision": "deny",
  "reason": "guardian: commits secrets file .env"
}

$ aizee doctor --json | jq .verdict
"ready"

Every tool call, LLM request, memory write, and file change flows through
Kernel.act() — Probity → Guardian → Policy → LoopDetector → Budget →
Audit — so a denial is a wall, not a suggestion.

What is aiZee?

A zero-compromise, version-controlled operating system that sits between you and every AI coding assistant — Cursor, Claude, Copilot, Windsurf, Cline, Aider, Devin — enforcing engineering standards, security policies, and architectural discipline on every line of generated code.

The problem it solves: AI assistants hallucinate APIs, forget conventions, ignore security, and silently ship technical debt. aiZee forces them to read from a centralized source of truth before writing a single line — and in v6, every action is verified while it executes, not just documented after.

What's New in v6.5.0 — Agent-Facing Surface

Adopted from a structured study of 16 top open-source agent repos
(google/artemis, Agent-Reach, OpenSpec, DeepTutor, free-claude-code,
paperless-ngx — full matrix in .ai/star-repos-report.md):

• aizee_doctor MCP tool — agents can self-diagnose: structured
  verdict (ready/degraded/blocked) + ordered next_steps with
  Run: commands for automatable fixes and Guidance: for user-only
  actions. CLI: aizee doctor --json.
• Uniform MCP envelope + stable error codes — new tools return
  {schema_version, ok, result, error:{code}, meta} so agents branch on
  NEED_SETUP/POLICY_DENIED/UPSTREAM_BROKEN instead of parsing text.
• aizee find / aizee goal — natural-language discovery over 141
  skills + 63 workflows + 266 tech-stack refs; goal maps an objective to
  a workflow's step list. MCP: aizee_find, aizee_goal.
• Governed LLM gateway — aizee gateway init|serve runs a localhost
  Anthropic/OpenAI-compatible proxy with a provider failover chain and
  Kernel.act enforcement on every request: prompt guardrails + policy +
  budget fire on the traffic path.
• Verification dial — Kernel.act(..., verify="checkpoints"|"strict")
  layers plan-diff and supply-chain import checks on top of the mandatory
  gates.
• OpenSpec-style change folders — aizee spec propose <name> scaffolds
  proposal.md/design.md/tasks.md; aizee spec archive lands it under
  changes/archive/YYYY-MM-DD-*.
• Memory consume-rules — rules/ingest.yaml glob→bank/kind/tags
  routing, so aizee memory ingest channels folders into named banks.
• aizee config show (masked) + config apply --check — secrets are
  redacted in output; --check validates a config file and previews the
  exact diff without writing.
• Root SKILL.md + aizee skill link — aiZee installs itself as a
  skill into Cursor, Claude Code, Codex, and OpenCode harnesses, so any
  agent picks up the governed workflow automatically.
• aizee models / aizee work poll — model routing catalog and a
  gh-powered open-work pull list.

What's New in v6.1.0 — Lean Surface

The headline change: the default surface is small and honest. The MCP fleet is reduced to what is actually used, marketing tool modules are gated off instead of deleted, dead code is gone, and installers remove retired files on upgrade.

Lean defaults

• 3 MCP servers by default — aizee (governance), graphify, context7. The marketing/social/freelance MCP servers are gone from every shipped config.
• 39 MCP tools enabled — 7 marketing-domain tool modules (ads, analytics, CRO, email, freelance, SEO, social) still ship but are disabled via disabledToolModules in aizee_mcp/config.json. Remove a name to re-enable it.
• 31 plugins disabled — plugins.yaml ships them enabled: false; the sandbox blocks the rest. code2video, graphify, context7 stay on.
• Dead code removed — unused runtime modules (a2a_server, semantic_search, provider_registry, sql_injection_guard, plugin_system, …) and their tests deleted.

Upgrade hygiene

• Stale-file cleanup — scripts/stale_files.txt lists retired paths; install.ps1, install.sh, and scripts/update.py delete them from existing installs while preserving state/, brain/, and .env.
• Unified test tree — all tests live under tests/{runtime,memory,eval,aizee_mcp,…}.
• Design library seeded — design-library/ now ships real DESIGN.md seeds (editorial, midnight, minimal) so DesignLibrary no longer resolves an empty catalog.
• Memory.md self-compaction — kept under its 500-line budget via aizee memory compact (archive in memory/archive/).

v6.0.0 recap — Governed Runtime

Enforcement moved onto the execution path in v6.0.0:

• runtime/enforcement.py — unified helper: MCP firewall → AgentGateway request checks → execution → gateway response checks → audit. Shared by every call path.
• Kernel.act() — AgentGateway verdicts (ALLOW / REDACT / BLOCK) now gate real actions; prompt-injection and secret-leak checks apply to prompt-like fields without blocking ordinary file writes.
• Outbound MCP — McpClient (sync + async) and McpAgent run the firewall and gateway around every external tool call.
• Inbound MCP — the aiZee server's tools keep RBAC and get gateway wrapping.

Detection depth

• Injection detector L1→L3 — 13-technique regex layer + L2 embedding-similarity layer + optional L3 LLM-judge hook. Deterministic/model-free by default.
• Dual-LLM hardening — quarantined worker output is schema-enforced via Pydantic; parse failure is fail-safe.
• MCP 2026-07-28 stateless — per-request protocolVersion negotiation + Mcp-Method/Mcp-Name header routing (runtime/mcp_protocol.py).

Governance depth

• APL verdicts — policies can now modify (rewrite payloads, audited) and observe (log-only) in addition to allow/ask/deny.
• Lifecycle hooks — output.pre_send and memory.pre_write phases; hooks can veto or mutate.
• aizee heal — safe autofix orchestrator (dry-run default, --apply with confirmation, audit to state/heal.log).
• Per-PR budgets — cumulative spend limits keyed by PR id (AIZEE_PR_ID), on top of session/hour/day windows.
• Release gate — eval/release_gate.py runs the reliability priority ladder over recorded rollouts; wired into aizee ci.
• Chaos suite — eval/chaos.py fault-injection scenarios + error-budget math.

Memory & protocol surfaces

• Bi-temporal memory — store.as_of(as_of=..., valid_at=...) answers "what did we know then" and "what was true then" separately; pinned, soft-delete with tombstone-time queries, contradiction relations.
• aizee memory compact — Memory.md auto-compaction (500-line budget, [PINNED] rescue, archive under memory/archive/).
• Code Mode — aizee codemode executes sandboxed Python snippets that call MCP tools directly (AST scan + restricted builtins + governed bridge + timeout).
• aizee bootstrap — materialize a minimal OS root after pip install aizee (idempotent, dry-run default).
• Advisory audits — aizee task overcheck (over-engineering signals from plan + graph), aizee task curriculum (staged learning plan from tech-stack refs).
• Cross-harness handoffs — aizee memory handoff --to-harness <h> stamps a portable aizee.handoff.v1 doc into the scoped vault (brain/handoffs/, fail-closed gitignore guard) so another agent picks up exactly where this one stopped.
• Instincts — aizee memory instinct-* records atomic trigger→action behaviors with confidence 0.3→0.9; observed in ≥2 projects → auto-promotes project→user scope.
• MCP supply-chain audit — aizee security mcp scans discovered MCP configs (JSONC-tolerant) for plaintext/token-shaped secrets in env and args, unpinned npx/uvx packages, writable command paths, and rug-pull drift vs locked baselines.
• Fact-forcing guardrail — recoverable destructive commands (force-push, hard reset) pass only with explicit {target, rollback} facts; catastrophic ones stay hard-blocked.
• Prompt-defense baseline — every materialized harness rules file carries a fixed anti-injection section (identity lock, secret non-disclosure, untrusted external content, unicode-trick suspicion).

Full detail: CHANGELOG.md

Quick Start

Prerequisites

Installation

git clone https://github.com/m3taz-ahmed/aizee.git .ai
cd .ai

Windows — GUI wizard (double-click install.bat or run):

.\install.ps1 -Gui

Windows — CLI:

.\install.ps1

macOS / Linux:

bash install.sh

pip (from GitHub):

pip install "git+https://github.com/m3taz-ahmed/aizee.git"
aizee bootstrap --target ~/.aizee --yes   # materialize a minimal OS root
export AIZEE_ROOT=~/.aizee

PyPI publication is planned; until pip install aizee lands, install
from the repo directly as above (the pyproject.toml is real — it
installs cleanly as an editable or git package).

Installer map — the .bat files are thin launchers, not separate installers:

Both install and update run the scripts/stale_files.txt retirement list, so files removed from the repo are deleted from existing installs too.

Verify

aizee doctor    # Health check (46 checks)
aizee heal      # Diagnose + safe autofixes (dry-run; --apply to fix)
aizee status    # Current persona, skills, budget

Core Architecture

.ai/                         # Sovereign root (discovered via AIZEE_ROOT)
├── AGENTS.md                # Cross-tool canonical bootloader
├── global-roles.md          # 29 personas + operational rules
├── global-workflow.md       # Cognitive loading & execution protocol
├── runtime/                 # Kernel: policy, budget, audit, 124 governance modules
│   ├── kernel.py            # Facade — Probity → Guardian → Policy → Loop → Budget → Audit
│   ├── enforcement.py       # Unified firewall+gateway enforcement helper
│   ├── agent_gateway.py     # Request/response guardrails (ALLOW/REDACT/BLOCK)
│   ├── injection_detector.py# L1 regex + L2 embeddings + L3 LLM-judge
│   ├── codemode/            # Sandboxed code-mode tool execution
│   └── policies/            # default/guardian/probity/mcp_firewall YAMLs
├── memory/                  # SQLite + FTS5 + vector, bi-temporal queries
├── aizee_mcp/               # MCP server (39 tools enabled, 3 resources)
├── eval/                    # Benchmarks, chaos, reliability, release gate
├── skills/                  # 141 persona + lord skills
├── workflows/               # 63 trigger-based execution protocols
├── rules/                   # Compressed behavioral rules
├── tech-stack/              # Version-locked stack references
├── dashboard/               # Web dashboard (Python stdlib HTTP)
├── scripts/                 # Installers, validators, MCP wrappers
├── install.ps1 / install.sh # Idempotent OS installer
└── pyproject.toml           # Package metadata + quality config

The Six Pillars

1. Persona + Skill Composition

29 personas (ARCH, QA, SEC, DEV, SRE, DATA, ML, DEVOPS, API, FREELANCE, MARKETING, GROWTH, BRAND, EMAIL, SOCIAL, CRO, SALES, etc.) with lord-level domain skills. Auto-detected per task — no manual selection needed.

aizee persona detect --multi "build a secure docker API with postgres"
# → Primary: ARCH + Secondary: SEC, DEVOPS + Lords: security-lord, cloud-platforms-lord

2. Runtime Governance

Every action passes through the gate pipeline before execution:

Probity → Guardian → Policy → Loop Detector → Budget → Audit
        └─ AgentGateway: injection + secret-leak verdicts (v6)

• Policy engine — allow/ask/deny/modify/observe YAML rules with AST-safe evaluation
• MCP firewall — rule-based outbound tool-call gate (deny destructive, ask unknown)
• AgentGateway — prompt/response guardrails on every enforced path
• Budget manager — token/cost/call limits per session/hour/day/week/month and per PR
• Audit logger — SHA-256 hash-chained, Ed25519-signed, tamper-evident trail
• Workflow runner — durable SQLite-backed execution with saga compensation

3. Live Ground-Truth

Context7 MCP fetches current library docs before implementation. Graphify knowledge graph replaces blind grep for codebase navigation.

4. Hybrid Memory

SQLite + FTS5 full-text + optional vector index (SentenceTransformers). Episodic, semantic, factual, procedural layers — now with pinning, soft-delete, contradiction links, HMAC integrity, and bi-temporal as_of queries.

aizee memory ingest                # Rebuild index after changes
aizee memory search "docker"       # Full-text + vector search
aizee memory compact               # Keep Memory.md under its line budget

5. Quality Gates (Zero Defect)

ruff check .                 # 0 warnings
mypy                         # Strict typing
aizee test --full            # full suite + coverage (fail-under=100)
python eval/harness.py       # E2E eval: ruff + mypy + pytest + validate-globals

6. Token Efficiency

Persona detection is local (pure Python, zero LLM tokens). Code Mode replaces tool-call JSON ping-pong with sandboxed snippets that invoke tools directly — materially fewer orchestration tokens on multi-tool tasks.

Runtime Enforcement Map

Dashboard

python dashboard/server.py 8080
# → http://127.0.0.1:8080

Dark-first command-center UI: command palette (Ctrl+K), bento-grid metrics, status pills, glass panels. Optional Bearer auth via AIZEE_DASHBOARD_TOKEN.

Tabs: Overview · Memory Explorer · Policy Sandbox · Workflows · Sagas · Chat · Tech Stack · Telemetry · System Health · Audit Logs · Settings

Important — disable MCP servers you don't use. Every enabled MCP server consumes memory and may spawn a subprocess on first tool call. After installation, open Settings → MCP Servers, uncheck what you don't need (Uncheck All then re-check), and Save Changes. The kernel auto-reloads on save.

Settings persist to state/settings.json (gitignored, survives updates). Schema migrations run automatically — old files are backed up.

Key Commands

Quality Gates

Tech Stack

• Core: Pure Python 3.10+ (no Node.js required for core OS)
• Memory: SQLite + FTS5 + optional SentenceTransformers vectors
• MCP: FastMCP server, 39 tools enabled by default (7 marketing tool modules ship gated via disabledToolModules)
• Dashboard: Python stdlib HTTP server + SQLite
• Knowledge graph: graphify (optional)
• Dependencies: pyyaml, pydantic, rich, cryptography, numpy, turbovec

Contributing

1. Fork → feature branch (feature/*)
2. Write tests first (AAA pattern, one behavior per test)
3. Run ruff check . && mypy && pytest -q && python eval/harness.py
4. All gates must pass — no PR without green
5. Conventional commits: type(scope): subject
6. PR ≤ 400 lines, targeted tests only

Ecosystem & Distribution

aiZee ships its own MCP server and agent-facing skill. The surfaces below make
it discoverable to agents and humans — some require maintainer accounts:

Everything else (topics, description, release, llms.txt, root SKILL.md,
aizee skill link into agent harnesses) is already shipped.

License

MIT — see LICENSE.