Skip to content

System Overview

Functional Architecture

At the conceptual level, AKA is a policy checkpoint between an agent harness and the model: every prompt, tool call, and response passes through it — before the model sees it (prompts, tool inputs) or after it responds (tool outputs) — and each one resolves to an outcome: Monitor, Warn, Redact, Block, or a manually-granted Exception.

Related reference

See How it works for the traffic-flow diagram.

Concept model
Plugin Hooks that intercept harness sessions captures Event Prompt, response, or code change scanned against Rule Pack Rules + fixtures, by category produces Finding A rule match against an event resolved by Policy Maps a rule or category to an action results in Action Monitor, Warn, Redact, Block, or Exception

Logical Architecture

At the logical level, those concepts map onto a TypeScript-strict pnpm monorepo, split so each concept has one owning package. The three harness-facing apps never talk to each other — they share behavior only through the runtime layer underneath them:

flowchart TD
    subgraph adapters["Harness adapters"]
        plugin["plugins/claude-code<br/><small>Hooks for Claude Code / Claude Desktop</small>"]
        codex["plugins/codex<br/><small>Hooks + skills for Codex CLI</small>"]
        antigravity["plugins/antigravity<br/><small>Hooks + skills for the agy CLI</small>"]
        browser["plugins/browser-extension<br/><small>Chrome MV3 + native host — ChatGPT / Claude.ai</small>"]
        cli["cli<br/><small>The aka CLI</small>"]
        webui["web-ui<br/><small>OSS Next.js dashboard</small>"]
    end

    subgraph runtime["Shared runtime"]
        pluginRuntime["packages/plugin-runtime<br/><small>Hook wiring the plugin runs on</small>"]
        sdk["packages/plugin-sdk<br/><small>Adapter interface + runtime lifecycle</small>"]
        detections["packages/detections<br/><small>Pure detection engine — scan + redact</small>"]
        persistence["packages/persistence<br/><small>Local SQLite store adapter</small>"]
        schema["packages/schema<br/><small>Zod contracts — single source of truth</small>"]
    end

    rules["rules/<br/><small>Detection rule packs</small>"]

    plugin --> pluginRuntime
    plugin --> sdk
    codex --> pluginRuntime
    codex --> sdk
    antigravity --> pluginRuntime
    antigravity --> sdk
    browser --> sdk
    pluginRuntime --> sdk
    pluginRuntime --> persistence
    pluginRuntime --> schema
    sdk --> detections
    sdk --> persistence
    cli --> persistence
    webui --> persistence
    detections -->|loads| rules
    detections --> schema
    persistence --> schema
    sdk --> schema

cli and web-ui read/write packages/persistence directly; the harness plugins go through packages/plugin-runtime and packages/plugin-sdk, since that's the layer that also owns the hook lifecycle. That's what makes a new harness an adapter rather than a fork: Claude Code, Codex, Antigravity, and the browser extension differ only in how their host delivers events and what its hook output can express. packages/detections is pure (no I/O), so the same scan/redact logic runs identically whether it's invoked from the plugin or the enterprise backend. packages/plugin-sdk is what lets a new harness adapter reuse the same runtime instead of reimplementing storage/detection — see Data Flow for how a request actually moves through these packages.

Where things live

Path What
~/.aka/settings/settings.json Your preferences (run mode, redaction policy)
~/.aka/data/aka.db The local SQLite store (events, findings, policies)
~/.npmrc GitHub Packages scope + auth (pre-release only)

Everything is local. To start over, remove ~/.aka and run aka init again.