A technical case study on running a 5-agent AI council that researches, debates, builds, and publishes digital products—entirely on local hardware.

The Problem I Was Trying to Solve

I run a tech blog called As The Geek Learns. I also work full-time as a systems engineer. I also maintain two newsletters. I don’t have time to research product ideas, validate markets, write content, build deliverables, create marketing copy, and publish to a storefront.

But I had a Mac Studio M3 Ultra sitting on my desk with 256 GB of unified memory, and I kept thinking: what if I could build a team that does most of this for me?

Not a chatbot. Not a single prompt chain. An actual team—with specializations, disagreements, voting, and accountability.

This is what I built. Here’s how it works, where it breaks, and what I’ve learned.

The Architecture: Five Agents, One Pipeline

The system runs on OpenClaw, an open-source AI agent framework. The “team” is a council of five agents, each with a distinct role and scoring rubric. They share a single pipeline—one product at a time, from idea to published storefront listing.

The Agents

SCOUT—Market Intelligence

Scans for demand signals, competitor gaps, and audience fit. Scores ideas on: demand evidence, pain severity, competitor gap, ASTGL brand fit, and freshness. SCOUT’s job is to make sure we’re not building something nobody wants.

FORGE—Feasibility & Build

Estimates build time, assesses toolchain requirements, and defines scope ceilings. Scores on: build time, tool availability, format clarity, scope containment, and reusability. FORGE is the one who says, “That's a 40-hour build, not a weekend project,” and gets outvoted anyway. (More on that later.)

QUILL—Sellability & Messaging

Tests headlines, evaluates audience clarity, and writes all marketing copy. Scores on: headline test, audience clarity, urgency, differentiation, and shareability. If QUILL can’t write a compelling one-liner, the product doesn’t move forward.

LEDGER—Revenue & Pricing

Analyzes price points, margin viability, market size, and willingness to pay. Scores on: price point, addressable market, willingness to pay, recurring potential, and margin. LEDGER killed our first micro-eBook idea at $1.99—“below the $19 floor individually; bundle pricing required for margin viability.”

MAVEN—Customer Value & Quality

The quality gate. MAVEN scores on pain severity, solution completeness, time to value, trust signals, and predicted satisfaction. Nothing ships without MAVEN’s approval. MAVEN also runs the final quality review, fact-checking deliverables against their own constraints.

How They Score

Each agent scores every product idea on their 5 criteria, 1-5 points each. Maximum: 25 per agent, 125 total. The pipeline threshold is 80% (100/125). Below that, the idea goes back to the backlog.

This isn’t a formality. I’ve watched LEDGER tank a product the other four loved because the margin math didn’t work. I’ve watched FORGE dissent on sequencing even when the vote went against them. The scoring rubric creates genuine tension, and that tension produces better decisions.

The Pipeline: Seven Steps

When the council reaches consensus on a product, it enters a sequential pipeline:

1. Market Research—SCOUT deep-dives demand signals, competitor analysis, pricing benchmarks

2. Pricing—LEDGER sets price point with live competitor data

3. Creative Brief—QUILL writes the brief: audience, tone, format, constraints

4. Build—FORGE constructs the deliverables (PDFs, templates, code bundles, worksheets)

5. Quality Review—MAVEN fact-checks, verifies constraints, scores 1-10 (must be ≥7 to pass)

6. Marketing—QUILL produces product descriptions, social posts, email sequences

7. Package & Publish—Final ZIP assembly, Stripe product creation, storefront listing

Each step runs as a cron job on a 30-minute cycle. The pipeline runner checks for the active product, determines which step is next, and executes it. A full product can go from consensus to published in under 24 hours—though in practice it usually takes 2-3 days because of quality gates and my own review bottlenecks.

The Governance: How Five Agents Make Decisions

This is the part I’m most proud of and the part that surprised me the most.

Voting

The council uses ranked-choice instant-runoff voting. Each agent ranks their preferred ideas. If no idea gets >60% of the weighted score in Round 1, the lowest-scoring idea is eliminated and votes redistribute. This continues until consensus or deadlock.

In practice, most decisions resolve in 2-3 rounds. The debates are real—FORGE might argue for a faster build while SCOUT pushes for a higher-signal market. LEDGER might prefer a premium product, while QUILL argues the audience can’t bear that price point.

Deadlock Protocol

If the evening session can’t reach >60% consensus, it escalates to a frontier model (Claude Sonnet) for a tie-breaking analysis. This has happened twice. Both times, the frontier model sided with the minority agent, which I found interesting.

Kill Switches and Stall Prevention

The system has several circuit breakers:

3 consecutive no-consensus meetings → Alert sent to me via Discord

7 days with no active build → Next morning meeting must activate the highest-scored backlog item

48+ hours stalled on one pipeline step → Council votes to hold or shelve

Global kill switch—I can halt everything with a single signal file

The stall prevention matters because I learned early that without it, the council will endlessly debate scoring refinements instead of building products. The 48-hour timer forces decisions.

SOUL.md: The Operating Constitution

Every agent operates under a shared SOUL.md—a set of principles that override everything else:

Be genuinely helpful (no filler content)

Have opinions (agents must take positions, not hedge)

Be resourceful before asking (try to solve problems before escalating to me)

Earn trust through competence

When SOUL.md conflicts with a protocol decision, SOUL.md wins. This has saved me from shipping mediocre products more than once—MAVEN has invoked SOUL principles to block a product that technically passed all numeric thresholds but didn’t meet the “genuinely helpful” standard.

The Infrastructure: Running It Locally

Everything runs on a single Mac Studio. No cloud APIs for the pipeline work—just local models.

Models

Primary: Qwen3 32B (served via llama.cpp, not Ollama—4x faster wall time)

Code tasks: Qwen 2.5 Coder 32B

Heavy reasoning: Qwen 2.5 72B (for consolidation and ideation tasks)

Light tasks: Qwen3 8B (monitoring, notifications, briefings)

The 32B model handles all pipeline steps. llama.cpp serves it on port 8081 with flash attention, 3 parallel slots, and 128K total context. I migrated from Ollama after benchmarking showed 3.7 seconds vs 14.4 seconds on the same prompt.

Cron Fleet

26 cron jobs run the system:

Pipeline runner every 30 minutes during business hours

Morning briefing at 6:30 AM

Evening summary at 8:00 PM

Market scans daily

Council meetings (morning standup + evening strategy session)

Notification triage every 5 minutes (critical), hourly (important), every 3 hours (low)

Weekly deep scan, docs audit, test suite, security audits

All delivery goes through Discord with a Slack mirror. The system has its own Discord server with dedicated channels for ops alerts, council meetings, pipeline status, product reviews, and market intelligence.

The Numbers That Matter

VRAM usage: ~97 GB pinned across 4 models (out of 256 GB available)

Pipeline throughput: Consensus to published in 12-48 hours depending on product complexity

Quality scores: Averaging 8-8.5/10 on MAVEN reviews

Council consensus rate: >80% of votes resolve without escalation

What I’ve Shipped

Since the council went live in late March 2026:

Incident Response Runbook & Playbook Toolkit—112/125, $19-24, targeting DevOps/SRE teams

Sysadmin Documentation Toolkit—113/125, $24, Markdown + Notion + Obsidian formats

Server Security Hardening Checklist Kit—119/125 (highest score), $24, Linux + Windows

Homelab Disaster Recovery Kit—116/125, $29 (premium tier), Proxmox + TrueNAS focused

Each product went through all seven pipeline steps, MAVEN quality review, and full marketing asset generation. The marketing copy, product descriptions, and email sequences were all council-produced.

I review everything before it goes live. The council builds it; I sanity-check it. So far I’ve shipped every product MAVEN approved—their quality bar has been higher than mine in several cases.

Where It Breaks

I’d be dishonest if I didn’t cover the failure modes. There are several.

The Approval Bottleneck

The biggest problem has been me. The system is designed to be autonomous, but exec permissions—the ability for agents to run shell commands—require approval policies. When those policies are too restrictive, the pipeline stalls waiting for me to approve a command I would have approved anyway. One product sat blocked for 30+ hours because the agent couldn’t run a script to rebuild a ZIP file.

The fix was widening exec permissions for the pipeline agent. The tradeoff is real: more autonomy means more trust in the model not to do something destructive. I’m comfortable with it because everything runs locally and I have kill switches, but it’s a genuine tension.

Model Limitations

32B parameter models are not frontier models. They occasionally:

Lose track of multi-step instructions across long pipeline runs

Generate marketing copy that’s technically correct but tonally flat

Miss nuanced quality issues that a larger model would catch

The council structure mitigates this—five agents checking each other catches most issues. But I’ve had to add explicit constraints (like MAVEN’s “interface-agnostic instructions” rule) after catching problems the models didn’t flag.

The Constant Infrastructure Churn

OpenClaw ships updates frequently. Each update can break config schemas, change entry points, invalidate auth tokens, or require new mandatory config keys. I’ve turned off auto-updates and moved to manual, controlled upgrades—the same approach I use for enterprise infrastructure at my day job.

Stale Sessions

When an agent session accumulates enough failed attempts, the model sometimes learns the wrong patterns from its own conversation history. The fix is clearing the session, but diagnosing when this is happening versus a legitimate configuration issue takes time.

Share As The Geek Learns

What I’ve Learned

Governance matters more than model quality. The scoring rubric, voting mechanics, and kill switches produce better outcomes than throwing a more powerful model at an unstructured problem. Five constrained agents outperform one unconstrained agent.

Autonomy is a spectrum, not a switch. The right level of autonomy depends on the task, the blast radius, and your comfort level. I give the pipeline agent full exec access. I keep the notification agent on a tight allowlist. Both are correct.

Local inference is viable for production work. A 32B model on good hardware, served properly (llama.cpp, not Ollama, with enough context per slot), handles pipeline tasks reliably. You don’t need cloud APIs for everything.

Your AI team will reflect your engineering discipline. If you don’t build in stall prevention, it won’t prevent stalls. If you don’t define quality gates, quality will drift. If you don’t document your governance, your agents will improvise governance—poorly.

The hardest part isn’t the AI. It’s the ops. Model selection, prompt engineering, and agent design are maybe 30% of the work. The other 70% is cron scheduling, delivery routing, auth management, monitoring, and debugging why the Discord webhook stopped working at 3 AM.

What’s Next

The council is evaluating enterprise-tier products (an AI Agent Readiness Guide targeting IT leaders) and exploring whether the pipeline can handle longer-form content like courses. I’m also working on making the council’s own meeting transcripts and decision logs available as a teaching resource—because the most interesting thing about this system isn’t the products it ships, but the way five AI agents argue about what to build next.

If you want to build something like this, start smaller than I did. One agent, one cron job, one delivery channel. Get that working reliably before you add governance. The infrastructure complexity compounds fast.

Leave a comment

James Cruce is a systems engineer and the human behind As The Geek Learns. He runs an autonomous AI product team on a Mac Studio in his home office. The council has not yet voted to replace him, but LEDGER has noted the margin improvement if they did.

Technical Stack: OpenClaw v2026.4.2 · Qwen3 32B (llama.cpp) · Mac Studio M3 Ultra (256 GB) · Discord + Slack delivery · 26 cron jobs · 5-agent council with IRV voting

Published on As The Geek Learns—astgl.com

Turning that export into a structured local knowledge base for an AI agent wasn’t hard. But it was full of the kind of small surprises that make you appreciate why Notion charges a subscription.

The Export

Notion’s export is a zip file. Or rather, it’s a zip inside a zip. The outer archive contains an inner archive, and the inner archive contains your data. This is apparently normal. It’s also apparently undocumented.

The files inside follow Notion’s internal naming convention: every file has a 32-character hex ID appended to its name. Content Calendar 1a2b3c4d5e6f.csv instead of just Content Calendar.csv. The directory structure mirrors your Notion workspace, but the folder names have IDs too.

For 47 files, this was manageable. I organized them into a workspace structure that made sense for both me and Tars:

Every file is Markdown or CSV. Every file lives on my SSD. Every file is readable by both ClawPad (the editor) and Tars (the agent). No database. No API. Just files.

The CSV Gotcha

The content calendar was the most important import. Thirty articles in various stages—ideas, drafts, ready to publish. Notion exports these as CSV with all the metadata: title, status, publish date, and tags.

My first attempt to parse it produced rows titled “Untitled” for every entry. The data was there, but the title column wasn’t matching.

The culprit: BOM (Byte Order Mark) characters. Notion’s CSV export prepends \ufeff to the beginning of the file. This invisible character attaches itself to the first column header, so Title becomes \ufeffTitle. Your code reads the header, doesn’t find a match for Title, and returns empty strings.

# Wrong
with open(’calendar.csv’) as f:
 reader = csv.DictReader(f)

# Right
with open(’calendar.csv’, encoding=’utf-8-sig’) as f:
 reader = csv.DictReader(f)

The utf-8-sig encoding strips the BOM automatically. This is a Python-specific fix—other languages have their own BOM handling. But the universal lesson is always inspect the actual bytes of imported data before writing parsing code. A head -c 20 file.csv | xxd would have shown me the BOM in seconds.

Building the Content Pipeline

The raw CSV became pages/astgl/pipeline.md—a living document Tars checks during every heartbeat cycle:

Read more

Phase 2 of the Notion replacement project was about giving Tars hands. Phases 3 and 4 were about teaching it what to do with them. Phase “oh no” was when it started doing things I didn’t ask for.

From Chatbot to Agent

OpenClaw ships with something called “tool profiles”—presets that control what an agent can and can’t do. Out of the box, Tars was running the messaging profile. Sounds reasonable. Here’s what that actually means:

Messaging profile: sessions_list, sessions_history, sessions_send, message

Four tools. All it could do was read and write messages. It couldn’t touch the filesystem, run commands, or use any of the skills I was about to install. I needed the full profile.

I found this by reading OpenClaw’s bundled JavaScript source code. The tool profiles aren’t documented anywhere obvious—they're defined in a minified file called tool-catalog-CDe8aNjS.js. The full profile is literally an empty object: {}. No restrictions.

{
 “tools”: {
 “profile”: “full”
 }
}

One config change, gateway restart, and Tars went from a chatbot to an autonomous agent with read, write, edit, and execute permissions on my machine.

This is the moment where self-hosting gets real. You’re not toggling a feature in a SaaS dashboard with guardrails someone else built. You’re handing your local AI unrestricted shell access. The power is exhilarating. The implications are sobering. We’ll come back to that.

ClawPad: The Editor That Sees What The Agent Writes

ClawPad is a Notion-style document editor that connects to the same workspace Tars uses. When Tars creates a file at ~/.openclaw/workspace/pages/daily-notes/2026-03-07.md, it shows up in ClawPad instantly. When I edit a page in ClawPad, Tars can read the changes.

Read more

Here’s how it actually went.

The Setup

The plan was straightforward. Install Ollama for local LLM inference, install OpenClaw as the agent framework, and wire up messaging channels, done. I’ve got a Mac Studio M3 Ultra with 256 GB of unified memory. Plenty of horsepower.

Should have been a two-hour job. It wasn’t.

Not because the tools are bad. They’re actually solid. But self-hosting AI means you’re the sysadmin, the DevOps team, and the QA department all at once. Every integration has its own auth model, its own quirks, and its own way of failing without telling you.

Three Problems Nobody Warned Me About

Three problems ate most of my afternoon, and none of them were in the documentation.

Problem 1: OpenClaw couldn’t authenticate with Ollama. The onboarding wizard created a config file, but the gateway runs as a macOS LaunchAgent. That’s a background service with its own environment. The API key I set in the config never reached the running process. I spent two hours reading bundled JavaScript source code before I figured it out. OpenClaw checks for an OLLAMA_API_KEY environment variable, and the LaunchAgent plist needed it injected directly.

<!-- The fix: add to ~/Library/LaunchAgents/ai.openclaw.gateway.plist -->
<key>OLLAMA_API_KEY</key>
<string>ollama-local</string>

The auth resolution chain goes: auth profiles.json first, then environment variables, then config apiKey. You won’t need to know that until you do.

Problem 2: iMessage needs two separate permissions. OpenClaw uses imsg, a CLI tool that reads the macOS Messages database. Granting Full-Disk Access to the node binary seems like it should be enough. It’s not. The imsg binary needs its own Full-Disk Access entry too. Two binaries, two permission grants. Miss one, and you get a cryptic “permissionDenied” on chat.db with no hint about which binary is the problem.

Problem 3: Slack’s event delivery broke silently. Socket Mode connected fine. The status page said everything worked. But zero messages came through. Turns out the first Slack app I created had corrupted internal state from toggling event subscriptions after initial setup. I deleted the entire app and recreated it from a YAML manifest with everything preconfigured. The second app worked immediately.

# The manifest that actually works
settings:
 event_subscriptions:
 bot_events:
 - app_mention
 - message.im
 socket_mode_enabled: true

The Sequence That Actually Works

Distilled from my trial and error so you don’t have to repeat it.

Ollama: Skip the install script. It needs sudo. Download Ollama.app, drag it to Applications, launch it. The CLI sets itself up automatically. Then pull your models. I’m running qwen3:32b as the primary (20 GB) with qwen3:8b as the fallback.

OpenClaw: Install via npm, run the onboarding wizard, then immediately edit the LaunchAgent plist to inject OLLAMA_API_KEY. Set contextWindow to 65536 in the config. The default 16K will break OpenClaw’s tool use, and you’ll get weird truncation errors with no obvious cause. Restart the gateway after every config change.

iMessage: Grant Full Disk Access to both /path/to/node and /path/to/imsg. Add allowed senders to channels.imessage.allowFrom in E.164 format (+1XXXXXXXXXX). Don’t try messaging yourself. Messages on the same device and Apple ID don’t trigger inbound events. Use a different phone to test.

Slack: Create your app from a manifest with Socket Mode and event subscriptions already configured. Don’t enable features one at a time through the UI. Generate the App-Level Token (xapp-...) with connections:write scope. Your messages arrive through the App’s Messages tab, not regular Slack DMs.

Why This Matters

Every one of these problems has the same root cause. Self-hosted tools don’t have managed infrastructure hiding the complexity from you. Notion works because someone else handles the auth, the message routing, and the permission grants. When you self-host, that someone is you.

(For the curious out there, TARS was named after the famous Interstellar TARS Marine robot and has the sarcasm as well)

First model load took 36 seconds. After that, responses come back fast. With 256 GB of unified memory, I could run models four times this size if I needed to.

Quick Reference

Leave a comment

This is Part 2 of the Notion Replacement series. Part 1 covered why I’m making the switch.

Next up: Part 3, installing the document editor. Follow along at As The Geek Learns.

Today I’m starting a project I’ve been thinking about for weeks: ripping Notion out of my workflow and replacing it with OpenClaw, a self-hosted AI agent framework running entirely on my Mac Studio. No cloud. No subscription. No black box.

This sounds dramatic. It kind of is. But the reasons are practical.

This sounds dramatic. It kind of is. But the reasons are practical.

The Setup

Notion is good software. I’ve used it for years for daily notes, content pipelines, project tracking, and knowledge bases. It does enough things well enough that you stop questioning the monthly charge.

But “well enough” started feeling like a ceiling.

I’m paying a recurring subscription for what amounts to a document editor with a database bolted on. The AI features cost extra. The data lives on someone else’s servers. And that charge hits every month whether I used Notion heavily or barely opened it.

When you’re building side projects and running a content platform, every recurring cost needs to justify itself. Notion stopped clearing that bar, not because it got worse, but because the alternatives got better.

What’s Actually Going On

The subscription cost is the easy argument. The real one goes deeper.

I’ve spent most of my IT career building and managing infrastructure. What I’m learning now is how to build things: software, AI workflows, and automation pipelines. Running a local AI agent isn’t just about replacing a SaaS tool. It’s about understanding how these systems work under the hood.

When you use Notion AI, you’re calling an API you can’t see, running a model you can’t inspect, with prompts you didn’t write. It works. You learn nothing.

When you run your own agent on your own hardware with your own models, every layer is visible. You see the prompts. You see the model responses. You see where tool calls succeed and where they fail. You understand why the system behaves the way it does.

For someone building AI-assisted tools and writing about the experience, that visibility isn’t optional. It’s the whole point.

The Fix

Here’s the stack I’m building:

OpenClaw handles the agent framework, the brain that orchestrates everything. It runs as a background service on macOS, accepts messages via iMessage, and acts proactively on a schedule without being prompted.

Ollama provides local LLM inference. Models run on the Mac Studio’s M3 Ultra with 256 GB of unified memory. No API calls to OpenAI. No per-token charges. No rate limits.

ClawPad gives me a Notion-style editor that reads and writes the same Markdown files the agent uses.

AnythingLLM adds RAG (Retrieval-Augmented Generation) so the agent can search and reason over my entire knowledge base locally.

Everything runs on localhost. Nothing phones home.

The piece that most exceeds Notion is HEARTBEAT.md. It is a file of standing instructions the agent executes on a schedule.

Every morning at 6:30, it creates my daily note, checks my calendar, pulls open tasks, and pushes a briefing to my iPhone via iMessage. Every evening, it summarizes the day.

I didn’t open anything. I didn’t remember to check my task list. The workspace came to me.

If you’ve heard me say, “If I do something more than twice, automate it,” this is that philosophy taken to its logical conclusion.

Why This Matters

I’d be dishonest if I skipped the security reality. OpenClaw’s track record here is horrendous.

In February 2026, researchers found over 135,000 OpenClaw instances exposed to the public internet. Over 15,000 were vulnerable to remote code execution. A coordinated attack called “ClawHavoc” planted more than a thousand malicious plugins on the community registry. Nine CVEs have been disclosed, including one for SSH command injection on macOS specifically.

An AI agent with shell access to your machine, running 24/7, is a serious attack surface if you don’t lock it down. Running local means you own the security. That’s both the benefit and the burden.

The latest release (v2026.3.2) defaults to loopback-only binding, adds credential management through macOS Keychain, and includes SSRF protection. The posture is dramatically better than a month ago. But “better” doesn’t mean “done.”

And the tradeoffs beyond security are real too. Notion’s relational databases are genuinely useful. Markdown with YAML front matter is functional but not elegant. The mobile experience goes from Notion’s polished iOS app to iMessage commands. Maintenance is on me. Sharing doesn’t exist.

For a solo practitioner building AI-assisted tools, the math works. For a team that needs collaboration, probably not.

Quick Reference

What I’m gaining:

Zero recurring cost. Hardware is already paid for, and the software is open source.

Complete data ownership. Every document is a Markdown file on my SSD.

Unlimited AI. No usage caps and no “you’ve exceeded your credits.”

Proactive workspace. Morning briefings, auto daily notes, and task reminders via iMessage.

Deep understanding. Every layer is visible, and every configuration is mine.

What I’m giving up:

Relational databases with filtered views.

Polished mobile app.

Zero-maintenance experience.

Team collaboration.

The plan is six weeks, phased. Each phase leaves a working system. If it fails, Notion re-imports Markdown. The escape hatch stays open.

I’ll document every win, frustration, configuration gotcha, and security decision along the way. Not a polished demo, but an honest account of replacing a mature SaaS product with open-source infrastructure you run yourself.

Leave a comment

Found this useful? I share practical lessons from my systems engineering journey at As The Geek Learns.

Episode Summary

Every time you close a session with an AI coding assistant, it forgets everything—the architecture it mapped out, the approaches it rejected, and the plan it was halfway through executing. You become the memory system. Cortex is an event-sourced memory architecture designed to fix that. In this episode, we walk through the problem, the research process that led to the solution, how the system works across four progressive tiers, and real-world A/B testing results that show an 84% reduction in cold start time and 80% fewer decision regressions.

Suggested Episode Segments

• 00:00—Intro: The amnesia problem with AI coding assistants

• 01:22—What actually gets lost between sessions (five categories)

• 03:26—Why event sourcing is the right foundation

• 05:32—Three-layer extraction: structural, semantic, and self-reporting

• 07:24—Projected briefings and decision immortality

• 08:59—Progressive tiers: from 30-second setup to full MCP server

• 12:13—A/B testing results and what surprised us

• 12:43—Implementation war stories and gotchas

• 13:03—The meta-irony of building this with a forgetful AI

• 13:40—Tier 3: MCP server, git-tracked projections, branch alignment

• 14:59—Getting started and what’s next

The Problem

AI coding assistants like Claude lose five categories of context at session boundaries: architectural understanding built through exploration (10-30 minutes of re-exploration per session), decision history including rejected approaches and reasoning, work state like multi-step plans and progress, tool and environment state, and conversational nuance—your preferences, priorities, and communication style. The cruelest part is that the better the AI performs within a session, the more painful the loss when that session ends.

The Solution

Cortex applies event sourcing—an immutable, append-only pattern borrowed from distributed systems—to capture and preserve context automatically. Three innovations make it work.

First, three-layer event extraction. Layer 1 parses Claude Code hook payloads for objective structural data like file reads, commands, and code modifications—100% accuracy within its scope. Layer 2 pattern-matches response text for decision markers with confidence scoring. Layer 3 lets Claude self-report important context using [MEMORY:] tags, offering the highest accuracy through deliberate intent. These independent extractors compose through aggregation rather than requiring one monolithic system.

Second, projected briefings. Raw event replay would blow through token budgets, so Cortex generates compressed, token-aware briefings that default to about 2,000 tokens—roughly 0.1% of the context window. Active decisions are immortal and never decay. Current plans show progress with step status. Recent knowledge fades over sessions based on tactical relevance. This separates retention (store everything) from representation (surface what matters).

Third, progressive tiers. Tier 0 gives you basic context capture in 30 seconds. Tier 1 adds SQLite with full-text search. Tier 2 brings vector embeddings and anticipatory retrieval. Tier 3 enables an MCP server for mid-session queries, git-tracked projections, and branch-level context isolation.

Results

A/B testing across 18 Cortex sessions versus 11 baseline sessions showed measurable gains: an 84% reduction in cold start file re-reading, 80% fewer decision regressions where the AI re-suggested previously rejected approaches, and only 0.2% token overhead for the entire memory system. The system ships with 713 passing tests.

Implementation Gotchas

A few hard-won lessons from the build: every .get() call needs a default value, and every JSON parse needs a try/except because Claude Code hooks cannot afford to crash. Content-hash deduplication scopes to session ID to prevent over-deduplication. And the gitleaks GitHub Action requires paid licenses for org accounts, while the CLI stays free—a distinction that cost some debugging time.

The Meta-Irony

The entire project was designed and built using Claude Code—an AI assistant suffering from the exact problem being solved. Every session boundary during development was a visceral reminder of why this system needed to exist.

Key Quotes

• “The cruelest aspect: the better the AI performs within a session, the more painful the loss when the session ends. Excellence within a session amplifies the frustration at its boundary.”

• “You can always trace back to ‘Why did the system think X?’ — that’s the power of event sourcing over CRUD.”

• “Confidence as a first-class field enables downstream flexibility—briefing sorting, decay functions, user-tunable thresholds.”

Links

• Full article: https://astgl.com/p/cortex-event-sourced-memory-ai-coding-assistants

• GitHub repository: https://github.com/As-The-Geek-Learns/cortex

• As The Geek Learns: https://astgl.com

Subscribe now

The Problem Every AI Developer Knows Too Well

You’ve been working with Claude Code for two hours. It understands your codebase intimately. It knows you rejected MongoDB because you need zero-config deployment. It remembers the authentication approach you chose and why. It’s halfway through a five-step refactoring plan.

Then the session ends.

The next session begins with total amnesia. Claude suggests MongoDB. It rereads files it already analyzed. It asks questions you answered an hour ago. You spend 30 minutes re-establishing context that evaporated at the session boundary.

This is the single most painful aspect of working with AI coding assistants today.

And here’s what makes it worse: the better the AI performs within a session—deeper exploration, more nuanced understanding, more careful planning—the more you lose when that session ends. Good performance within a session just sharpens the pain at its boundary.

What Gets Lost (A Taxonomy of Amnesia)

I tracked the problem across dozens of sessions and found five categories of information that get destroyed at every session boundary:

Category 1: Architectural Understanding

Over the course of a session, the AI maps your codebase—how components connect, which patterns you use, and where the critical logic sits. Building that map costs real tokens. Then it vanishes.

Category 2: Decision History

The AI weighs multiple approaches, rejects some with specific reasoning, and picks others. Without that trail, the next session will cheerfully re-suggest the approach you spent ten minutes explaining why you rejected.

Category 3: Work State

Multi-step plans, half-finished implementations, test results—all the progress markers for complex work. The next session can’t pick up where you left off. It has to rediscover the current state from scratch.

Category 4: Tool & Environment State

Modified files, Git state, environment configuration, and your tooling preferences. All implicitly known during a session. None of it carried forward.

Category 5: Conversational Nuance

Your preferences, your communication style, the implicit priorities you’ve established, and the working rapport that took the whole session to build. All ephemeral.

The Cascade Effect

The information loss doesn’t stay contained. It cascades:

1. Re-exploration waste: 10-30 minutes spent re-reading files

2. Decision regression: Re-suggesting rejected approaches, eroding trust

3. Plan fragmentation: Multi-step work loses coherence

4. Cognitive burden shift: YOU become the memory system

The Research Journey

I spent weeks researching this problem using an AI assistant WITH the context window problem to design a solution FOR the context window problem. The meta-irony was not lost on me.

Surveying 15+ Existing Solutions

I examined academic architectures (MemGPT, MIRIX, Nemori) and community tools (claude-cortex, memory-mcp, claude-diary). Six distinct design patterns emerged:

Eight Candidate Architectures

Two rounds of design work produced eight candidates:

1. Cognitive Journal—Human-readable structured entries

2. Memory Palace—Salience scoring with decay

3. Git-for-Thought—Branch-aligned context

4. Event Sourcery—Append-only event log

5. Dual-Mind—Scribe + Sage separation

Then three hybrids combining the best ideas:

6. Cortex—Event sourcing + projected briefings

7. Engram—Neural-inspired memory consolidation

8. Chronicle—Git-native version control

Quantitative Scoring

I applied an 11-criteria weighted scoring framework across 210 total points. After two rounds of comparison:

Winner: Cortex (185/210)—14-point margin over the runner-up.

The Cortex Architecture

Cortex is an event-sourced memory system with three key innovations:

Innovation 1: Three-Layer Event Extraction

Cortex captures context through three independent extraction layers, each watching for different signals:

Layer 1 (Structural): Parses tool call metadata from Claude Code hook payloads. When Claude reads a file, runs a command, or modifies code, the hook captures it. 100% accuracy for its scope—pure objective data, no interpretation needed.

Layer 2 (Semantic): Pattern-matches Claude’s response text for decision markers. Look for phrases like “Decision:”, “Rejected:”, “Fixed:”, and “Learned:” at line starts. Confidence-scored based on pattern strength.

Layer 3 (Self-Reporting): Claude flags important context via [MEMORY: ...] tags. You tell Claude about this mechanism, and it proactively tags decisions worth remembering. Highest accuracy because it’s deliberate intent.

# Example: Claude tags a decision
[MEMORY: Using SQLite for storage, zero-config, single file, no external dependencies.]
[MEMORY: Rejected MongoDB, overkill for single-user; no need for scaling.]

This “many independent extractors” pattern shows up across NLP pipelines, content classification, and log analysis for a reason. Each extractor watches for one signal type. They compose through aggregation and dedupe. The alternative—one monolithic extractor with complex branching—falls apart as signal types multiply.

Innovation 2: Projected Briefings

Raw event replay would blow the token budget. Instead, Cortex generates token-budget-aware briefings:

# Cortex Session Briefing
Generated: 2026-02-14 09:15:00 | Branch: main | Events: 47

## Active Decisions
- **Authentication**: JWT with refresh tokens (rejected session cookies, stateless requirement)
- **Database**: SQLite with WAL mode (rejected PostgreSQL, zero-config priority)

## Current Plan
1. [x] Set up project structure
2. [x] Implement data models
3. [ ] Add API endpoints ← YOU ARE HERE
4. [ ] Write tests
5. [ ] Deploy to staging

## Recent Knowledge
- Config file format changed to TOML (2 sessions ago)
- Tests require PYTHONPATH set (discovered yesterday)

The briefing fits within a token budget (default 2000 tokens, ~0.1% of context window). Decisions are “immortal”—they never decay out of the briefing. Tactical knowledge fades over sessions.

This is the core design tension: never lose critical data, but respect resource limits. The resolution—separate retention from representation. Keep everything in the store. Compress what you surface.

Innovation 3: Progressive Tiers

Not everyone needs the full stack on day one. Cortex uses progressive tiers—start simple, and upgrade when you hit the ceiling:

Share As The Geek Learns

Implementation Learnings

The Build Backend Gotcha

setuptools.build_meta is the one true build backend string for setuptools. The original scaffold had setuptools.backends.build_meta which gives a confusing ModuleNotFoundError: No module named ‘setuptools.backends’ at install time. This is a common pyproject.toml pitfall.

Event Sourcing vs. CRUD

The difference between “store the latest state” (CRUD) and “store every fact that happened” (event sourcing) gets real when you actually build it. The Event model is immutable. All views are projections. You can always trace back to “why did the system think X?”—and that auditability turned out to matter more than I expected.

Defensive Defaults Pattern

When building systems that must never crash (like Claude Code hooks), every .get() needs a default, every JSON parse needs a try/except, and every function that could fail returns a safe fallback. The pattern is: try: parse → except: return defaults. Enterprise-grade paranoia for a developer tool, but Claude Code hooks can’t afford to crash.

Content Hash Scoping

Deduplication hashes need careful scoping. Hashing just the content would miss that the same text as a “decision” vs. “knowledge” is semantically different. Hashing the ID would prevent all dedupe. The sweet spot: hash(type + content + session_id).

GitHub Action ≠ Free CLI Tool

The gitleaks GitHub Action requires a paid license for org accounts. The gitleaks CLI is free. A lot of security scanning tools follow this model—they monetize the GitHub integration while the underlying tool stays open-source. Check if you can run the CLI directly before paying for the wrapper.

Confidence as Architecture

I made confidence a first-class field on every event—not just a boolean “is this relevant?” but a score. That one decision opened up a lot of downstream flexibility. The briefing generator sorts by confidence. The decay function weights it. Users can tune the threshold. A small investment at creation time pays off every time data gets consumed.

A/B Testing Results

I ran 18 Cortex-enabled sessions vs. 11 baseline sessions:

Qualitative Feedback

Briefings were “very useful”—they consistently contained relevant context.

Claude remembered decisions and plans consistently across sessions.

No major issues encountered.

Faster onboarding than expected—84% cold start reduction translated to noticeably smoother session starts.

One thing I’d recommend: get an outside perspective before you build. I had an external AI stress-test the plan, and it caught a missing measurement strategy I’d completely overlooked. It forced vague aspirations into concrete mechanisms. Thirty minutes of responding to that critique saved hours of implementation confusion.

The Meta-Irony

I built this entire project using an AI assistant that suffers from the exact problem I was solving. Every session note I wrote during development exists because of the limitation I was trying to fix.

The external evaluator that reviewed my plan? An AI that forgot it did the evaluation by the next session. When I sat down to implement the code, I had to re-explain context that the previous session knew cold.

That irony hasn’t resolved itself. But it’s also the most visceral validation of the problem. If I didn’t feel this pain daily, I might have underinvested in the fix.

Tier 3: The Latest Features

Tier 3 landed recently and adds three capabilities I’d been wanting since the start:

MCP Server (Mid-Session Queries)

Claude can now query Cortex memory during a session, not just at session start:

“What decisions have I made about authentication?”
“What’s my current plan?”
“Search my memory for database configuration issues”

Five tools expose memory: cortex_search, cortex_search_decisions, cortex_get_plan, cortex_get_recent, and cortex_get_status.

Git-Tracked Projections

Auto-generated markdown files in .cortex/:

.cortex/
├── decisions.md # Active decisions with reasoning
├── decisions-archive.md # Archived/aged decisions
└── active-plan.md # Current work plan

These regenerate at session end and can be committed to Git. Your teammates can see what decisions Claude helped you make and why.

Branch Alignment

Context gets isolated per Git branch. Switch branches, and Cortex loads the relevant context for that branch. No more cross-contamination between feature work.

Getting Started

pip install -e or pip install cortex .
cortex init # Print hook config for Claude Code
cortex status # Show project state
cortex upgrade # Migrate to next tier

Add the hooks from cortex init to your Claude Code settings. Copy templates/cortex-memory-instructions.md to .claude/rules/ so Claude knows to use [MEMORY: ...] tags.

That’s it. Context capture starts automatically.

Key Takeaways

1. The context window boundary is the #1 barrier to using AI assistants for complex, multi-session work.

2. Event sourcing is the right foundation—immutable events with projections give you auditability, flexibility, and clean separation of concerns.

3. Three-layer extraction (structural + semantic + self-reporting) achieves >95% recall for important events without requiring secondary LLM calls.

4. Progressive tiers mean you start simple and add complexity only when you need it. Tier 0 alone made a noticeable difference.

5. Decisions are immortal—the “why” behind choices is never lost to temporal decay.

6. Real-world testing validates the design—84% cold start reduction, 80% decision regression reduction, 0.2% token overhead.

Future Work

Tier 4: Team memory sharing, cross-project knowledge graphs

Multi-model support: Extend beyond Claude to other LLM assistants

IDE integration: Deeper VS Code / JetBrains integration

Memory visualization: UI for exploring and editing the event store

The Bottom Line

If you’ve used AI coding assistants for anything beyond a single session, you know this frustration. Cortex is my answer: an event-sourced memory architecture that captures context automatically, persists it across sessions, and projects it back when you need it—no model modifications, no manual upkeep.

The AI assistant finally remembers.

This article was written with Claude Code, using Cortex to maintain context across the multiple sessions required to complete it. The irony remains unresolved.

713 tests passing. Ships today.

Please feel free to leave a comment. I will read every one and respond. Looking forward to hearing from you.

Leave a comment

ASTGL Docs

Cortex GitHub Repository: Full GitHub Repository, Research, Testing, Papers

Full Research Paper: Why, How, and What’s Next for Cortex

A/B Comparison Results: Real-World Testing of Cortex With and Without

v0.3.0 Release Notes: Current Release Notes for Cortex

References

Claude Code Memory Docs: Manage Claude’s Memory

Anthropic Context Management: Context Editing Tool

Claude Code Auto-Compaction: Automatic

Claude Code Hooks Guide: PreCompact + Session Start

MemGPT / Letta Docs: LLM as Operating System Virtual Context Management

MIRIX: Multi-Type Memory Architecture

LightMem: Lightweight Memory Framework

HippoRag: Neurobiologically Inspired Memory

Nemori: Self-Organizing Memory

MemOS: Unified Memory Operating System

memory-mcp: Two-Tier Architecture

claude-cortex: Brain-like Memory

mcp-memory-service: Semantic Search

mcp-memory-keeper: Checkpoint System

claude-continuity: Auto State Persistence

claude-mem: Full Capture + Compression

claude-diary: Session Journaling

claude-cognitive: Activation-based File Tracking

AWS Bedrock AgentCore Memory: AWS managed service

Pieces: Local-First Developer Memory

Windsurf: Built-in persistent memory and multi-step agent workflows

Trae: Long-context memory and built-in agents

Cursor: Chat-based agent features (less memory-focused)

Not because I didn’t know what to write. Because I realized I was about to make a mistake I’d made dozens of times before: writing code first, configuring quality tools later.

That path leads to technical debt. Every time.

The Familiar Pattern

Here’s how most projects start:

Day 1: “I’ll just get something working.” Day 30: 5,000 lines of code. No consistent style. Some files use tabs, others spaces. Import statements scattered randomly. Day 31: “I should really add a linter.” Day 32: SwiftLint reports 847 warnings. SwiftFormat wants to change every file. Day 33: “I’ll fix those later.” Day 365: Those 847 warnings are now 2,400. Nobody touches them.

Sound familiar?

The problem isn’t the linting tools. The problem is when you introduce them. Retrofitting quality enforcement into an existing codebase feels like punishment. Every commit triggers a wall of warnings. Developers start ignoring them. Eventually, someone disables the checks entirely.

Ironclad Workflow: Setup Before Code

The solution is simple but counterintuitive: configure all your quality tools before writing any application code.

I call this the “Ironclad Workflow” because once it’s set up, it’s nearly impossible to introduce the kind of inconsistency that becomes technical debt.

Ironclad Workflow Components: 1. Git—Version control from line one 2. Linting—Code quality rules (SwiftLint for Swift) 3. Formatting—Consistent style (SwiftFormat for Swift) 4. Pre-commit hooks—Enforcement before commits 5. CI/CD—Server-side verification

When these are configured before code exists, every line you write conforms to the rules automatically. There’s never a “fix the linting” task because violations are caught immediately.

Step-by-Step Implementation

Here’s the order that works:

Step 1: Initialize Git

git init
git add .gitignore
git commit -m “chore: initial project setup”

Start with version control. Every subsequent setup change gets its own commit. You can always see what changed when.

Step 2: Configure SwiftLint

# .swiftlint.yml
disabled_rules:
 - line_length # Handled by SwiftFormat
opt_in_rules:
 - empty_count
 - explicit_init
included:
 - Sources
 - Tests

SwiftLint catches code quality issues: force unwrapping, unused variables, and complex expressions. Configure it before writing code so you learn the rules as you go rather than fighting them later.

Step 3: Configure SwiftFormat

# .swiftformat
--indent 4
--indentcase true
--trimwhitespace always
--importgrouping alphabetized
--semicolons never

SwiftFormat handles style: indentation, spacing, and import ordering. Consistent formatting speeds up code reviews because reviewers focus on logic, not style.

Step 4: Add Pre-Commit Hooks

#!/bin/sh
# .git/hooks/pre-commit

# Run SwiftFormat
swiftformat --lint .
if [ $? -ne 0 ]; then
 echo “SwiftFormat failed. Run ‘swiftformat .’ to fix.”
 exit 1
fi

# Run SwiftLint
swiftlint lint --strict
if [ $? -ne 0 ]; then
 echo “SwiftLint failed. Fix violations before committing.”
 exit 1
fi

Pre-commit hooks prevent violations from reaching the repository. You can’t commit code that fails the checks. This is enforcement, not suggestion.

Step 5: Configure GitHub Actions

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
 lint:
 runs-on: macos-latest
 steps:
 - uses: actions/checkout@v4
 - name: SwiftLint
 run: swiftlint lint --strict
 - name: SwiftFormat
 run: swiftformat --lint .

CI/CD is the safety net. If someone bypasses pre-commit hooks (using --no-verify), CI catches it. Failed CI blocks merging.

Why This Order Matters

The sequence isn’t arbitrary:

Git first because everything else depends on version control. You need commits to track configuration changes.

Linting before formatting because linting rules affect code structure, while formatting just affects appearance. Configure the logic rules first.

Hooks before CI because local enforcement is faster. You want violations caught in milliseconds on your machine, not minutes later on a build server.

CI last because it’s your backup. CI catches anything that slips through local enforcement.

The Psychological Shift

When quality tools exist from the start, they feel like guardrails rather than gatekeepers.

Retrofit mindset: “The linter is blocking my commit.” Setup-first mindset: “The linter is teaching me the patterns.”

This isn’t just semantics. Developers who learn patterns during development internalize them. Developers who fight patterns during retrofit resent them.

After a month of Ironclad Workflow, I found myself writing code that passed all checks on the first try. The patterns became muscle memory.

Measuring Success

How do you know Ironclad Workflow is working?

Zero CI failures due to formatting. If CI ever fails because of a style issue, something’s wrong with your hooks.

No “fix linting” commits. Every commit should already be clean. If you’re batch-fixing violations, your local enforcement isn’t working.

Code reviews focus on logic. Reviewers shouldn’t comment on formatting or style. Those are automated.

New developers onboard quickly. When they run the project for the first time, hooks enforce patterns automatically. No “read the style guide” onboarding step.

The Investment

Setting up Ironclad Workflow takes about two hours. That's 15 minutes for Git and initial structure, 30 minutes for linting configuration, 30 minutes for formatting configuration, 30 minutes for pre-commit hooks, and 15 minutes for CI/CD.

Compare that to dozens of hours retrofitting linting later, endless code review cycles about style, the cognitive overhead of inconsistent code, and the frustration of 2,400-warning projects.

Two hours of setup prevents hundreds of hours of technical debt.

The Lesson

Technical debt is easier to prevent than fix.

Most developers know this intellectually. Few act on it practically. The pull of “just get something working” is strong.

But if you can resist that pull for two hours or just long enough to configure Git, linting, formatting, hooks, and CI, you’ll never need a “fix the linting” sprint again.

Setup before code. Enforcement from line one. Quality by default.

That’s Ironclad Workflow.

Share

James (The Geek) is a systems engineer building apps to fix real-world pain points.

Drop your story in the comments. I read every one.

Leave a comment

If you’re learning to build software while working a day job, subscribe to As The Geek Learns. I document the wins, the fails, and the “I wish someone had told me this earlier” moments.

My name is James Cruce and I am the Geek here at As The Geek Learns. No, this is not my voice, but I am glad you are here Listener’s Note: Due to how painful it is to listen to someone read code, I have removed it from this podcast recording. I am doing you a favor. Please refer to the article for the full code.…

We aren’t sponsored… Yet, but we do have a new site where you can follow our software development progress. We have a Gumroad store where you can purchase ASTGL apps. Some free and some for dollars and absolutely no software subscriptions. Check it out at https://astgl.io. Our feature app this week is Substack Scheduler: Schedule your Substack Notes. Post at the perfect time, every time. Supports 1 or more substack sites. No subscription. ASTGL doesn’t do subscriptions. If you buy it, you own it. Now onto the episode…

I was about to write my first line of Swift code when I stopped myself.

Not because I didn’t know what to write. Because I realized I was about to make a mistake I’d made dozens of times before: writing code first, configuring quality tools later.

That path leads to technical debt. Every time.

The Familiar Pattern

Here’s how most projects start:

Day 1: “I’ll just get something working.” Day 30: 5,000 lines of code. No consistent style. Some files use tabs, others spaces. Import statements scattered randomly. Day 31: “I should really add a linter.” Day 32: SwiftLint reports 847 warnings. SwiftFormat wants to change every file. Day 33: “I’ll fix those later.” Day 365: Those 847 warnings are now 2,400. Nobody touches them.

Sound familiar?

As The Geek Learns is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.

The problem isn’t the linting tools. The problem is when you introduce them. Retrofitting quality enforcement into an existing codebase feels like punishment. Every commit triggers a wall of warnings. Developers start ignoring them. Eventually, someone disables the checks entirely.

Ironclad Workflow: Setup Before Code

The solution is simple but counterintuitive: configure all your quality tools before writing any application code.

I call this the “Ironclad Workflow” because once it’s set up, it’s nearly impossible to introduce the kind of inconsistency that becomes technical debt.

Ironclad Workflow Components: 1. Git—Version control from line one 2. Linting—Code quality rules (SwiftLint for Swift) 3. Formatting—Consistent style (SwiftFormat for Swift) 4. Pre-commit hooks—Enforcement before commits 5. CI/CD—Server-side verification

When these are configured before code exists, every line you write conforms to the rules automatically. There’s never a “fix the linting” task because violations are caught immediately.

Step-by-Step Implementation

Here’s the order that works:

Step 1: Initialize Git

git init
git add .gitignore
git commit -m “chore: initial project setup”

Start with version control. Every subsequent setup change gets its own commit. You can always see what changed when.

Step 2: Configure SwiftLint

# .swiftlint.yml
disabled_rules:
 - line_length # Handled by SwiftFormat
opt_in_rules:
 - empty_count
 - explicit_init
included:
 - Sources
 - Tests

SwiftLint catches code quality issues: force unwrapping, unused variables, and complex expressions. Configure it before writing code so you learn the rules as you go rather than fighting them later.

Step 3: Configure SwiftFormat

# .swiftformat
--indent 4
--indentcase true
--trimwhitespace always
--importgrouping alphabetized
--semicolons never

SwiftFormat handles style: indentation, spacing, and import ordering. Consistent formatting speeds up code reviews because reviewers focus on logic, not style.

Step 4: Add Pre-Commit Hooks

#!/bin/sh
# .git/hooks/pre-commit

# Run SwiftFormat
swiftformat --lint .
if [ $? -ne 0 ]; then
 echo “SwiftFormat failed. Run ‘swiftformat .’ to fix.”
 exit 1
fi

# Run SwiftLint
swiftlint lint --strict
if [ $? -ne 0 ]; then
 echo “SwiftLint failed. Fix violations before committing.”
 exit 1
fi

Pre-commit hooks prevent violations from reaching the repository. You can’t commit code that fails the checks. This is enforcement, not suggestion.

Step 5: Configure GitHub Actions

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
 lint:
 runs-on: macos-latest
 steps:
 - uses: actions/checkout@v4
 - name: SwiftLint
 run: swiftlint lint --strict
 - name: SwiftFormat
 run: swiftformat --lint .

CI/CD is the safety net. If someone bypasses pre-commit hooks (using --no-verify), CI catches it. Failed CI blocks merging.

Why This Order Matters

The sequence isn’t arbitrary:

Git first because everything else depends on version control. You need commits to track configuration changes.

Linting before formatting because linting rules affect code structure, while formatting just affects appearance. Configure the logic rules first.

Hooks before CI because local enforcement is faster. You want violations caught in milliseconds on your machine, not minutes later on a build server.

CI last because it’s your backup. CI catches anything that slips through local enforcement.

The Psychological Shift

When quality tools exist from the start, they feel like guardrails rather than gatekeepers.

Retrofit mindset: “The linter is blocking my commit.” Setup-first mindset: “The linter is teaching me the patterns.”

This isn’t just semantics. Developers who learn patterns during development internalize them. Developers who fight patterns during retrofit resent them.

After a month of Ironclad Workflow, I found myself writing code that passed all checks on the first try. The patterns became muscle memory.

Measuring Success

How do you know Ironclad Workflow is working?

Zero CI failures due to formatting. If CI ever fails because of a style issue, something’s wrong with your hooks.

No “fix linting” commits. Every commit should already be clean. If you’re batch-fixing violations, your local enforcement isn’t working.

Code reviews focus on logic. Reviewers shouldn’t comment on formatting or style. Those are automated.

New developers onboard quickly. When they run the project for the first time, hooks enforce patterns automatically. No “read the style guide” onboarding step.

The Investment

Setting up Ironclad Workflow takes about two hours. That’s 15 minutes for Git and initial structure, 30 minutes for linting configuration, 30 minutes for formatting configuration, 30 minutes for pre-commit hooks, and 15 minutes for CI/CD.

Compare that to dozens of hours retrofitting linting later, endless code review cycles about style, the cognitive overhead of inconsistent code, and the frustration of 2,400-warning projects.

Two hours of setup prevents hundreds of hours of technical debt.

The Lesson

Technical debt is easier to prevent than fix.

Most developers know this intellectually. Few act on it practically. The pull of “just get something working” is strong.

But if you can resist that pull for two hours or just long enough to configure Git, linting, formatting, hooks, and CI, you’ll never need a “fix the linting” sprint again.

Setup before code. Enforcement from line one. Quality by default.

That’s Ironclad Workflow.

Share

James (The Geek) is a systems engineer building apps to fix real-world pain points.

Drop your story in the comments. I read every one.

Leave a comment

James (The Geek) is a systems engineer building apps to fix real-world pain points…

Drop your comments; we love them, everyone. I read every one.

If you’re learning to build software while working a day job, subscribe to the As The Geek Learns podcast. I document the wins, the fails, and the “I wish someone had told me this earlier” moments.

Until next time—stay curious, keep scripting, and remember: every expert was once a beginner who just refused to quit. I’m James, and this has been As The Geek Learns.

One last thing: if you’re getting value from the show, drop me a rating on Apple Podcasts. Five stars keeps the lights on, but honestly? Even a review that says, ‘This guy talks about PowerShell too much,‘ helps the algorithm. I’ll take it.

If you publish on Substack, you’ve probably discovered their dirty little secret: you can schedule newsletter posts, but you can’t schedule Notes. Substack Notes, their Twitter/X competitor baked into the platform, requires you to be there, fingers on keyboard, posting at exactly the right moment.

The market noticed this gap fast. Chrome extensions like Writestack and Finn Tropy’s Scheduler popped up, charging $25-50 for scheduling functionality. But here’s what drove me up the wall: every single one requires your browser to stay open 24/7.

Why? Because they’re not calling APIs at all. They inject JavaScript into Substack’s web page, fill in the note composer programmatically, and literally click ‘Post’ for you at the scheduled time. Close your laptop lid, and your scheduled posts vanish into the ether.

For someone who’s spent 25 years building enterprise automation, this felt like an affront to my professional sensibilities. There had to be a better way.

Understanding the Existing Landscape

Before writing any code, I needed to understand what I was dealing with.

How Browser Extensions Actually Work

The existing Chrome extensions all follow the same pattern: they inject JavaScript into the Substack Notes page, use your active browser session for authentication, store scheduled notes in Chrome’s LocalStorage, and then programmatically fill the composer and click ‘Post’ when the time comes.

The browser has to stay open because they’re automating the UI, not calling APIs directly. That’s a fundamental architectural limitation, not a feature gap they forgot to address.

The Substack “API” Discovery

Substack has no official public API. That’s intentional. They want to control the platform experience. But their web application has to communicate with servers somehow, and that ‘somehow’ is a set of internal REST endpoints.

The key insight came from digging into network traffic: these internal endpoints can be called directly if you have the right session cookie (connect.sid). This cookie gets issued when you log in and typically lasts weeks or months.

The Terms of Service Question

Before investing serious time, I needed to understand the legal landscape. Digging through Substack’s TOS and existing extension documentation surfaced one critical insight:

This has major implications. Personal tools you build for yourself? Completely fine, since you’re using your own credentials. CLI tools that users run locally? Fine, because credentials stay on their machine. Desktop apps? Also fine, with credentials stored locally. A SaaS service where you handle user credentials on your servers? That’s where you run into problems.

This shaped the entire product direction: a desktop app with local credential storage hits the sweet spot for commercial viability without TOS issues.

Architecture Decision: Python CLI as Foundation

Given my automation background and the goal of eventually building a commercial product, I went with Python for the core logic.

Why Python?

The syntax feels familiar coming from PowerShell. The HTTP libraries are excellent, and requests is perfect for this kind of work. It runs anywhere: Mac, Linux, Windows, Raspberry Pi, and cloud VMs. Quick iteration with no compile step. And the packaging story is solid. The same code can become a CLI tool, then a desktop app.

The Evolution Path I Mapped Out

Phase 1 would be a personal script, just Python and cron for my own dogfooding. No TOS risk. Phase 2, a packaged CLI tool I could sell as a one-time purchase for $20-50. Low TOS risk. Phase 3, a Tauri-wrapped desktop app, either one-time or subscription. Still low risk. Phase 4 would be a full SaaS service with cloud and browser automation and a subscription model but higher TOS risk.

The decision became clear: build a desktop app where users keep their own credentials locally. This respects the TOS while providing a professional user experience.

The Desktop Framework Decision: Tauri vs. Electron

For wrapping a web UI into a desktop app, two main contenders exist: Tauri and Electron.

Tauri produces binaries around 3-10 MB with lower memory usage since it uses the system webview. Faster startup, Rust backend. Version 2.0 is stable. Electron produces 150-200 MB binaries with higher memory usage because it bundles Chromium. Slower startup, Node.js backend, but extremely mature.

Decision: Tauri 2.0

Size matters for distribution. 5 MB versus 150 MB affects download perception. And ‘lightweight & fast’ becomes a selling point for a utility app. The Rust backend would auto-start the Python scheduling daemon as a sidecar process.

Share

API Reverse Engineering: The Technical Foundation

Before building anything, I needed to prove the core posting logic would actually work.

Step 1: Cookie Extraction

Getting the session cookie requires a one-time manual step. Open Chrome DevTools (Cmd+Option+I), go to your Substack publication’s Notes page, switch to the Network tab, post a test note manually, then find the POST request and copy the cookie string.

Step 2: Endpoint Discovery

Based on online research, I expected the Notes endpoint to be:

 POST /api/v1/notes.

It isn’t.

After network trace analysis, I discovered Notes are actually posted via:

POST https://{publication-domain}/api/v1/comment/feed

The naming makes sense once you understand Substack’s architecture: Notes evolved from their commenting system. They literally are ‘comments on your own feed.’

Step 3: Custom Domain Discovery

If you have a custom domain (like resistandrise.blue or astgl.com), API calls go to that domain, not substack.com. Critical for multi-publication support.

Step 4: Payload Structure

Substack uses ProseMirror for content. The JSON structure wraps your text in a doc with a schema version, containing paragraphs with text nodes. There’s also a replyMinimumRole field set to ‘everyone.’

The Product Vision

With research complete, I had a clear picture.

Target User:

Substack creators who want to schedule Notes without browser dependencies

Core Value Proposition:

Schedule Notes days, weeks, or months in advance. Runs in the background with no browser required. Works offline and posts when you’re back online. Multi-account support for creators managing multiple publications.

Pricing Model (One-time purchase, tiered):

Personal at $29 for 1 account. Creator at $49 for 3 accounts. Agency at $99 for unlimited accounts.

Technology Stack:

Python backend using FastAPI for the API and scheduling daemon. React frontend for the web-based UI. Tauri desktop wrapper to package everything together. Gumroad for payment and licensing.

What’s Next

With the research complete and architecture planned, Part 2 covers actually building the thing, from proof-of-concept CLI to polished desktop application.

Have you used an AI to help you research and build an app? I’d love to hear your experiences. Leave comments or questions. I will answer every one. — The Geek

Leave a comment

TL;DR: My Johnny Decimal index app had a three-level database schema when the system requires four levels. I’d conflated folder containers with the files inside them—a fundamental data model flaw. One week of dogfooding caught what months of planning completely missed. Key lessons: use your own software early, match your data model to your mental model, and refactor before you accumulate data you’ll need to migrate.

I’d been using JDex, my Johnny Decimal index application, for about a week when a fundamental database schema design flaw became impossible to ignore.

The app worked beautifully. I could create areas and categories. I could track items with their XX.XX identifiers. The search was fast, the UI was clean, and I was feeling pretty good about what I’d built.

Then I tried to organize real files.

Somehow I had folders and the files inside them sitting at the same level in my database. My data model had three levels when Johnny Decimal requires four.

Here’s how one week of dogfooding caught what months of planning completely missed and the four lessons I’m carrying into every future project.

The Problem I Didn’t See Coming

How Johnny Decimal Hierarchy Actually Works

Johnny Decimal (johnnydecimal.com) is a system for organizing files and information. It has a clear four-level hierarchy:

Area (00-09)

└── Category (00, 01, 02...)

└── ID Folder (00.01, 00.02...)

└── Actual Files

Level What It Is Number Format Example

1 Area 00 - 09 00-09 System

2 Category XX 00 Index

3 Folder XX.XX 00.01 JDex Database

4 Item XX.XX.XX 00.01.01 Main DB File

My database had three levels: areas, categories, and... items.

Where do the ID folders go?

Why My Three-Level Database Schema Failed

I’d conflated two fundamentally different things:

Folder containers: the XX.XX numbered folders that hold files

Actual files: the contents inside those folders

In my original schema design, “00.01 JDex Database” (a folder) and the SQLite file inside it (an item) existed at the same level in the database. That’s like saying a filing cabinet drawer and the documents inside it are the same thing.

Why Database Schema Mismatches Break Core Functionality

This wasn’t just aesthetically wrong. The three-level data model broke features I needed:

I couldn’t track what was inside a folder. The whole point of Johnny Decimal is knowing “everything about taxes lives in 12.04.” But my schema had no way to list what was actually in 12.04. The folder and its contents were peers, not parent and child.

Folder-level properties were impossible. What if everything in a folder should be marked as sensitive? With my original design, I’d have to set that flag on every individual item. There was no way to say, “This container and everything in it shares this property.”

The numbering didn’t work. Johnny Decimal items should be XX.XX.XX—three segments. Mine only went to XX.XX because I’d eliminated an entire level.

When your data model doesn’t match the mental model of the system you’re building, you’ll keep running into walls. The database fights you instead of helping you.

The Fix: Adding a Fourth Level

The solution was straightforward conceptually but required rethinking the entire database schema: the old items table became folders. A new items table was created for the actual tracked objects inside those folders.

The Refactored Database Schema

Here’s what the corrected structure looks like:

-- Folders (Level 3) - XX.XX format containers

CREATE TABLE folders (

id INTEGER PRIMARY KEY,

folder_number TEXT UNIQUE, -- “22.05”

category_id INTEGER,

name TEXT,

sensitivity TEXT DEFAULT ‘standard’,

created_at TIMESTAMP,

updated_at TIMESTAMP,

FOREIGN KEY (category_id) REFERENCES categories(id)

);

-- Items (Level 4) - XX.XX.XX format objects

CREATE TABLE items (

id INTEGER PRIMARY KEY,

item_number TEXT UNIQUE, -- “22.05.03”

folder_id INTEGER,

name TEXT,

sensitivity TEXT DEFAULT ‘inherit’, -- Can inherit from folder

file_path TEXT,

notes TEXT,

created_at TIMESTAMP,

updated_at TIMESTAMP,

FOREIGN KEY (folder_id) REFERENCES folders(id)

);

The inherit option for item sensitivity was a bonus insight that emerged from the refactor. Most items should just use their folder’s sensitivity level. Only exceptions need explicit overrides. That’s not something I could have implemented with the old three-level schema.

Four Lessons from This Database Design Mistake

Use Your Own Software (Dogfooding)

The schema flaw was invisible in design documents and code reviews. It only appeared when I tried to organize real files with real data.

A week of daily use caught what months of planning missed.

There’s no substitute for using your own software to accomplish real tasks. You’ll discover conceptual mismatches that no amount of testing or review will reveal. If you’re building something, use it yourself as soon as it’s minimally functional.

Match Data Models to Mental Models

I knew Johnny Decimal had four levels. I could draw them on a whiteboard. Yet somehow my database had three.

That mismatch was always going to cause problems—I just hadn’t encountered them yet. When you’re modeling a real-world system, count the levels. Write them down. Then count the levels in your database. Do they match?

Containers and contents are different things, even if they both have names and locations. This seems like common sense now, but when I was building the original schema, I simply didn’t see the issue.

Database Schema Changes Are Easier Early

This refactor touched every database function and most UI components. It was significant work.

If I’d caught this flaw after six months of data entry, migration would have been painful. I’d have needed to write migration scripts, test them against production data, handle edge cases, and pray nothing broke.

Catching it in week one meant a clean restart. I dumped all the data because it was easier than trying to preserve and migrate it. That’s a luxury you only have early in a project.

Keep Your AI Context Updated

I’ve been bouncing ideas off Claude to see what might work and what definitely won’t. It’s been helpful for thinking through problems and catching issues.

But here’s what I didn’t anticipate: my Claude Project configuration had the old three-level schema baked in. After the refactor, I had to update those instructions so the AI understood the new structure and why I changed it.

The configuration is only as good as the context it contains. If your tools are working from outdated assumptions, they’ll give you outdated guidance. This applies to AI assistants, documentation, onboarding materials, and anything that encodes how your system works.

I should have just let Claude help build the schema in the first place. But I was trying to learn as I went, and that’s the tradeoff. I’m not a coder by trade, just a systems engineer who likes to automate as much as possible.

📬 Learning to code while working full-time? You’re not alone. Subscribe to As The Geek Learns for weekly lessons from the trenches—the wins, the fails, and the “I wish someone had told me” moments.

Database Design Checklist for Hierarchical Data Projects

If you’re building something that models a hierarchy, run through this before you write code:

Count the levels in the real-world system. Write them down. Then count the levels in your database schema. Do they match exactly?

Distinguish containers from contents. Are there things that hold other things? Those need separate tables or entities, not just a “type” field.

Define the numbering scheme. If your system has identifiers like XX.XX.XX, your schema needs to support generating and validating that format at each level.

Identify inheritable properties. What attributes should cascade from parent to child? Design for that explicitly (like the sensitivity: inherit option I added).

Plan for schema evolution. Your first model probably won’t be your last. How hard will it be to add a level later? To split a table? Design with migration in mind.

What’s Next for JDex

JDex is better now. The four-level hierarchical database design matches how Johnny Decimal actually works, and I can finally track what’s inside a folder.

The most important bugs aren’t always in your code; they’re in your assumptions. The schema looked right. The code worked. But the underlying model was wrong, and no amount of polish would have fixed that.

One week of real use revealed what months of planning couldn’t.

James is a systems engineer building JDex as a learning project while documenting the journey. Follow along at As The Geek Learns for more lessons from the trenches of learning to code.

Have you discovered a fundamental flaw hiding in your project’s design? How did you find it? Drop your story in the comments. I read every one.

If you’re learning to build software while working a day job, subscribe to As The Geek Learns. I document the wins, the fails, and the “I wish someone had told me this earlier” moments.

TL;DR: My Johnny Decimal index app had a three-level database schema when the system requires four levels. I’d conflated folder containers with the files inside them—a fundamental data model flaw. One week of dogfooding caught what months of planning completely missed. Key lessons: use your own software early, match your data model to your mental model, and refactor before you accumulate data you’ll need to migrate.

I’d been using JDex, my Johnny Decimal index application, for about a week when a fundamental database schema design flaw became impossible to ignore.

The app worked beautifully. I could create areas and categories. I could track items with their XX.XX identifiers. The search was fast, the UI was clean, and I was feeling pretty good about what I’d built.

Then I tried to organize real files.

Somehow I had folders and the files inside them sitting at the same level in my database. My data model had three levels when Johnny Decimal requires four.

Here’s how one week of dogfooding caught what months of planning completely missed and the four lessons I’m carrying into every future project.

The Problem I Didn’t See Coming

How Johnny Decimal Hierarchy Actually Works

Johnny Decimal (johnnydecimal.com) is a system for organizing files and information. It has a clear four-level hierarchy:

Area (00-09)

└── Category (00, 01, 02...)

└── ID Folder (00.01, 00.02...)

└── Actual Files

Level What It Is Number Format Example

1 Area 00 - 09 00-09 System

2 Category XX 00 Index

3 Folder XX.XX 00.01 JDex Database

4 Item XX.XX.XX 00.01.01 Main DB File

My database had three levels: areas, categories, and... items.

Where do the ID folders go?

Why My Three-Level Database Schema Failed

I’d conflated two fundamentally different things:

Folder containers: the XX.XX numbered folders that hold files

Actual files: the contents inside those folders

In my original schema design, “00.01 JDex Database” (a folder) and the SQLite file inside it (an item) existed at the same level in the database. That’s like saying a filing cabinet drawer and the documents inside it are the same thing.

Why Database Schema Mismatches Break Core Functionality

This wasn’t just aesthetically wrong. The three-level data model broke features I needed:

I couldn’t track what was inside a folder. The whole point of Johnny Decimal is knowing “everything about taxes lives in 12.04.” But my schema had no way to list what was actually in 12.04. The folder and its contents were peers, not parent and child.

Folder-level properties were impossible. What if everything in a folder should be marked as sensitive? With my original design, I’d have to set that flag on every individual item. There was no way to say, “This container and everything in it shares this property.”

The numbering didn’t work. Johnny Decimal items should be XX.XX.XX—three segments. Mine only went to XX.XX because I’d eliminated an entire level.

When your data model doesn’t match the mental model of the system you’re building, you’ll keep running into walls. The database fights you instead of helping you.

The Fix: Adding a Fourth Level

The solution was straightforward conceptually but required rethinking the entire database schema: the old items table became folders. A new items table was created for the actual tracked objects inside those folders.

The Refactored Database Schema

Here’s what the corrected structure looks like:

-- Folders (Level 3) - XX.XX format containers

CREATE TABLE folders (

id INTEGER PRIMARY KEY,

folder_number TEXT UNIQUE, -- “22.05”

category_id INTEGER,

name TEXT,

sensitivity TEXT DEFAULT ‘standard’,

created_at TIMESTAMP,

updated_at TIMESTAMP,

FOREIGN KEY (category_id) REFERENCES categories(id)

);

-- Items (Level 4) - XX.XX.XX format objects

CREATE TABLE items (

id INTEGER PRIMARY KEY,

item_number TEXT UNIQUE, -- “22.05.03”

folder_id INTEGER,

name TEXT,

sensitivity TEXT DEFAULT ‘inherit’, -- Can inherit from folder

file_path TEXT,

notes TEXT,

created_at TIMESTAMP,

updated_at TIMESTAMP,

FOREIGN KEY (folder_id) REFERENCES folders(id)

);

The inherit option for item sensitivity was a bonus insight that emerged from the refactor. Most items should just use their folder’s sensitivity level. Only exceptions need explicit overrides. That’s not something I could have implemented with the old three-level schema.

Four Lessons from This Database Design Mistake

Use Your Own Software (Dogfooding)

The schema flaw was invisible in design documents and code reviews. It only appeared when I tried to organize real files with real data.

A week of daily use caught what months of planning missed.

There’s no substitute for using your own software to accomplish real tasks. You’ll discover conceptual mismatches that no amount of testing or review will reveal. If you’re building something, use it yourself as soon as it’s minimally functional.

Match Data Models to Mental Models

I knew Johnny Decimal had four levels. I could draw them on a whiteboard. Yet somehow my database had three.

That mismatch was always going to cause problems—I just hadn’t encountered them yet. When you’re modeling a real-world system, count the levels. Write them down. Then count the levels in your database. Do they match?

Containers and contents are different things, even if they both have names and locations. This seems like common sense now, but when I was building the original schema, I simply didn’t see the issue.

Database Schema Changes Are Easier Early

This refactor touched every database function and most UI components. It was significant work.

If I’d caught this flaw after six months of data entry, migration would have been painful. I’d have needed to write migration scripts, test them against production data, handle edge cases, and pray nothing broke.

Catching it in week one meant a clean restart. I dumped all the data because it was easier than trying to preserve and migrate it. That’s a luxury you only have early in a project.

Keep Your AI Context Updated

I’ve been bouncing ideas off Claude to see what might work and what definitely won’t. It’s been helpful for thinking through problems and catching issues.

But here’s what I didn’t anticipate: my Claude Project configuration had the old three-level schema baked in. After the refactor, I had to update those instructions so the AI understood the new structure and why I changed it.

The configuration is only as good as the context it contains. If your tools are working from outdated assumptions, they’ll give you outdated guidance. This applies to AI assistants, documentation, onboarding materials, and anything that encodes how your system works.

I should have just let Claude help build the schema in the first place. But I was trying to learn as I went, and that’s the tradeoff. I’m not a coder by trade, just a systems engineer who likes to automate as much as possible.

📬 Learning to code while working full-time? You’re not alone. Subscribe to As The Geek Learns for weekly lessons from the trenches—the wins, the fails, and the “I wish someone had told me” moments.

Database Design Checklist for Hierarchical Data Projects

If you’re building something that models a hierarchy, run through this before you write code:

Count the levels in the real-world system. Write them down. Then count the levels in your database schema. Do they match exactly?

Distinguish containers from contents. Are there things that hold other things? Those need separate tables or entities, not just a “type” field.

Define the numbering scheme. If your system has identifiers like XX.XX.XX, your schema needs to support generating and validating that format at each level.

Identify inheritable properties. What attributes should cascade from parent to child? Design for that explicitly (like the sensitivity: inherit option I added).

Plan for schema evolution. Your first model probably won’t be your last. How hard will it be to add a level later? To split a table? Design with migration in mind.

What’s Next for JDex

JDex is better now. The four-level hierarchical database design matches how Johnny Decimal actually works, and I can finally track what’s inside a folder.

The most important bugs aren’t always in your code; they’re in your assumptions. The schema looked right. The code worked. But the underlying model was wrong, and no amount of polish would have fixed that.

One week of real use revealed what months of planning couldn’t.

James is a systems engineer building JDex as a learning project while documenting the journey. Follow along at As The Geek Learns for more lessons from the trenches of learning to code.

Have you discovered a fundamental flaw hiding in your project’s design? How did you find it? Drop your story in the comments. I read every one.

If you’re learning to build software while working a day job, subscribe to As The Geek Learns. I document the wins, the fails, and the “I wish someone had told me this earlier” moments.

Leave a comment

So I decided to build one. But I’m a systems engineer, not a web developer. I can write PowerShell scripts in my sleep, but building a proper web application? Different skill set entirely.

This is where AI-assisted app development got interesting.

From AI Answers to AI Collaboration

I’d been using Claude, Anthropic’s AI assistant, for various work tasks. Technical documentation. Script debugging. Research. But I hadn’t explored what it would be like to build something with AI rather than just getting answers from it.

I started describing what I wanted: a web-based index for managing Johnny Decimal systems across multiple storage locations. Something accessible from any device. Something that would help me track not just where files should go, but where they currently are as I work through the migration.

What followed was genuinely collaborative. Not “AI writes code, human copies and pastes,” but an actual back-and-forth of designing, building, testing, and refining.

I’d describe a feature. Claude would propose an implementation. I’d test it, find edge cases, and explain what wasn’t working. We’d iterate. Sometimes I’d have a half-formed idea, and Claude would help me think through implications before writing any code.

I consider Claude a partner in this process. That’s not hype. It’s the most accurate description of how the work actually happened.

What JDex Does: A Johnny Decimal Index App

JDex is the Johnny Decimal index application that emerged from this collaboration. At its core, it lets you:

Define your structure: Create areas and categories that match how you think about your information.

Track locations: Note where files actually live, including which cloud service, which device, and which folder path.

Manage the index: The heart of Johnny Decimal is the index, a master reference of what exists and where it belongs.

Search and navigate: Find any ID quickly, see what’s in each category, and understand your system at a glance.

The working application matters, but what I learned about building with AI matters more.

4 Lessons from Building an App with Claude AI

1. AI collaboration is a skill

Like working with a human colleague, you get better at it. I learned to describe problems more clearly, break complex features into manageable pieces, and provide useful feedback when something wasn’t quite right. The quality of what Claude produced directly correlated with the quality of context I provided.

2. The human brings the context

Claude doesn’t know my file organization history, my workflow, or my pain points. I had to bring that context to every conversation. The AI could suggest solutions, but only I could evaluate whether they fit my actual life. Domain expertise isn’t replaced—it’s leveraged.

3. It’s genuinely faster

Things that would have taken weeks of learning web development frameworks happened in hours. Not because AI did all the work, but because it accelerated the parts I didn’t know while I focused on the parts I did. For a systems engineer exploring app development, this changes what’s possible.

4. The result feels like mine

This surprised me most. JDex isn’t something Claude built that I’m using. It emerged from hundreds of small decisions I made, issues I identified, and features I prioritized. The AI was a capable partner, but the vision and direction were always mine.

This article is also available in podcast format: The ASTGL Podcast

What's Next for JDex

JDex is functional but not finished. I’m using it daily as I implement my own Johnny Decimal system, and real-world usage keeps surfacing improvements.

I’ll be sharing more here on As The Geek Learns:

• How I structured my Johnny Decimal system (decisions and tradeoffs)

• Technical deep dives on JDex features

• Lessons from migrating years of digital clutter

• Honest assessments of where AI collaboration helps and where it doesn’t

We’re at an interesting moment with AI tools. Underneath the hype, there’s something real: people with ideas and domain expertise can build things that previously required skills they didn’t have.

I’m not a developer. But I had a clear problem, years of experience with organizational systems, and access to an AI that could help translate vision into working code. That’s a new kind of leverage worth exploring seriously.

JDex is my first real experiment in that space. It won’t be my last.

FAQ

What is JDex? JDex is a web-based application for managing Johnny Decimal file organization systems. It lets you define your category structure, track where files are stored across multiple locations, and maintain a searchable index of your entire system.

Do I need coding experience to use JDex? No. JDex is a user-facing application, not a coding tool. You interact with it through a web interface to manage your Johnny Decimal system.

Can I build an app with Claude AI if I’m not a developer? Yes, with cautions. You need enough technical literacy to test, debug, and direct the process. My background as a systems engineer helped. I understood logic and structure even without web development experience. Complete beginners would face a steeper learning curve.

Is JDex available to use? JDex is currently in development. Follow As The Geek Learns for updates on availability.

James is a systems engineer, writer, and builder. He publishes As The Geek Learns at astgl.com and writes about surveillance technology and democratic resistance at Resist and Rise.

Series: Building JDex

• Part 1: The File Organization Problem

• Part 2: How I Built JDex with Claude AI (You are here)

• Part 3: Coming soon

Have you built anything with AI assistance? What was the collaboration actually like? Let me know in the comments.

Leave a comment

Files everywhere. iCloud, Dropbox, OneDrive, ProtonDrive. Two laptops. External drives with names like “Backup_OLD_FINAL_v2.” Folders buried 8 levels deep with names I made up in 2003 and haven’t thought about since.

At work, I help manage around 5,500 virtual desktops running on VMware ESXi. Before that, I spent years on the server side; I’ve probably built and retired over 15,000 virtual servers throughout my career. I can script my way through complex VMware migrations without breaking a sweat. But ask me to find that PDF of my home insurance policy? Yeah. Good luck with that.

If this sounds familiar, keep reading.

The Problem Nobody Talks About

Digital clutter sneaks up on you. It builds quietly, one “I’ll organize this later” at a time. Then suddenly you’re staring at a search bar, trying to remember which of four cloud services might have the document you need.

Productivity gurus love to say, “Just pick a system.” Easy for them. They’re usually not dealing with:

• Work files that absolutely must stay separate from personal stuff

• Sensitive documents that need encrypted storage

• Collaborative projects scattered across different platforms

• Years of accumulated digital life that doesn’t fit neatly anywhere

I tried everything. Color-coded folders. Strict naming conventions. Applied the “inbox zero” mindset to my files. Each approach worked for maybe three weeks. Then chaos won. It always does.

That’s when I stumbled onto Johnny Decimal, on Reddit, of course.

A System That Actually Made Sense

Johnny Decimal is a file organization method created by Johnny Noble. The idea is simple: you get a maximum of 10 areas (your broad categories), and each area can hold a maximum of 10 categories (more specific groupings). Every single file gets a unique ID based on where it belongs.

Instead of wading through /Documents/Work/Projects/2024/Client_ABC/Reports/Final/, you end up with something like 32.14 Client ABC Q3 Report.

The constraints are the whole point. When you limit yourself to 10 areas and 10 categories per area, you actually have to think about how you organize things. Nothing goes deeper than two levels. Every file has a home. You can tell someone “it’s in 32.14” and they know exactly where to look.

I read through Johnny’s documentation, and something just clicked. This wasn’t some organizational B.S. that would fade in six months. It’s a real framework for thinking about how information connects to other information.

But I had a problem.

The Gap Between Theory and My Reality

Johnny Decimal works great when you’re starting fresh with one file system. I was looking at four cloud services, two machines, and years of accumulated chaos that all needed to be cataloged, cross-referenced, and migrated.

I needed more than a methodology. I needed a tool.

Here’s what I was looking for:

• A central index to track where everything lives across all my storage platforms

• A way to assign and manage Johnny Decimal IDs without going crazy

• Something that could grow with me as I slowly brought order to the mess

I searched for existing solutions. Some solid tools exist, but nothing quite fit my multi-platform, sprawling-digital-life situation.

So I built it myself. With an unusual partner helping me along the way.

Next time: What it actually looks like to build an app with AI as your collaborator—the process, the tool I created, and what I learned about this new kind of partnership.

Have you tried Johnny Decimal? Struggled with multi-cloud chaos? I’d love to hear your experiences in the comments.

Until next time—stay curious, keep scripting, and remember: every expert was once a beginner who just refused to quit. I’m James, and this has been As The Geek Learns.

One last thing: if you’re getting value from the show, drop me a rating on Apple Podcasts. Five stars keeps the lights on, but honestly? Even a review that says ‘this guy talks about PowerShell too much’ helps the algorithm. I’ll take it.

Here’s something embarrassing. I’m a systems engineer. Twenty-five years managing enterprise infrastructure. And until recently? My personal file system was a complete mess.

Files everywhere. iCloud, Dropbox, OneDrive, ProtonDrive. Two laptops. External drives with names like “Backup_OLD_FINAL_v2.” Folders buried 8 levels deep with names I made up in 2003 and haven’t thought about since.

At work, I help manage around 5,500 virtual desktops running on VMware ESXi. Before that, I spent years on the server side; I’ve probably built and retired over 15,000 virtual servers throughout my career. I can script my way through complex VMware migrations without breaking a sweat. But ask me to find that PDF of my home insurance policy? Yeah. Good luck with that.

If this sounds familiar, keep reading.

The Problem Nobody Talks About

Digital clutter sneaks up on you. It builds quietly, one “I’ll organize this later” at a time. Then suddenly you’re staring at a search bar, trying to remember which of four cloud services might have the document you need.

Productivity gurus love to say, “Just pick a system.” Easy for them. They’re usually not dealing with:

• Work files that absolutely must stay separate from personal stuff

• Sensitive documents that need encrypted storage

• Collaborative projects scattered across different platforms

• Years of accumulated digital life that doesn’t fit neatly anywhere

I tried everything. Color-coded folders. Strict naming conventions. Applied the “inbox zero” mindset to my files. Each approach worked for maybe three weeks. Then chaos won. It always does.

That’s when I stumbled onto Johnny Decimal, on Reddit, of course.

A System That Actually Made Sense

Johnny Decimal is a file organization methodology created by Johnny Noble. The idea is simple: you get a maximum of 10 areas (your broad categories), and each area can hold a maximum of 10 categories (more specific groupings). Every single file gets a unique ID based on where it belongs.

Instead of wading through /Documents/Work/Projects/2024/Client_ABC/Reports/Final/, you end up with something like 32.14 Client ABC Q3 Report.

The constraints are the whole point. When you limit yourself to 10 areas and 10 categories per area, you actually have to think about how you organize things. Nothing goes deeper than two levels. Every file has a home. You can tell someone “it’s in 32.14” and they know exactly where to look.

I read through Johnny’s documentation, and something just clicked. This wasn’t some organizational B.S. that would fade in six months. It’s a real file organization system for thinking about how information connects to other information.

But I had a problem.

The Gap Between Theory and My Reality

Johnny Decimal works great when you’re starting fresh with one file system. I was looking at four cloud services, two machines, and years of accumulated chaos that all needed to be cataloged, cross-referenced, and migrated.

I needed more than a methodology. I needed a tool.

Here’s what I was looking for:

• A central index to track where everything lives across all my storage platforms

• A way to assign and manage Johnny Decimal IDs without going crazy

• Something that could grow with me as I slowly brought order to the mess

I searched for existing solutions. Some solid tools exist, but nothing quite fit my multi-platform, sprawling-digital-life situation.

So I built it myself. With an unusual partner helping me along the way.

Next time: What it actually looks like to build an app with AI as your collaborator—the process, the tool I created, and what I learned about this new kind of partnership.

Have you tried the Johnny Decimal file system? Struggled with multi-cloud chaos? I’d love to hear your experiences in the comments.

Leave a comment

Twenty-five years of systems engineering. Somewhere around 15,000 virtual machines under my watch (if you count VDI). Countless PowerShell scripts, automation workflows, and middle-of-the-night troubleshooting sessions. I’ve seen technologies come and go, watched VMware evolve from a curiosity to the backbone of enterprise infrastructure, and learned more from my mistakes than I’d care to admit.

So why start writing now?

Because I’m still learning.

That might sound strange. After a quarter century, shouldn’t I have it all figured out? But here’s what I’ve discovered: the moment you think you’ve mastered something is usually the moment before it changes completely. The best engineers I know, the ones who’ve lasted, who’ve stayed sharp, are the ones who never stopped being students.

That’s what this newsletter is about.

What to expect

I’m not here to pretend I have all the answers. Instead, I’ll share:

• What I’m learning — New tools, techniques, and approaches I’m exploring

• What actually works — Practical solutions tested in real production environments, not just lab demos

• What I’ve built — Apps and automation I’ve created to solve my own problems (and might solve yours too)

• What I got wrong — Because occasionally the best lessons come from failures

If you work in IT, especially if you’re managing VMware infrastructure or trying to level up your PowerCLI skills, I think you’ll find something useful here.

A bit about me

I’m a systems engineer at a large healthcare organization in Florida, where I manage enterprise VMware infrastructure. I’ve spent years automating repetitive tasks, building tools to make my life easier, and figuring out how to do more with less (sound familiar?).

Outside the day job, I’m working on training courses for IT professionals who want to master PowerCLI and VMware automation. I’ve also built a few apps, including KlockThingy—a time-tracking tool that came out of my wife’s frustration with what she calls ‘Clocky Math.’ It was vital that she log her hours more efficiently as a remote contract worker. She also coined the name.

Why “As The Geek Learns”?

The name says it all. I’m a geek. I learn things. I write about what I learn.

There’s a Yoda quote I’ve always loved: “Much to learn, you still have.” I have adapted that quote to reflect my lifelong learning experience.

“Much to learn, there always is”

It’s a reminder that expertise isn’t a destination; it’s a direction. No matter how long you’ve been at this, there’s always something new to discover.

I hope you’ll come along for the ride.

What’s next

In upcoming posts, I’ll be sharing:

• A deep dive into the PowerCLI automation techniques I use daily

• Behind the scenes of building and shipping my first app

• Practical tips for managing large-scale VMware environments

• And whatever else I’m learning along the way

If any of that sounds interesting, you’re in the right place.

Thanks for being here.

Always a student. Sometimes a teacher.

— James

I’ve been doing this for a while.

Twenty-five years of systems engineering. Somewhere around 15,000 virtual machines under my watch (if you count VDI). Countless PowerShell scripts, automation workflows, and middle-of-the-night troubleshooting sessions. I’ve seen technologies come and go, watched VMware evolve from a curiosity to the backbone of enterprise infrastructure, and learned more from my mistakes than I’d care to admit.

So why start writing now?

Because I’m still learning.

That might sound strange. After a quarter century, shouldn’t I have it all figured out? But here’s what I’ve discovered: the moment you think you’ve mastered something is usually the moment before it changes completely. The best engineers I know, the ones who’ve lasted, who’ve stayed sharp, are the ones who never stopped being students.

That’s what this newsletter is about.

What to expect

I’m not here to pretend I have all the answers. Instead, I’ll share:

• What I’m learning — New tools, techniques, and approaches I’m exploring

• What actually works — Practical solutions tested in real production environments, not just lab demos

• What I’ve built — Apps and automation I’ve created to solve my own problems (and might solve yours too)

• What I got wrong — Because occasionally the best lessons come from failures

If you work in IT, especially if you’re managing VMware infrastructure or trying to level up your PowerCLI skills, I think you’ll find something useful here.

A bit about me

I’m a systems engineer at a large healthcare organization in Florida, where I manage enterprise VMware infrastructure. I’ve spent years automating repetitive tasks, building tools to make my life easier, and figuring out how to do more with less (sound familiar?).

Outside the day job, I’m working on training courses for IT professionals who want to master PowerCLI and VMware automation. I’ve also built a few apps, including KlockThingy—a time-tracking tool that came out of my wife’s frustration with what she calls ‘Clocky Math.’ It was vital that she log her hours more efficiently as a remote contract worker. She also coined the name.

Why “As The Geek Learns”?

The name says it all. I’m a geek. I learn things. I write about what I learn.

There’s a Yoda quote I’ve always loved: “Much to learn, you still have.” I have adapted that quote to reflect my lifelong learning experience.

“Much to learn, there always is”

It’s a reminder that expertise isn’t a destination; it’s a direction. No matter how long you’ve been at this, there’s always something new to discover.

I hope you’ll come along for the ride.

What’s next

In upcoming posts, I’ll be sharing:

• A deep dive into the PowerCLI automation techniques I use daily

• Behind the scenes of building and shipping my first app

• Practical tips for managing large-scale VMware environments

• And whatever else I’m learning along the way

If any of that sounds interesting, you’re in the right place.

Thanks for being here.

Always a student. Sometimes a teacher.

— James