420AI

A self-hosted AI Coding Session Intelligence Platform — capture every AI coding-tool session on your machine(s), archive it with full fidelity, and turn it into reports on cost, token/context efficiency, tool-call failures, and Git outcomes.
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

AI coding tools produce valuable but fragmented operational data — sessions live in vendor-specific local stores, CLIs, and logs that can crash, change format, or lose history. 420AI captures that data across machines, archives it with maximum fidelity, and turns it into Markdown reports and a live dashboard so you can answer questions like which projects/tools/models are worth the spend and where context is wasted.

It is local-first and self-hosted (nothing leaves your home server), event-sourced (raw records are the permanent truth; everything else is a re-buildable projection), and deterministic-metrics-first, AI-interpretation-second. The repo is an npm-workspaces monorepo:

• packages/shared — token shape, event taxonomy, fingerprint, pricing, cost, ingest wire types
• packages/db — Drizzle Postgres schema + migrations, AES-256-GCM field encryption, repositories
• apps/ingest — Fastify Ingest API (pairing, bearer-authed idempotent ingest, projections, reports)
• apps/collector — headless capture agent (connectors, durable queue, watcher, sync, CLI)
• apps/dashboard — Next.js + shadcn/theGridCN Live Monitor
• apps/desktop — Tauri (Rust) tray app that supervises the collector as a sidecar

(back to top)

Built With

• TypeScript on Node.js ≥ 24 (ESM, strict)
• Fastify — the Ingest API
• Drizzle ORM + PostgreSQL 17 (Docker)
• Next.js + shadcn/ui + theGridCN — the dashboard
• Tauri (Rust) — the desktop/tray collector
• Vitest — unit + integration tests

(back to top)

Getting Started

Prerequisites

• Node ≥ 24 (see .nvmrc) — the collector queue uses the built-in node:sqlite.
• Docker — for the PostgreSQL 17 archive (host port 5433).

Installation

1. Clone the repo

   git clone https://github.com/seanrobertwright/420AI.git
   cd 420AI

2. Install workspace dependencies

   npm install

3. Create your env file and fill the two secrets

   cp .env.example .env
   # ARCHIVE_ENCRYPTION_KEY — 32 bytes, base64:
   node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
   # ADMIN_TOKEN — gates admin endpoints:
   node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

4. Start the archive and apply migrations

   npm run db:up        # postgres:17 on host port 5433
   npm run db:migrate

5. Run the Ingest API

   npm run ingest:dev   # http://localhost:8420

(back to top)

Usage

Pair a machine and capture sessions (collector CLI, run with tsx — no build needed):

# Create a pairing code (admin-gated), then pair the collector
curl -s -X POST localhost:8420/v1/pairing-codes -H "authorization: Bearer $ADMIN_TOKEN" -d '{}'
npx tsx apps/collector/src/cli.ts pair <code> --url http://localhost:8420 --name win-dev

# Run the background capture agent (Ctrl-C drains and stops)
npx tsx apps/collector/src/cli.ts watch

# One-shot ops: drain the queue / inspect backlog / discover repos
npx tsx apps/collector/src/cli.ts sync
npx tsx apps/collector/src/cli.ts queue
npx tsx apps/collector/src/cli.ts discover

Run the dashboard (Live Monitor):

npm run dashboard:dev   # reads INGEST_URL + ADMIN_TOKEN from env

For the full setup and day-to-day guide, see docs/guide/install.md and docs/guide/usage.md.

(back to top)

Roadmap

• M1–M9 — capture → archive → projections → reporting → AI interpretation → Live Monitor
• M10 — hardening: exports, catalog signing, operational alerts, replay metadata
• M11 — Tauri desktop/tray collector
• M12 — Production Readiness / GA (in progress, 8 slices): basic search, dashboard surfaces, auth hardening, ops baseline, archive-replay engine, alert delivery, connector hardening, export/distribution polish

See SUMMARY.md and the open issues for the full list.

(back to top)

Contributing

This is a single-maintainer project. Contributions, issues, and feature requests are welcome — fork the repo, create a feature branch, and open a PR. Before committing, ensure the gate passes:

npm run repo-health           # typecheck + tests + NUL/stray-artifact scans
npm run repo-health -- --require-db   # also runs the Postgres integration layer

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Sean Wright —

Project Link: https://github.com/seanrobertwright/420AI

(back to top)

Acknowledgments

• othneildrew/Best-README-Template — README structure
• Shields.io — badges

(back to top)