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["apps/plugin-claude-code<br/><small>Hooks for Claude Code / Claude Desktop</small>"]
        cli["apps/cli<br/><small>The aka CLI</small>"]
        webui["apps/web-ui<br/><small>OSS Next.js dashboard</small>"]
    end

    subgraph runtime["Shared runtime"]
        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 --> sdk
    sdk --> detections
    sdk --> persistence
    cli --> persistence
    webui --> persistence
    detections -->|loads| rules
    detections --> schema
    persistence --> schema
    sdk --> schema

apps/cli and apps/web-ui read/write packages/persistence directly; only the harness plugin goes through packages/plugin-sdk, since that's the layer that also owns the hook lifecycle. 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.