← back  the engine

Inside the machine that builds the work.

No mystery box. AJ AI is one machine running one loop — classify → route → execute → persist — over real tools, with a deterministic router and an audit that ends with a human. Here's every moving part.

0 tests 0 vault notes 5 execution backends 4 audit gates ~$400/mo to run

01 by the numbers

The data room, as it stands today

Every figure below is counted, not estimated. This is the real, current state of the engine AJ AI runs on.

0B
Claude tokens built
0
build sessions
0+
build actions
0
tests
0
vault notes
0 GB
working memory
0
Python modules
0
test files

02 architecture

One loop, one machine.

Think of it like a tiny operating system. A kernel decides; memory remembers; hands do the work; a clock runs it on a schedule. Every request walks the same four steps.

The kernel is Claude — it reads the request, classifies it, and picks the route. The vault (Obsidian markdown) is canonical memory; SQLite is an append-only ledger for audit, never the source of truth. The hands are Claude Code + Codex, which write and run real code. A scheduler (Windows/NSSM) runs the nightly jobs.

classify → route → execute → persist — every request, same path.
Markdown vault = source of truth · SQLite = audit only.
Runs on one operator, one machine — not a cloud of agents.
Claude kernel classify route execute persist Obsidian vault SQLite ledger Code · Codex scheduler

the kernel decides · memory remembers · hands build · the clock runs it

03 models & routing

One deterministic router. Five backends. Zero added cost.

The router isn't another AI deciding — it's plain keyword/prefix matching that sends each request to the right model. No extra LLM call, no extra latency, and the cheap model handles the cheap work.

Heavy reasoning goes to the big models; extraction and classification go to Haiku; offline/free work can run on a local model. Swapping routine classification onto Haiku cut the monthly model bill by roughly half with no quality loss on those tasks.

Opus · heavy reasoning Sonnet · synthesis Haiku · extract / classify GPT-4o · fallback local · free / offline
router deterministic · $0 Opus Sonnet Haiku GPT-4o local model

keyword/prefix match → exactly one backend, every time

04 end-to-end trace

How one request moves through the engine

One operator request, followed all the way down. classify → route → execute → audit → human → persist → deliver. No hand-waving — the real mechanics an engineer can trust.

arrive classify route execute 4-gate human persist
01 ARRIVE A request hits the Click CLI or FastAPI dashboard An operator instruction enters through the Click CLI or the FastAPI dashboard. Pydantic validates the shape before anything downstream runs.
02 CLASSIFY Claude — the reasoning kernel — picks a route Claude classifies intent and selects the route: chat · plan · research · code · codex · propose. Each route's prompt lives in vault/40_Prompts/.
03 ROUTE Deterministic router picks model + tool, then hydrates context — zero added LLM cost Keyword/prefix match (no extra LLM call) maps the route to a model — Opus / Sonnet / Haiku / Fable or OpenAI Codex — and its tool. Active project context is auto-injected from the vault before the executor sees a token.
04 EXECUTE The hands run — git pre-SHA captured, stop-and-ask on a blocker Claude Code / Codex / shell write and run real code; a git pre-SHA makes the job rollback-by-id. If the executor emits BLOCKED: <question> as line one, the run halts, logs to the vault, and waits for a human to resolve. No silent guessing.
05 AUDIT The 4-gate audit runs — nothing irreversible ships without all four Detailed below: deterministic lint hooks → LLM review → an independent second model (Codex) → human sign-off.
06 PERSIST Vault note becomes truth, SQLite row becomes the audit trail, deliverable.md ships The result is written as a plain-markdown vault note (source of truth) and appended to the SQLite ledger (append-only audit). A deliverable is generated and the run logged to Linear + Obsidian. The loop closes.

· the gate inside step 06

The 4-gate audit

Nothing irreversible ships without all four. And a merge-guard hook blocks merge / reset --hard / force-push to main unless a one-shot MERGE-OK token exists.

1 Deterministic lint hooks py_lint · db_guard · dangerous_cmd — fire on PreToolUse. No model, no judgment, just rules.
2 LLM review Claude checks the change for logic and intent — does this do what the request actually asked for?
3 Independent audit A different model (Codex) gives a read-only second opinion. No single model signs off on its own work.
4 Human sign-off (AJ) The approval gate. An explicit human OK before any apply — or it doesn't ship.
git pre-SHA captured rollback by job id stop-and-ask blocker → vault → human resolves vault note source of truth SQLite ledger append-only audit MERGE-OK token one-shot, guards main deliverable.md generated artifact

05 token economics

The economics: ~$400 a month for work that lists at ~$6,150

7.72 billion Claude tokens went into building this stack. Priced at pay-as-you-go API rates, that work would bill out to roughly $6,150 — and it actually runs for a fraction of that.

Where the value sits, by model

The router sends the hard reasoning to Opus and keeps cheap, repetitive work on cheap models. Most of the spend concentrates in two Opus generations doing the heavy build work; the lighter models handle the long tail for cents.

90%+ of every request is a cache read, not a fresh prompt — the same context gets reused across thousands of build actions instead of re-billed each time.
A deterministic router pins each task to the right tier, so Sonnet and Haiku absorb the volume that never needed Opus.
Codex adds 0.10B tokens on top, for about 7.82B across the full stack.
modelAPI-equivalent value
Opus 4.8$3,224
Opus 4.7$2,616
Sonnet$260
Fable$40
Haiku$12
Claude totalacross 7.72B tokens$6,150
ChatGPT personal, est.~2.5 yrs personal use$18,724
$6,150
API list-rate value
~$400/mo
actual all-in cost
0%+
requests served from cache
0B
Claude tokens built

One operator running ~$6,150 of API-rate work for about $400 a month. The router and the cache are what turn that budget into six thousand dollars of output — the cheap work stays cheap, and nothing gets paid for twice.

06 scale

A year of build, from one machine that doesn't sleep

One operator, one machine, and a scheduler that runs through the night. This is the raw throughput behind the system — counted, not estimated.

0
build sessions
0+
build actions
0
tests
0
vault notes

Volume the operator never typed by hand

Every number here is a side-effect of the same loop running over and over: a session opens, the agent acts, the work gets tested, and the decision gets written down. Run that loop 2,594 times and it compounds into a system no one person could keep in their head.

2,594 sessions producing 44,000+ build actions — every API response is a concrete step taken.
169 Python modules form the working body of the system, not scaffolding.
1,668 automated tests across 118 files keep the whole thing honest as it grows.
2,002 vault notes live in a 3.5 GB vault the agent reads back as memory.

· output, by the unit

sessions actions tests decisions modules 2,594 44k+ 1,668 2,002 169

Bars scaled to count. Tests in green — the gate that has to stay full before anything ships.

169 Python modules the body 118 test files the safety net 3.5 GB vault the memory nights on the scheduler runs while the operator sleeps

07 the audit moat

Nothing irreversible ships without passing four gates.

Code, deploys, anything touching money — every one runs the gauntlet. Three machine checks, then a human. That's why you can trust what comes out.

01Deterministic lintssyntax + safety rules, no model needed
02LLM reviewClaude checks logic + intent
03Independent audita different model, read-only, second opinion
04Human sign-offAJ approves — or it does not ship

08 guardrails, in code

The guardrails, for real

The audit moat is the policy. This is the wiring underneath it. Speed with a seatbelt — the executors write and run real code at full pace, and a layer of deterministic hooks sits between intent and anything irreversible.

Four hooks, zero judgment calls

These run as Claude Code lifecycle hooks, not LLM checks. They are pattern matches and exit codes — deterministic, fast, and impossible to sweet-talk. A hook either passes or it blocks the tool call before it lands.

PreToolUse fires before a write or command runs — it can veto. PostToolUse fires after, to clean and normalize.
No model in the loop means no added LLM cost and no nondeterminism on the safety path.
Same gate whether the request came from a human operator or an autonomous nightly job.
PreToolUse veto PostToolUse normalize exit-code gated
01 py_lint PostToolUse. Formats and lints every Python file the executor touches, so generated code lands clean instead of drifting.
02 db_guard PreToolUse. Blocks risky database writes before they execute — protects the SQLite ledger and store from destructive statements.
03 dangerous_cmd PreToolUse. Inspects shell commands and refuses the dangerous ones before the shell executor ever runs them.
04 merge-guard Blocks merge, reset --hard, and force-push to main unless a one-shot MERGE-OK token exists.

The MERGE-OK token

Irreversible git operations on main are denied by default. The only way through is a single-use MERGE-OK token, and that token is created only on an explicit human OK. One token, one merge — it is consumed on use, so a stale approval cannot quietly authorize the next operation.

Covers the three ways history gets rewritten or overwritten: merge, reset --hard, force-push.
No token present → the operation is blocked, full stop. The hook does not ask the model what it thinks.
Human sign-off is gate four of the four-gate audit, and it is the same hand that mints the token.
git merge to main merge-guard MERGE-OK token? token found proceed · consume token no token blocked, full stop
PRE-SHA Every apply is reversible by job id Before any code or codex apply, the runner captures the git pre-SHA. Every change is pinned to a job, so a bad apply rolls back to the exact commit it started from.
APPROVAL GATE Nothing applies without the gate The executor can write and propose freely, but an approval gate stands before apply. Generation is cheap and reversible; landing it on disk is the line that requires a yes.
STOP-AND-ASK BLOCKED halts the runner If an executor's first line is BLOCKED: <question>, the runner stops, writes the blocker to the vault, and waits for an explicit human resolve before resuming.
LEDGER Append-only, tamper-evident record The SQLite store is an append-only audit ledger — never source of truth, never rewritten. It records what happened so the trail survives even when the vault is the canonical memory.
4 deterministic hooks on the safety path
1 single-use MERGE-OK token per merge
0 added LLM cost to enforce the rules
append-only SQLite ledger, never source of truth

09 the honest record

The engine writes its failures down

Most of building real AI is paths that go nowhere. Those paths live in the vault instead of getting buried — which is the whole reason to trust the parts that worked.

An honest log, not a highlight reel

Every run leaves a record. The dead ends, the wrong turns, the ideas that tested worse than the thing they were meant to replace — all of it gets logged with the same weight as the wins. A clean story is easy to write after the fact. A complete one is harder, and it is the only kind worth standing behind.

2,002 vault notes captured in the vault, dead ends included.
3.5 GB of working memory — the reasoning behind each call, not just the result.
Nothing gets quietly deleted when it stops looking good.
Decisions logged0 in the vault
Working memory0 GB of reasoning
Build sessions0 recorded runs
Tests passing0 across 0 files

· the independent-audit gate

A second pass catches what the first one misses

Before a result counts, it goes through an independent audit gate. That gate routinely finds real defects a single pass glides past — mis-graded results, wrong numbers, a regression that slipped in silently — and it forces the fix before anything ships. The friction is the point. A claim that survives an adversary you built to break it is a claim you can actually trust.

mis-graded results caught wrong numbers flagged silent regressions blocked fix forced before it counts

the differentiator

Every result that ships has survived an independent model and a human

The honest record of what didn't work is the reason to believe what did. The engine keeps the receipts, runs its own adversary, and only lets a result stand once it survives the check.

10 the stack

What actually runs it.

Eleven layers, real components, each one chosen for a reason. Plain Python and markdown at the edges, deterministic routing and append-only audit at the core — so the system stays cheap to run, easy to inspect, and impossible to quietly corrupt.

One operator, one machine, a legible stack

There's no exotic infrastructure here. Claude is the reasoning kernel; a deterministic router picks the model and tool per request with zero added LLM cost. The hands are real CLIs that write and run code behind a four-gate audit. Memory is split on purpose — markdown is the truth you read, SQLite is the ledger you can't rewrite.

Every layer is something a senior engineer can open and read: plain markdown, plain Python, a SQLite file, git SHAs.
The router adds no extra inference call — keyword/prefix matching decides the model and tool before any token is spent.
Nothing irreversible ships until the full pytest suite — ~0 tests across 0 files — passes.
kernel + deterministic router executors · Code · Codex 4-gate audit vault (truth) SQLite ledger MCP connectors · GitHub · Linear · Playwright scheduler · Windows tasks · NSSM · gateway hosting · Cloudflare Pages + Hostinger VPS

top: decide · middle: build + check · base: remember, connect, schedule, host

runtimePython 3.10+ · Click CLI · FastAPI · PydanticClick is the operator interface, FastAPI serves the dashboard, Pydantic types every model
kernelClaude Opus · Sonnet · Haiku · Fable + CodexClaude reasons; the model menu spans heavy work to cheap extraction
routerDeterministic keyword / prefix matchpicks model + tool per request — no extra LLM call, zero added cost
memoryObsidian markdown vault — canonical truthproposals, tasks, blockers, decisions, the LLM Wiki, all plain text you can read
ledgerSQLite — aj_ai.memory.store.Storeappend-only audit only, never the source of truth — so history can't be quietly rewritten
handsClaude Code + Codex CLIs + a shell executorwrite and run real code; code/codex capture a git pre-SHA and roll back by job id
connectMCP layer — GitHub · Linear · Playwright · more+ Context7 · Composio · Cloudflare; the engine opens PRs, files issues, drives a browser
safetypy_lint · db_guard · dangerous_cmd · merge-guardPreToolUse lint hooks; merge-guard blocks merge / reset --hard / force-push without a MERGE-OK token
clockWindows scheduled tasks / NSSM + gatewayrun the nightly jobs; the gateway keeps autonomous jobs alive
hostCloudflare Pages + Hostinger KVM VPSPages/Registrar/Turnstile/DNS for static; an always-on VPS behind nginx for services that persist
testspytest — ~1,668 tests / ~118 filesconftest fixtures (stub_orch, api_client, StubProvider); the full suite must pass before a commit lands
GitHub · PRs Linear · ENG issues via GraphQL Playwright · browser Context7 · live docs Composio Cloudflare

· why the memory is split

Markdown is the truth you read. SQLite is the ledger you can't rewrite.

The vault holds the canonical state — decisions, deliverables, the wiki — as plain markdown, so it's diffable, greppable, and editable by a human without a database client. The SQLite store sits underneath as an append-only audit ledger: it records what happened and never serves as source of truth. Keeping the two apart means a corrupted or contradictory record can't masquerade as canon, and every irreversible action leaves a trail you can replay. A SessionStart hook reloads the wiki index, living status, and user memory into every run — RAM loaded from disk at boot.

honest by design

Built to be trusted because an independent model and a human check everything it ships.

One operator, one machine, a few hundred dollars a month — and a paper trail for every irreversible thing it does.