# ai-tc — AI Traffic Control

> An open-source, local-first control plane for coding agents. Every event in an agent session — prompt, response, tool call, file read — passes one control point: the detection engine scans it against rule packs for secrets and regulated data (PCI, PHI, PII), and policy decides what happens next (monitor, warn, redact, block, or a manual exception). Runs entirely on the developer's machine with no backend and no account. Apache-2.0. Installs as a plugin for Claude Code (and Claude Desktop, the same package), Codex CLI or Antigravity; as a browser extension for ChatGPT and Claude.ai web chat; or as the standalone `aka` CLI.

Detection and enforcement run locally. A handful of narrow paths do reach the network. Most are child processes — the default-on update notice's `npm view` lookups, package-manager installs, the plugin's `npm audit signatures` supply-chain check, git-style external `aka <name>` dispatch to a program on your own `PATH` this project doesn't bundle or control, and the **opt-in** `/aka:setup` calibration each host plugin ships. One is not: `aka attach` registers a machine against an AKA deployment your own organization runs, and from then on the plugin forwards that deployment the activity it is entitled to see and pulls the policy it sets — over `@akasecurity/remote`, the one package in the tree permitted to open a socket. It is opt-in and inert until an endpoint and an access key are both on disk, and `aka detach` ends it. Two paths carry your data: the calibration (to a model, behind two separate, separately-revocable grants) and an attached connection (to your organization's deployment). The README's `[^egress]` footnote is the guarded, up-to-date list of every path and exactly what the calibration payload contains — read it rather than this paragraph for the current count.

## Install

- Claude Code: `/plugin marketplace add akasecurity/marketplace` then `/plugin install ai-tc@akasecurity`.
- Claude Desktop: supported through the same plugin package; see the installation guide.
- Codex CLI and Antigravity: separate plugin packages from the same marketplace; see the installation guide.
- Browser extension (ChatGPT + Claude.ai web chat): `aka extension install`, bridged to Chrome over native messaging.
- Standalone CLI (binary `aka`, no coding agent required): install, then `aka init` — it detects whether a plugin is present and offers to add it.

## Key concepts

- **Event** — a prompt, response, tool call, or file read captured from an agent session.
- **Finding** — a rule match the detection engine produces against an event.
- **Rule** — a JSON file describing what to detect: a keyword list, a regex pattern, or a validator.
- **Rule pack** — a directory of rules and their fixtures with a `manifest.json`. Seven ship built in: `secrets`, `secrets-infra`, `core-pii`, `core-financial`, `core-phi`, `core-code-context`, `code-flaws`.
- **Policy** — the decision taken when a rule or category fires.
- **Plugin** — the harness extension that intercepts sessions. One package serves Claude Code and Claude Desktop; separate packages ship for Codex CLI and Antigravity, plus a browser extension for ChatGPT and Claude.ai web chat.

## Where your data lives

A local SQLite store at `~/.aka/data/aka.db`, settings beside it under `~/.aka/settings`, and vault/exception key material under `~/.aka/keys`. No database server, no schema to manage. The store is a running log of sessions: only rule-flagged spans are masked, the rest is kept verbatim and unencrypted. On macOS and Linux the directories are owner-only (`0700`) and files are `0600`; those permissions are the only at-rest control, and they do nothing on Windows. [SECURITY.md](https://github.com/akasecurity/ai-tc/blob/main/SECURITY.md) has the full picture.

## Documentation

- [README.md](https://github.com/akasecurity/ai-tc/blob/main/README.md): How it works, key concepts, where data lives, install, and the full egress footnote.
- [Docs site](https://akasecurity.github.io/ai-tc-docs/): Full documentation, architecture, and the built-in detection catalog.
- [How it works](https://akasecurity.github.io/ai-tc-docs/getting-started/how-it-works/): The control point and the path an event takes through it.
- [Architecture overview](https://akasecurity.github.io/ai-tc-docs/architecture/overview/): How the plugin, detection engine, and local SQLite store fit together.
- [Writing rules](https://akasecurity.github.io/ai-tc-docs/rules/writing-rules/): Authoring a detection rule and its fixtures.
- [SECURITY.md](https://github.com/akasecurity/ai-tc/blob/main/SECURITY.md): The store's threat model and private vulnerability reporting.
- [CONTRIBUTING.md](https://github.com/akasecurity/ai-tc/blob/main/CONTRIBUTING.md): Branch-and-PR workflow, commit convention, and the test suite.

## Repository layout

- `packages/` — the workspace: `detections` (rule engine), `scanner`, `extract`, `persistence` (SQLite store), `schema`, `plugin-runtime`, `plugin-sdk`, `local-ops`, `dashboard-ui`, `ui-kit`, `setup-wizard`.
- `plugins/claude-code/`, `plugins/codex/`, `plugins/antigravity/` — the harness plugins, one per host, published as `@akasecurity/ai-tc-claude-code`, `@akasecurity/ai-tc-codex` and `@akasecurity/ai-tc-antigravity`.
- `plugins/browser-extension/` — the Chrome extension for ChatGPT and Claude.ai web chat (MV3 content scripts + a native-messaging host).
- `cli/` — the standalone CLI published as `@akasecurity/cli`, binary `aka`.
- `rules/` — the seven built-in rule packs and their fixtures.
- `skills/write-detection-rule/` — the authoring skill for new detection rules.
- `web-ui/` — the local dashboard.

## Related

- [akasecurity/marketplace](https://github.com/akasecurity/marketplace): One place to install AKA Security's tools for coding agents; `ai-tc` is served from here.
- [akasecurity/ai-tc-docs](https://github.com/akasecurity/ai-tc-docs): Source for the documentation site above.
- [akasecurity/claude-tools](https://github.com/akasecurity/claude-tools): The security defaults Claude Code doesn't ship with (guard hooks on an isolated profile).
- [akasecurity/preflight-skills](https://github.com/akasecurity/preflight-skills): An independent multi-model review crew for coding agents. Report-only.