DEV Community: Alex LaGuardia

Three freelancer tools died in two months. I built the replacement.

Alex LaGuardia — Sat, 04 Apr 2026 10:18:46 +0000

HoneyBook hiked prices 89%. AND.CO shut down entirely. Bonsai got acquired by Zoom with no roadmap. All within two months of each other.

I'm a freelancer who was paying $29/mo for HoneyBook. I used two features: proposals and invoice reminders. That's it. Two features out of fifty. The other forty-eight were bloat I paid for and never touched.

Dubsado is so complex that a cottage industry of "setup specialists" charge $500-3,500 just to configure it. That tells you everything about how broken this market is.

So I built Stampwerk. Proposals, contracts, invoices, and follow-ups. $12/mo. No setup wizard. No onboarding call. No fifty features you'll never open.

What the AI actually does

This isn't "AI-powered" as a marketing checkbox. The AI does two specific things that freelancers hate doing manually.

1. Proposal generation. Answer 5 questions about a project and the LLM writes a full proposal -- scope, timeline, pricing breakdown, and payment terms.

# 5 inputs in, structured proposal out
response = groq_client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=[
        {"role": "system", "content": PROPOSAL_SYSTEM},
        {"role": "user", "content": json.dumps({
            "client": client_name,
            "description": project_desc,
            "budget_range": budget,
            "timeline": timeline,
            "deliverables": deliverables
        })}
    ],
    response_format={"type": "json_object"}
)

Not template-fill. The model reasons about scope and pricing based on the project description. You edit what it generates, not what a template assumes.

2. Invoice follow-ups. A background daemon runs hourly and chases overdue invoices on a 3-step escalation:

Day 3 -- friendly check-in
Day 7 -- professional reminder with payment link
Day 14 -- firm final notice

Each message matches the escalation stage. This is the part of freelancing that everyone hates and nobody does consistently. Now it runs while you sleep.

The full pipeline

The thesis behind Stampwerk is that these aren't separate features. They're one flow:

Client signs up (Google or magic link, 30 seconds)
Creates a project, answers 5 questions
AI generates the proposal
Client views it at a public link, accepts with one click
Contract auto-generates from the accepted proposal terms
Client e-signs
Milestones trigger invoices with Stripe payment links
Overdue invoices get automatic follow-ups

One pipeline. Every step feeds the next. No configuration, no "setup specialist" needed.

HoneyBook has all these features too. They also have fifty others, a $29-59/mo price tag, and an 89% price hike that tells you where they think the market is headed.

Why these tech choices

Layer	Choice	Why
Backend	FastAPI	42 routes, async, typed
Database	SQLite	One file, WAL mode, zero ops burden
AI	Groq + Llama 3.3 70B	Free inference, structured JSON output
Payments	Stripe	Payment links for clients, subscriptions for us
Email	Resend	Transactional email under 3K sends is free
Frontend	Next.js 14 + Tailwind	SSR, file routing, fast iteration

Total infrastructure cost: $0/mo. AI calls are free through Groq. Email is free at this scale. Stripe only charges when money moves. The whole thing runs on a single server I already had.

This matters because the competitors raised hundreds of millions. HoneyBook took $479M in funding. Dubsado bootstrapped to $2.5M ARR. Moxie raised ~$10M. When you compete against that, your margin has to be your moat. A $0 cost base means $12/mo is sustainable, not a loss leader.

Honest trade-offs

The retro arcade UI is polarizing. Some people think it's unprofessional for a business tool. I'm keeping it. If your target is corporate project managers, sure. If your target is solo freelancers who are tired of software that looks like every other SaaS dashboard, it works.

No PDF export yet. No time tracking. No QuickBooks integration. No mobile app. These are real gaps. But I'd rather ship the core pipeline right and add features from real user feedback than build fifty features nobody asked for.

That's how we got HoneyBook in the first place.

Try it

stampwerk.com -- free tier gives you 5 clients, 5 projects, and full AI proposals. Pro is $12/mo for unlimited.

Built with FastAPI, Next.js 14, SQLite, Groq, Stripe, and Resend. Questions about the stack or the business model welcome.

I Built a Security Scanner That Uses AI to Review Its Own Findings

Alex LaGuardia — Tue, 31 Mar 2026 09:53:59 +0000

Every AI coding tool ships code fast. None of them check if it's safe.

I built Critik — an open-source security scanner that catches what your AI writes and your review misses. Regex and AST find the candidates. An LLM reviews each one with full file context, confirms the real problems, kills the false positives, and explains why in plain English.

pip install critik and you're scanning in 30 seconds.

The Numbers Are Ugly

53% of teams that shipped AI-generated code later found security issues that passed review. Georgia Tech's Vibe Security Radar tracked 74 CVEs from AI coding tools in Q1 2026 alone — 6 in January, 15 in February, 35 in March. Accelerating.

Here's what I keep finding when I scan AI-built projects:

Hardcoded API keys — Cursor generates a Supabase client and pastes the service_role key right in the file
SQL injection via f-strings — Copilot autocompletes db.execute(f"SELECT * FROM users WHERE id = {user_id}") without blinking
Firebase rules wide open — Bolt scaffolds read: true, write: true and nobody touches it
NEXT_PUBLIC_ prefix on secrets — the env var that hands your database URL to every browser

Not edge cases. Default patterns.

The Tools That Exist Don't Fix This

Snyk charges $25-98/dev/mo. Built for enterprises with procurement budgets.

Semgrep is powerful. Also requires writing custom rules in a DSL. Steep curve. Recently relicensed behind commercial terms.

npm audit is, in Dan Abramov's words, "broken by design" — flags devDependency issues that can't touch production.

Bandit and ESLint security plugins catch patterns but have zero context. They flag eval() in a test fixture the same way they flag eval(user_input) in a request handler.

That last one is the real problem. Static scanners are noisy. Developers learn to ignore them. Which means they ignore the real findings too.

Two Passes. One Scanner.

Pass 1 — Static (fast, offline, free)

Regex patterns and Python AST parsing. Hardcoded secrets (16 patterns — AWS, Stripe, OpenAI, Anthropic), SQL injection, command injection, eval/exec, XSS, framework misconfigs. Runs in milliseconds. No API key needed.

Pass 2 — AI Review (optional, the whole point)

Add --ai and each finding goes to Groq's Llama 3.3 70B with the full file as context. The model acts as a security analyst:

Verdict: confirmed, false_positive, or needs_review
Confidence: 0-100%
Why: "This eval() parses trusted JSON config from a local file" vs "This eval() takes unsanitized user input from req.query"
Fix: actual code, not generic advice

The AI doesn't replace the scanner. It reviews the scanner's work.

What It Looks Like

$ critik scan . --ai

  Critik v0.4.0 — scanned 7 files  [AI]

  CRITICAL  nextjs-public-secret
  app/config.ts:18  Secret exposed to browser via NEXT_PUBLIC_ prefix
  | 18 | const key = process.env.NEXT_PUBLIC_SECRET_API_KEY
  CONFIRMED (95%)
  > The NEXT_PUBLIC_ prefix exposes this API key to every browser.
  Fix: Rename to SECRET_API_KEY and access server-side only

  CRITICAL  aws-access-key              (dimmed — false positive)
  tests/fixtures/bad_secrets.py:2  AWS access key detected
  FALSE POS (100%)
  > This file is in tests/fixtures — fake credentials for testing.

  HIGH      sql-fstring
  app/db.py:6  SQL injection via f-string in execute()
  | 6 | db.execute(f"SELECT * FROM users WHERE id = {user_id}")
  CONFIRMED (95%)
  > This f-string takes unsanitized input, allowing SQL injection.
  Fix: db.execute('SELECT * FROM users WHERE id = ?', (user_id,))

  ─────────────────────────────────────────────
  7 files scanned in 2714ms — 23 findings: 10 critical, 8 high, 5 medium
  AI analysis: 7 confirmed, 16 false positives

Without AI: 23 findings. Developer overwhelmed. Ignores all of them.

With AI: 7 real issues. 16 dismissed with reasons. Developer fixes what matters.

Under the Hood

Each API call sends the full file content (up to 8K chars) plus all findings for that file. One call per file — keeps tokens low, context high.

The model sees imports, function signatures, data flow. It knows test fixtures are probably safe, .env files are expected to have secrets, and NEXT_PUBLIC_ vars are intentionally client-exposed.

Temperature 0.2. Structured JSON back. If the API is down, Critik falls back to regex-only. No crash, no hang.

What It Catches

Category	Patterns	Examples
Secrets	16	AWS, GitHub, OpenAI, Anthropic, Stripe, Slack, DB URLs, JWTs, private keys
Injection	6	SQL via f-string/concat, eval(), exec(), os.system(), subprocess shell=True, XSS
Frameworks	8	Supabase RLS, Firebase rules, NEXT_PUBLIC_ secrets, NextAuth, Prisma raw, Stripe webhooks
Config	6	NODE_ENV in source, insecure cookies, open CORS, debug mode
Auth	2	Missing auth on routes, open endpoints
Dotenv	3	Exposed .env, sensitive vars unencrypted

Free. All of It.

pip install critik
critik scan .                # regex/AST only — offline, instant
critik scan . --ai           # + AI review (needs GROQ_API_KEY)
critik scan . --format fix   # copy-paste fix prompts for Cursor/Claude

Pre-commit hook: critik hook install. SARIF output for CI/CD. GitHub Action included. MIT license.

Why I Built This

I hunt bugs on HackerOne and 0din. The vulnerabilities I find in production are the same patterns AI tools ship by default. Hardcoded keys. Missing auth. SQL injection. Open configs.

The irony: AI coding tools are the biggest source of new vulnerabilities and the best tool for catching them. A regex finds eval(). Only an LLM can tell you if it's dangerous.

Critik is the scanner I wanted. Now it exists.

Website: critik.dev
GitHub: AlexlaGuardia/Critik
PyPI: pip install critik

Run critik scan . on your project. You might not like what you find.

OAuth2, Two APIs, and Soft Deletes — Building an MCP Server for FreshBooks

Alex LaGuardia — Thu, 26 Mar 2026 22:33:14 +0000

Most MCP servers assume your target API hands you an API key and gets out of the way. FreshBooks doesn't. It requires full OAuth2, splits its API across two different base URLs, and has resources that can only be soft-deleted. Building this server meant solving problems most MCP tutorials don't prepare you for.

The result: 25 tools covering invoices, clients, expenses, payments, time tracking, projects, estimates, and reports — with the auth flow, API quirks, and deletion edge cases handled for you.

What It Does

MCP lets AI assistants interact with external tools directly. With this server installed, you manage your entire freelance business without leaving your AI assistant.

Before (manual):

Log into FreshBooks
Navigate to Invoices → find overdue ones
Note the client names and amounts
Switch to your AI tool
Type out all the details
Ask what to do about it

After (with mcp-freshbooks):

"Which invoices are overdue? Draft follow-up messages for each client based on how late they are."

Claude calls list_invoices with a status filter, gets the details, and drafts personalized follow-ups — all in one shot.

25 Tools, Full Business Coverage

Invoices (6): List, get, create, update, delete, send by email
Clients (4): List, get, create, archive with full contact details
Expenses (3): List, get, create with category and tax support
Payments (2): List, record payments against invoices
Time Entries (2): List, create with project/service association
Projects (2): List, get with budget and billing details
Estimates (2): List, get with line items
Reports (1): Profit & Loss report with date filtering
Auth (3): OAuth2 flow, identity check, connection test

Technical Decisions Worth Sharing

Full OAuth2 — No Shortcuts

FreshBooks requires OAuth2. No API keys, no shortcuts. The server handles the entire flow: it spins up a local HTTPS callback server, opens the authorization URL, catches the redirect with the auth code, exchanges it for tokens, and persists them to ~/.mcp-freshbooks/tokens.json. Token refresh is automatic — you authenticate once and forget about it.

@mcp.tool()
def freshbooks_authenticate() -> str:
    """Start OAuth2 authentication. Returns a URL to open in your browser."""
    config = get_config()
    url = get_auth_url(config)
    # Spins up localhost:8555 HTTPS callback server in background
    start_callback_server(config)
    return f"Open this URL to authorize:\n{url}"

This was the hardest part of the build. Most MCP servers assume API keys. When your platform demands OAuth2, you either solve it properly or your server is useless.

Two APIs, Two Base URLs

FreshBooks has a split API: accounting resources (invoices, clients, expenses) live at api.freshbooks.com/accounting/account/{account_id}/..., while project resources (projects, time entries) live at api.freshbooks.com/projects/business/{business_id}/.... Different base URLs, different ID types.

The client abstracts this completely:

ACCOUNTING_BASE = "https://api.freshbooks.com/accounting/account"
PROJECTS_BASE = "https://api.freshbooks.com/projects/business"

async def accounting_list(resource, ...):
    account_id, _ = await get_ids()
    url = f"{ACCOUNTING_BASE}/{account_id}/{resource}"
    ...

async def projects_list(resource, ...):
    _, business_id = await get_ids()
    url = f"{PROJECTS_BASE}/{business_id}/{resource}"
    ...

The tools never think about which API base to use — they just call the right function.

Soft Deletes vs Hard Deletes

FreshBooks treats deletion differently depending on the resource. Invoices and estimates can be hard-deleted (actually removed). Clients and expenses can only be soft-deleted by setting vis_state to 1 (archived). Delete a client with the wrong endpoint and you get a cryptic 400 error.

async def accounting_delete(resource, resource_id):
    """Hard-delete (invoices, estimates)."""
    ...

async def accounting_soft_delete(resource, resource_id, wrapper_key):
    """Soft-delete via vis_state=1 (clients, expenses)."""
    return await accounting_update(resource, resource_id, wrapper_key, {"vis_state": 1})

Each tool uses the correct method — the AI never needs to know about this distinction.

The search[key] Query Format

FreshBooks uses a non-standard query parameter format for filters: search[status]=2&search[date_from]=2024-01-01. Not status=2, not filter[status]=2 — specifically search[key]. Get the format wrong and the API silently ignores your filters.

def _build_search_params(filters):
    params = {}
    for key, value in filters.items():
        if isinstance(value, list):
            for v in value:
                params.setdefault(f"search[{key}][]", []).append(str(v))
        else:
            params[f"search[{key}]"] = str(value)
    return params

The tools accept clean Python dicts and handle the formatting internally.

Get Started in 2 Minutes

Install

pip install mcp-freshbooks

Create OAuth App

Go to my.freshbooks.com/#/developer, create an app, and note the client ID and secret. Set the redirect URI to https://localhost:8555/callback.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "freshbooks": {
      "command": "mcp-freshbooks",
      "env": {
        "FRESHBOOKS_CLIENT_ID": "your-client-id",
        "FRESHBOOKS_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Then ask Claude to run freshbooks_authenticate — it will give you a URL to authorize. One-time setup, tokens auto-refresh after that.

Claude Code

claude mcp add freshbooks -- env FRESHBOOKS_CLIENT_ID=id FRESHBOOKS_CLIENT_SECRET=secret mcp-freshbooks

Cursor

Same JSON config as Claude Desktop in .cursor/mcp.json.

What I'd Do Differently

Add invoice line item support from day one. The current create_invoice accepts line items as a JSON string, which works but isn't the cleanest interface. A dedicated line-item builder would be more ergonomic for the AI.

Handle plan-gated features more gracefully. FreshBooks gates features by plan tier — time tracking, projects, and advanced reports require paid plans. The error handling catches 403s and explains this, but detecting plan limits upfront would be smoother.

Lessons for MCP Server Builders

Solve OAuth2 properly. If your target platform requires it, don't punt — build the full flow with token persistence and auto-refresh. It's the difference between a demo and a tool people actually use.
Abstract API inconsistencies. If the platform has split APIs, different deletion behaviors, or non-standard query formats — hide all of it. The AI should never deal with platform quirks.
Handle plan-tier errors. SaaS platforms gate features by pricing tier. Catch permission errors and explain what's happening instead of returning raw 403s.
Persist tokens securely. Store tokens in a well-known location (~/.mcp-freshbooks/) with clear documentation. Users shouldn't have to re-authenticate every session.

Links

GitHub: AlexlaGuardia/mcp-freshbooks
PyPI: mcp-freshbooks
License: MIT

This is part of a series of production-grade MCP servers I'm building for underserved SaaS platforms. Also available: Mailchimp, WooCommerce, ActiveCampaign. Follow me here or on GitHub to catch the next one.

Update (April 2026): Since publishing, mcp-freshbooks has been expanded from 25 to 53 tools (v0.2.0). New coverage includes recurring invoices, 5 typed reports (P&L, tax, accounts aging, revenue, expense), and workflow tools like invoice-from-time and estimate-to-invoice conversion. pip install mcp-freshbooks to get the latest.

Zero to 33 Tools: Building the First MCP Server for ActiveCampaign

Alex LaGuardia — Thu, 26 Mar 2026 22:32:11 +0000

I searched GitHub, npm, PyPI, and every MCP registry I could find for an ActiveCampaign MCP server. Zero results. Not a bad one, not an incomplete one — nothing. For a platform with 185,000 paying customers and a full-featured API, that gap felt worth filling.

So I built it from scratch: 33 tools covering contacts, deals, automations, tags, pipelines, campaigns, custom fields, and webhooks.

What It Does

MCP lets AI assistants interact with external tools directly. With this server installed, you manage your CRM and marketing automation without leaving your AI assistant.

Before (manual):

Log into ActiveCampaign
Navigate to Contacts → search for a customer
Check their tags, deals, automation history
Switch to your AI tool
Describe what you found
Ask for analysis

After (with mcp-activecampaign):

"Find all contacts tagged 'enterprise-lead' and show me their deal pipeline status. Which ones haven't been contacted in 30 days?"

Claude calls list_contacts with a tag filter, then list_deals for each, and gives you an actionable priority list — all in one shot.

33 Tools, Full CRM Coverage

Contacts (7): List, get, create, update, delete, search, manage tags
Deals (5): List, get, create, update, delete with pipeline/stage support
Tags (4): List, create, add to contact, remove from contact
Lists (2): List all, get details with subscriber counts
Automations (3): List, get details, add contacts to automations
Pipelines (2): List pipelines, list stages within pipelines
Custom Fields (3): List fields, get values, set values per contact
Campaigns (2): List campaigns with stats, get full campaign details
Accounts (2): List and get company/organization records
Webhooks (3): List, create, delete for real-time event handling

Technical Decisions Worth Sharing

Client-Side Rate Limiting

ActiveCampaign enforces 5 requests per second per account. Hit the limit and you get 429s that can cascade. Instead of reacting to failures, the client prevents them:

MAX_RPS = 5
MIN_INTERVAL = 1.0 / MAX_RPS  # 0.2s between requests

async def _throttle(self) -> None:
    """Enforce 5 req/s rate limit."""
    async with self._lock:
        now = time.monotonic()
        elapsed = now - self._last_request
        if elapsed < self.MIN_INTERVAL:
            await asyncio.sleep(self.MIN_INTERVAL - elapsed)
        self._last_request = time.monotonic()

An asyncio lock ensures thread safety, and time.monotonic() avoids clock-drift edge cases. If a 429 still slips through (burst from another client), there's a fallback that respects the Retry-After header:

if resp.status_code == 429:
    retry_after = float(resp.headers.get("Retry-After", "1"))
    await asyncio.sleep(retry_after)
    return await self._request(method, path, **kwargs)

Belt and suspenders. The AI never sees rate limit errors.

The "Deal Groups" Translation

ActiveCampaign calls pipelines "deal groups" internally. The API endpoint is /dealGroups, stages are filtered by d_groupid, and creating a deal requires a group field — not pipeline. This naming inconsistency trips up every integration:

@mcp.tool()
async def list_pipelines(limit: int = 20, offset: int = 0) -> str:
    """List deal pipelines (called 'deal groups' in AC API)."""
    data = await ac.get("/dealGroups", ...)
    for p in data.get("dealGroups", []):
        pipelines.append({
            "id": p["id"],
            "title": p.get("title", ""),
            ...
        })

The tools use the word "pipeline" (what users expect) while the client sends "dealGroup" (what the API expects). The AI works with natural language; the translation happens silently.

URL Normalization with API Path

ActiveCampaign API URLs look like https://youraccountname.api-us1.com/api/3/contacts. Users might pass just the account URL, or include the /api/3 suffix. The client normalizes both:

base_url = base_url.rstrip("/")
if not base_url.endswith("/api/3"):
    base_url = f"{base_url}/api/3"

Small thing, but it eliminates a common setup failure.

Read-Only Automations (And Being Honest About It)

ActiveCampaign's API doesn't support creating automations programmatically — you can only list them, view details, and add contacts to existing ones. The tool docstrings say this explicitly:

@mcp.tool()
async def list_automations(...) -> str:
    """List automations (read-only — AC API doesn't support creating automations)."""

When the AI knows the boundary, it can suggest alternatives ("Create the automation in the AC dashboard, then I can add contacts to it") instead of failing mysteriously.

Get Started in 2 Minutes

Install

pip install mcp-activecampaign

Get Your API Credentials

ActiveCampaign → Settings → Developer. You need:

API URL: https://youraccountname.api-us1.com
API Key: The key shown on that page

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "activecampaign": {
      "command": "mcp-activecampaign",
      "env": {
        "ACTIVECAMPAIGN_URL": "https://youraccountname.api-us1.com",
        "ACTIVECAMPAIGN_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add activecampaign -- env ACTIVECAMPAIGN_URL=https://youraccountname.api-us1.com ACTIVECAMPAIGN_API_KEY=key mcp-activecampaign

Cursor

Same JSON config as Claude Desktop in .cursor/mcp.json.

What I'd Do Differently

Add deal note support. ActiveCampaign deals have a notes system that's heavily used by sales teams. I covered the core CRUD but skipped notes — they're high-value for AI-assisted sales workflows.

Build contact-to-deal linking tools. The current create_deal accepts a contact_id, but there's no tool to view or manage the contact-deal association after creation. That relationship is central to how AC users think about their CRM.

Lessons for MCP Server Builders

Rate limit proactively, not reactively. Client-side throttling is always better than hitting limits and retrying. Use asyncio.Lock + time.monotonic() for a clean implementation.
Translate internal naming to user naming. If the API calls something "dealGroups" but users call it "pipelines," use the user's word in your tools. The translation is invisible and the ergonomics improve dramatically.
Document API limitations in docstrings. If the platform doesn't support creating a resource via API, say so in the tool description. The AI uses docstrings to decide what to suggest.
Be the first mover. When you search for "[Platform] MCP server" and find zero results, that's a signal. 185K customers and nobody built this? Ship it.

Links

GitHub: AlexlaGuardia/mcp-activecampaign
PyPI: mcp-activecampaign
License: MIT

This is part of a series of production-grade MCP servers I'm building for underserved SaaS platforms. Also available: Mailchimp, WooCommerce, FreshBooks. Follow me here or on GitHub to catch the next one.

Update (April 2026): Since publishing, mcp-activecampaign has been expanded from 33 to 65 tools (v0.2.0). New coverage includes lead scoring, saved segments, campaign create/send, forms, goals, deal custom fields, CRM notes and tasks, event tracking, ecommerce, and bulk import. pip install mcp-activecampaign to get the latest.

How I Built a Full Product in One Night with 3 Parallel AI Agents

Alex LaGuardia — Wed, 25 Mar 2026 22:12:15 +0000

Last Thursday night I sat down to add session handoff to my Python library. I stood up 8 hours later with a complete product: MCP server, REST API, embedded dashboard, event triggers, signal compaction. From 1,200 lines to 5,900. From a CLI tool to something with a web UI.

Here's how, and why the technique matters more than the project.

The Setup

I'd built Vigil — an awareness daemon for AI agents. It worked great as a CLI tool: emit signals, compile state, boot agents with context. But it was missing the features that make it a real product: session handoff, an MCP server for Claude/Cursor integration, a REST API, and a dashboard.

Each of these features lives in its own module. They share the database layer but have no code dependencies on each other. That's the key insight.

The Technique: Parallel AI Windows

I opened three Claude Code terminal windows, each working on a separate file:

Window 1: Session handoff protocol (handoff.py)
Window 2: Signal compaction engine (compaction.py)
Window 3: MCP server mode (mcp_server.py)

Each window had the same context: the existing codebase, the database schema, the module interfaces. But they worked independently, writing to separate files. No merge conflicts.

While those three were building, I reviewed their output periodically and planned the next batch. When all three finished, I opened a single integration window that wired everything together: imports, CLI commands, shared database migrations.

Then I repeated the pattern:

Window 1: REST API (api.py)
Window 2: Dashboard templates (5 HTML pages)
Window 3: Event triggers (triggers.py)

Same idea. Independent files, parallel execution, single integration pass.

What Made It Work

1. Clean module boundaries. Every feature was a new file that imported from existing modules (db.py, signals.py, awareness.py). No feature needed to modify another feature's code. This isn't accidental — I designed the architecture knowing I'd build this way.

2. Stable interfaces. The database schema and the VigilDB API were stable. All three windows could from vigil.db import VigilDB and trust that the interface wouldn't change under them.

3. Integration is the bottleneck, not implementation. Each module took 30-60 minutes to build. Integration — wiring CLI commands, updating __init__.py, running the test suite — took 20 minutes per batch. The integration step is where I caught type mismatches, missing imports, and interface disagreements.

4. Mid-session code audit. After the first batch (handoff + compaction + MCP), I ran a full code audit before starting batch two. Found 3 critical issues and 6 important ones. Fixing them before building the REST API prevented those bugs from propagating.

The Numbers

Metric	Before (v0.1)	After (v1.0)	Delta
Lines of code	1,278	5,922	+4,644
Modules	7	13	+6
Tests	48	196	+148
CLI commands	7	14	+7

14 commits over 8 hours. Zero merge conflicts.

What I'd Do Differently

Start with the integration test, not the unit tests. Each window wrote unit tests for its module. But the integration tests — "emit a signal, compile awareness, check the dashboard shows it" — came last. If I'd written those first, I'd have caught interface mismatches earlier.

Define the REST API schema before building the dashboard. Window 2 (dashboard) had to guess what the API response shapes would be, because Window 1 (API) was still being built. A shared types file or API schema would have eliminated that friction.

Why This Matters Beyond My Project

The parallel AI window technique works for any codebase with clean module boundaries:

Microservices: Each window builds a different service
Frontend components: Each window builds a different page/component
Data pipelines: Each window builds a different stage

The constraint is the same: modules must be independently buildable with stable interfaces between them. If feature B needs to call feature A's code and that code doesn't exist yet, you can't parallelize them.

This is also a strong argument for writing clean interfaces first. The 30 minutes I spent designing VigilDB's API saved hours of integration pain later.

The Product

Vigil v1.5.0 is on PyPI. It gives AI agents persistent awareness across sessions:

Awareness daemon compiles system state every 90 seconds
Frame-based tool filtering reduces context by 75-85%
Signal protocol lets agents coordinate without direct communication
Session handoff with structured summaries and resume
MCP server with 12 tools (Claude Code, Cursor, Claude Desktop)
REST API with 20 endpoints and SSE event stream
Dashboard with live updates

pip install vigil-agent
vigil init
vigil daemon start

GitHub: github.com/AlexlaGuardia/Vigil

If you're building with AI coding assistants and want to move faster, try the parallel window technique on your next feature batch. The key is architecture that supports it — clean boundaries, stable interfaces, independent files.

I Built a Nervous System for AI Agents (Not Another Memory Store)

Alex LaGuardia — Wed, 25 Mar 2026 22:09:18 +0000

The Problem Nobody Talks About

Everyone's building AI agents. Nobody's building the infrastructure to keep them aware.

I've been running ~95 MCP tools across multiple AI agents for the past year — a coding assistant, a trading system, a creative writing setup. Three problems kept hitting me:

1. Cold starts. Every new session starts from zero. The agent has no idea what happened 5 minutes ago in a different session.

2. Token bloat. Loading 95 tool definitions into context burns ~50,000 tokens before the agent does a single useful thing. That's real money and real context window wasted on tools the agent won't use.

3. No coordination. Multiple agents working on the same system can't hand off work or share awareness without me copy-pasting context between them.

The existing tools (Mem0, Letta, LangGraph) solve pieces of this. Mem0 does memory retrieval. Letta does stateful agents. LangGraph does workflow state. But none of them give agents awareness — a continuously-compiled understanding of what's happening right now.

What If Agents Had a Nervous System?

Memory stores are filing cabinets. You put stuff in, you pull stuff out. That's useful, but it's not how awareness works.

Your nervous system doesn't wait for you to query it. It continuously processes signals from your environment and compiles them into a state that's instantly available. You don't boot up every morning and run SELECT * FROM memories WHERE relevant = true. You just... know what's going on.

That's what I built.

Vigil: The Six Ideas

1. The Awareness Daemon

A background process runs every 90 seconds, reading signals from agents and compiling them into "hot context" — a structured snapshot any agent can boot from instantly.

from vigil import VigilDaemon

daemon = VigilDaemon(
    db_path="vigil.db",
    compile_interval=90,
    awareness_file="AWARENESS.md",
)
daemon.start()

When an agent starts a session, it calls compiler.boot() and gets full context in under a second: active frame, current work, recent signals, priority queue. No startup latency.

The daemon also writes an AWARENESS.md file — human-readable, version-controllable. My agents and I read the same file.

2. Frame-Based Tool Filtering

This was the biggest win. Instead of loading all tools into every context, you tag tools with "frames" — named context modes.

from vigil.registry import tool, tool_count

@tool(name="deploy", description="Deploy to production",
      frames=["backend", "devops"])
async def deploy(args):
    ...

@tool(name="write_chapter", description="Write a story chapter",
      frames=["creative"])
async def write_chapter(args):
    ...

@tool(name="health", description="Health check",
      frames=["core"])  # Always visible
async def health(args):
    ...

tool_count()              # 3 (all tools)
tool_count("backend")     # 2 (deploy + health)
tool_count("creative")    # 2 (write_chapter + health)

An agent in "backend" mode never sees creative writing tools. In my setup, this took tool definitions from 95 down to 14-25 per session — a 75-85% reduction in tool-definition tokens. The LLM also makes better tool choices with fewer irrelevant options.

3. Signal Protocol

Agents communicate through signals — short, categorized messages with content budgets:

Type	Budget	Purpose
observation	400 chars	Regular activity updates
handoff	600 chars	Session conclusions
summary	800 chars	Comprehensive summaries
alert	300 chars	Urgent notifications

from vigil import SignalBus, VigilDB

db = VigilDB("vigil.db")
bus = SignalBus(db)

bus.emit("backend-agent", "Deployed auth service v2. Tests passing.")
bus.emit("frontend-agent", "Dashboard layout refactored for mobile.")

Content budgets prevent runaway data. The daemon reads these signals, synthesizes them into the awareness summary, and moves on. Agents don't talk to each other — they emit into the bus and the daemon handles the rest.

4. Session Handoff

This is what makes multi-session work actually work. Agents end sessions with structured summaries:

from vigil import HandoffProtocol

proto = HandoffProtocol(db)

proto.end_session(
    agent_id="backend-agent",
    summary="Shipped auth v2 with JWT tokens",
    files_touched=["auth.py", "middleware.py"],
    decisions=["Switched from session cookies to JWT"],
    next_steps=["Add rate limiting", "Write integration tests"],
)

# Next morning, different agent resumes
context = proto.resume("morning-agent")
# Includes: last handoff, signals since, pending next steps

Handoff chains track continuity across sessions. The resume context tells the next agent exactly what happened, what decisions were made, and what to do next. No more "remind me what we were working on."

5. Signal Compaction

Signals accumulate. Without compaction, your awareness context grows forever. Vigil uses tiered retention:

Raw signals — kept for 7 days
Daily summaries — synthesized from raw, kept for 30 days
Weekly digests — synthesized from daily, kept for 90 days
Monthly snapshots — permanent archive

vigil compact --dry-run  # Preview what would be compacted
vigil compact            # Run it

History stays manageable without losing important context.

6. Event Triggers

Pattern-match on signals and fire actions automatically:

from vigil import TriggerManager

triggers = TriggerManager(db)

triggers.create(
    name="alert-to-slack",
    signal_type="alert",
    agent_pattern="*",
    action_type="webhook",
    action_config={"url": "https://hooks.slack.com/..."},
)

"If any agent emits an alert, post to Slack." "If the backend agent goes silent for 2 hours, create a focus item." Triggers turn Vigil from a passive awareness layer into an active coordination system.

MCP Server: The Distribution Play

Everything above is available as an MCP server:

vigil serve                          # stdio (Claude Code, Claude Desktop)
vigil serve --transport sse          # SSE (remote clients)
vigil serve --transport http         # REST API + dashboard

12 MCP tools: boot, compile, signal, status, signals, handoff, resume, chain, stale, focus, frames, agents.

Any MCP-compatible client (Claude Code, Cursor, Windsurf, Claude Desktop) connects and gets persistent awareness. The agent boots with context, emits signals during work, and hands off when done. Next session picks up where it left off.

The Numbers

Metric	Value
Modules	14
Lines of code	7,100+
Tests	252
MCP tools	12
REST endpoints	20
Dashboard pages	5
Dependencies	0 (stdlib only, MCP is optional)
Infrastructure	SQLite (zero setup)

Why Not [Existing Tool]?

	Vigil	Mem0	Letta	LangGraph
Approach	Awareness daemon	Memory retrieval	Stateful runtime	State machine
Context	Pre-compiled, instant	Query on demand	LLM-managed	Checkpoint-based
Tool filtering	Frame-based (75-85% savings)	None	None	None
Multi-agent	Signal protocol + handoff	Shared memory	Single agent	Graph edges
Compaction	Tiered retention	None	LLM-managed	None
MCP native	Built-in server	No	No	No
Infrastructure	SQLite	API + LLM costs	Full runtime	LangChain ecosystem

These aren't competitors — they're complementary. Vigil handles awareness and coordination. Mem0 handles deep memory. Use both.

Get Started

pip install vigil-agent

vigil init
vigil signal my-agent "Starting work on the auth system"
vigil daemon start
vigil status

Or as an MCP server:

pip install "vigil-agent[mcp]"
vigil serve

252 tests. MIT license. Zero external dependencies.

GitHub: github.com/AlexlaGuardia/Vigil
PyPI: pypi.org/project/vigil-agent

This is v1.5.0. The roadmap includes a hosted multi-tenant platform, federation protocol for cross-org agent coordination, and eventually a hardware device (Pi-based always-on awareness hub). If you're building multi-agent systems and fighting the same problems, I'd love to hear how you're solving them.

Managing a WooCommerce Store from Claude — 34 MCP Tools I Wish Existed

Alex LaGuardia — Wed, 25 Mar 2026 21:37:48 +0000

WooCommerce runs 36% of all online stores — over 5 million active sites. If you're using Claude or Cursor and want to check orders, update products, or pull sales reports, you're copy-pasting from WordPress admin like it's 2015.

I built 34 MCP tools that let your AI assistant manage a WooCommerce store directly. Products, orders, customers, coupons, shipping, reports — full CRUD, not just read-only.

What It Does

MCP lets AI assistants interact with external tools directly. With this server installed, you stop tab-switching between Claude and your WordPress admin panel.

Before (manual):

Open WordPress admin
Navigate to WooCommerce → Orders
Filter by date range
Export or copy the data
Paste into Claude
Ask for analysis

After (with mcp-woocommerce):

"Show me all orders from this week. Which products are selling best and what's my average order value?"

Claude calls list_orders, then get_sales_report, and gives you the analysis — all in one conversation.

34 Tools, Full CRUD

Not just reading data — you can manage your entire store:

Products (7): List, get, create, update, delete, manage variations, batch operations
Orders (5): List, get, create, update, add notes
Customers (4): List, get, create, update with full address support
Coupons (3): List, get, create with discount types and usage limits
Reports (4): Sales, top sellers, orders totals, and customer totals
Shipping (3): Zones, methods, and zone-method configuration
Webhooks (3): List, create, delete for real-time event handling
Payments (2): List gateways and toggle enable/disable
System (3): Store info, status checks, and settings

Technical Decisions Worth Sharing

URL Normalization

WooCommerce's REST API lives at /wp-json/wc/v3 under whatever domain the store uses. Users will pass in mystore.com, https://mystore.com, or https://mystore.com/wp-json/wc/v3. The client handles all of them:

base = store_url.rstrip("/")
if not base.startswith(("https://", "http://")):
    base = f"https://{base}"
if not base.endswith("/wp-json/wc/v3"):
    base = f"{base}/wp-json/wc/v3"

One less thing for users to get wrong.

HTTP Basic Auth (The Simple Kind)

WooCommerce uses consumer key/secret pairs over HTTPS — no OAuth dance, no token refresh, no expiration headaches. You generate keys in WordPress admin (WooCommerce → Settings → Advanced → REST API), set the permission level (read, write, or read/write), and you're done.

self._client = httpx.AsyncClient(
    base_url=self.base_url,
    auth=(consumer_key, consumer_secret),
    follow_redirects=True,
)

The follow_redirects=True is important — many WordPress installs have redirect rules (www ↔ non-www, HTTP → HTTPS) that will silently break API calls without it.

Array Responses vs Object Responses

Unlike most APIs that wrap results in {"data": [...], "total": N}, WooCommerce returns bare arrays for list endpoints. Pagination info comes in response headers (X-WP-Total, X-WP-TotalPages), not the body. Every tool handles this:

data = await wc.get("/products", params=params)
products = []
for p in data if isinstance(data, list) else []:
    products.append({...})
return _fmt({"count": len(products), "products": products})

The AI gets a consistent format regardless of WooCommerce's quirks.

Structured Error Codes

WooCommerce returns machine-readable error codes (woocommerce_rest_product_invalid_id, woocommerce_rest_cannot_view) alongside human messages. The client preserves both:

raise WooCommerceError(
    data.get("code", "unknown_error"),
    data.get("message", "No details provided"),
    resp.status_code,
)

When the AI hits an error, it gets enough context to explain what went wrong and suggest a fix — not just "400 Bad Request."

Get Started in 2 Minutes

Install

pip install mcp-woocommerce

Generate API Keys

WordPress Admin → WooCommerce → Settings → Advanced → REST API → Add Key.

Set permissions to Read/Write and save the consumer key and secret.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "woocommerce": {
      "command": "mcp-woocommerce",
      "env": {
        "WOOCOMMERCE_URL": "https://yourstore.com",
        "WOOCOMMERCE_KEY": "ck_your_key",
        "WOOCOMMERCE_SECRET": "cs_your_secret"
      }
    }
  }
}

Claude Code

claude mcp add woocommerce -- env WOOCOMMERCE_URL=https://yourstore.com WOOCOMMERCE_KEY=ck_key WOOCOMMERCE_SECRET=cs_secret mcp-woocommerce

Cursor

Same JSON config as Claude Desktop in .cursor/mcp.json.

What I'd Do Differently

Add batch endpoints sooner. WooCommerce supports batch create/update/delete for products, orders, and coupons in a single API call. I added product batch operations but should have done it across all resources from the start — it's a massive time saver for bulk operations.

Test with a staging store. WooCommerce's behavior varies wildly depending on installed plugins, theme, and WordPress version. A clean WooCommerce install acts differently from one running 30 plugins with custom REST API filters.

Lessons for MCP Server Builders

Handle URL normalization. Don't assume users will pass the exact base URL your client expects. Accept the most natural input and normalize it.
Follow redirects. WordPress sites love redirects. If your HTTP client doesn't follow them, you'll get mysterious failures.
Normalize response shapes. If the API returns arrays sometimes and objects other times, your tools should present a consistent format to the AI.
Preserve error codes. Machine-readable error codes help the AI reason about failures and suggest fixes. Don't throw them away.

Links

GitHub: AlexlaGuardia/mcp-woocommerce
PyPI: mcp-woocommerce
License: MIT

This is part of a series of production-grade MCP servers I'm building for underserved SaaS platforms. Also available: Mailchimp, FreshBooks, ActiveCampaign. Follow me here or on GitHub to catch the next one.

Update (April 2026): Since publishing, mcp-woocommerce has been expanded from 34 to 73 tools (v0.2.0). New coverage includes refunds, reports, shipping zones, tax rates, payment gateways, webhooks, system status, product variations, and order notes. pip install mcp-woocommerce to get the latest.

33 Tools for Mailchimp in One MCP Server — Here's How I Built It

Alex LaGuardia — Tue, 24 Mar 2026 23:37:33 +0000

I wanted to manage my Mailchimp campaigns from Claude without copy-pasting data between tabs. The existing MCP servers for Mailchimp were either read-only, incomplete, or abandoned weekend projects with 3-5 tools.

So I built one with 33 tools that actually covers the full API — campaigns, audiences, members, segments, templates, automations, and reports. Read and write.

What It Does

MCP lets AI assistants interact with external tools directly. With this server installed, instead of tab-switching between Claude and Mailchimp, you just ask:

Before (manual):

Open Mailchimp
Navigate to Campaigns → Reports
Find last campaign
Copy the stats
Paste into Claude
Ask for analysis

After (with mcp-mailchimp):

"How did my last campaign perform? Compare the open rate to my previous 5 campaigns."

Claude calls list_campaigns, then get_campaign_report for each, and gives you the analysis — all in one shot.

33 Tools, Full Read/Write

Not just listing data — you can actually do things:

Campaigns (8): Create, send, schedule, replicate, test, update
Content (2): Get and set campaign HTML/templates
Reports (3): Performance stats, click-level details, open tracking
Audiences (3): List, get details, create new lists
Members (6): Add, update, upsert, archive, search, activity history
Tags (2): List and manage member tags
Segments (3): List, view members, create from emails
Templates (2): List and view template HTML
Automations (3): List, pause, start classic workflows
Account (1): Validate API key and get account info

Technical Decisions Worth Sharing

The Subscriber Hash Gotcha

Mailchimp doesn't identify members by email or UUID. It uses an MD5 hash of the lowercased email. Get this wrong and you get silent 404s — no error message, just empty responses.

@staticmethod
def subscriber_hash(email: str) -> str:
    return hashlib.md5(email.lower().strip().encode()).hexdigest()

Every Mailchimp integration learns this the hard way. My client handles it automatically so the tools just accept plain email addresses.

Upsert Over Separate Create/Update

Instead of separate "add" and "update" tools, I use Mailchimp's PUT endpoint for member management (add_or_update_member). It's a safe upsert — exists? update. New? create.

The critical detail: it uses status_if_new so it won't accidentally resubscribe someone who previously unsubscribed. That's a compliance landmine most implementations miss.

Formatted Responses, Not API Dumps

Mailchimp's API responses are verbose — nested _links, redundant metadata, fields nobody needs. Every tool extracts just the useful fields:

@mcp.tool()
async def get_campaign_report(campaign_id: str) -> str:
    """Get performance report for a sent campaign."""
    mc = get_client()
    r = await mc.get(f"/reports/{campaign_id}")
    return _fmt({
        "emails_sent": r.get("emails_sent", 0),
        "opens": {
            "unique": r.get("opens", {}).get("unique_opens", 0),
            "rate": r.get("opens", {}).get("open_rate", 0),
        },
        "clicks": {
            "unique": r.get("clicks", {}).get("unique_clicks", 0),
            "rate": r.get("clicks", {}).get("click_rate", 0),
        },
        "bounces": {
            "hard": r.get("bounces", {}).get("hard_bounces", 0),
            "soft": r.get("bounces", {}).get("soft_bounces", 0),
        },
        "unsubscribes": r.get("unsubscribed", 0),
    })

The AI gets clean data it can reason about. No parsing gymnastics.

FastMCP Makes Tool Definition Trivial

The official mcp Python SDK with FastMCP generates JSON Schema from type hints and docstrings automatically. A tool is just an async function:

@mcp.tool()
async def list_campaigns(
    status: str = "",
    list_id: str = "",
    count: int = 20,
    offset: int = 0,
) -> str:
    """List email campaigns. Filter by status or audience."""
    # ... implementation

No schema files, no registration boilerplate. Type hints become parameter descriptions. Docstrings become tool descriptions. It just works.

Get Started in 2 Minutes

Install

pip install mcp-mailchimp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mailchimp": {
      "command": "mcp-mailchimp",
      "env": {
        "MAILCHIMP_API_KEY": "your-key-us21"
      }
    }
  }
}

Claude Code

claude mcp add mailchimp -- env MAILCHIMP_API_KEY=your-key mcp-mailchimp

Cursor

Same JSON config as Claude Desktop in .cursor/mcp.json.

What I'd Do Differently

Start with fewer tools. 33 tools gives comprehensive coverage, but 15-20 would handle 95% of use cases. The automation and segment tools are niche — campaigns and members are where the value is.

Test with real data sooner. Mailchimp's free tier is now just 250 contacts and 500 sends/month. I developed mostly against the API docs, which meant some edge cases only showed up during real testing.

Lessons for MCP Server Builders

If you're building MCP servers, here's what Mailchimp specifically taught me:

Watch for silent identity schemes. Mailchimp uses MD5 hashes of lowercased emails as member IDs — no error if you get it wrong, just empty responses. If your target API has non-obvious ID formats, abstract them away.
Prefer upsert over create+update. Mailchimp's PUT endpoint does a safe upsert with status_if_new, so it won't accidentally resubscribe someone. Idempotent operations are always safer when an AI is making the calls.
Strip verbose responses. Mailchimp returns _links, nested metadata, and redundant fields in every response. Extract only what the AI needs to reason about — the fewer tokens, the better the analysis.
Write copy-paste configs. Claude Desktop, Claude Code, Cursor — give people the exact JSON block. Every friction point between install and first use loses a user.

Links

GitHub: AlexlaGuardia/mcp-mailchimp
PyPI: mcp-mailchimp
License: MIT

This is part of a series of production-grade MCP servers I'm building for underserved SaaS platforms. Also available: WooCommerce, FreshBooks, ActiveCampaign. Follow me here or on GitHub to catch the next one.

Update (April 2026): Since publishing, mcp-mailchimp has been expanded from 33 to 71 tools (v0.3.0). New coverage includes e-commerce (stores, orders, carts, revenue attribution), audience analytics (growth history, locations, email client stats), webhooks, merge fields, interest groups, A/B test results, member notes, file manager, landing pages, and batch operations. pip install mcp-mailchimp to get the latest.

I built a CLI inspector for MCP servers

Alex LaGuardia — Thu, 19 Mar 2026 09:19:57 +0000

I run a custom MCP server with 100+ tools. Every time I added a tool or changed a schema, my only options were reading the source or wiring up a test client.

So I built mcpcat — four commands, ~250 lines of Python.

# See what a server exposes
mcpcat tools http://localhost:8100/mcp

# Inspect a specific tool's schema
mcpcat inspect http://localhost:8100/mcp cortex_signal

# Call a tool directly
mcpcat call http://localhost:8100/mcp health

# Check if a server is alive
mcpcat ping http://localhost:8100/mcp

The first version only supported the old SSE transport. It hung on my own server because I use streamable HTTP. Now it auto-detects both.

If you're building or consuming MCP servers and want something like curl but for MCP, give it a try:

pip install git+https://github.com/AlexlaGuardia/MCPcat.git

I wrote a longer post about the build process and the transport detection bug here: alexlaguardia.dev/writing/mcpcat

Built with Python, Typer, httpx, and Rich. MIT licensed. PRs welcome.

How I Built a Cognitive AI Layer That Routes Thoughts to the Right Brain

Alex LaGuardia — Wed, 18 Mar 2026 22:33:46 +0000

Most AI projects call an API and return the response. I built something different — a cognitive layer that classifies every input, routes it to the optimal LLM provider based on complexity and cost, executes tools autonomously in an iterative loop, and compresses memory so conversations never lose context.

It's called Akatskii, and it runs as the brain behind Luna, a personal AI assistant I use daily for managing a SaaS platform, trading systems, and creative projects.

This isn't a tutorial. It's what I learned building a production cognitive architecture from scratch.

The Problem

I needed an AI assistant that could:

Think at different speeds. A status check doesn't need Claude's reasoning. A complex architecture decision doesn't belong on Groq's fast path.
Use tools autonomously. Not "call one function and return" — actually reason through multi-step problems, calling tools iteratively until the task is done.
Remember everything. Conversations shouldn't break when you hit context limits. The system should compress, not truncate.
Cost close to zero. I'm running this 24/7. Paying $0.15/1K tokens for every status check is insane.

No existing framework solved all four. So I built one.

The Router: Regex Before LLM

The most counterintuitive decision I made: use regex for routing, not an LLM.

Here's why. About 80% of inputs to an AI assistant are predictable. "What's the system status?" is always a status check. "Why are posts failing?" always needs reasoning. Pattern matching handles these instantly, deterministically, and for free.

User: "check system health"
→ Regex match: REFLEX (confidence: 0.9)
→ Route to Groq (free, ~150ms)
→ Pre-fetch system_health capability data
→ LLM generates response grounded in real data

Only when regex confidence drops below 0.8 does the system fall back to an LLM for classification — Groq's Llama 3.3 70B, which adds ~100ms and costs nothing on the free tier.

Result: 80% of routing is instant and free. The remaining 20% costs fractions of a cent.

Five Thought Types, Three Providers

Every input gets classified into one of five thought types, each mapped to a different LLM provider:

Type	Provider	Cost	When
Reflex	Groq Llama 3.3 70B	Free	Status checks, lookups, simple queries
Executive	Gemini 2.5 Flash	Free	Reasoning, planning, debugging
Sensory	Gemini 2.5 Flash	Free	Image analysis, multimodal
Creative	Gemini 2.5 Flash	Free	Narrative, prose, worldbuilding
Deep	Claude Sonnet 4	Paid	Complex architecture (explicit escalation only)

The key insight: Claude is never invoked unless the user explicitly asks for it ("need claude", "escalate", "deep dive"). Everything else runs on free providers. My monthly LLM cost for a 24/7 AI assistant: effectively zero.

The Agentic Loop: Let the LLM Decide When It's Done

This is where it gets interesting. When a thought requires tools, the brain enters an iterative loop:

for iteration in range(15):
    response = llm.call_with_tools(messages, available_tools)

    if response.is_text:  # LLM decided it's done
        return response

    # Execute tool calls (parallel if multiple)
    for tool_call in response.tool_calls:
        result = await execute_mcp_tool(tool_call)
        messages.append(tool_result(result))

    # Loop: LLM sees results, decides next action

The LLM reasons, calls tools, gets results, reasons again — up to 15 iterations. It decides when the task is complete, not the developer. Multiple tool calls in a single response execute in parallel via asyncio.gather.

If the iteration limit is hit, instead of silently returning incomplete work, the system runs a continuation pass — a second invocation with the partial results as context, giving the LLM one more chance to synthesize a complete response.

The tool bridge connects to a Model Context Protocol (MCP) server with 40+ tools via direct Python imports — no HTTP overhead, no serialization, no auth handshake. The LLM can check system health, query databases, manage content pipelines, execute trades, and signal other agents.

Memory Compaction: Compress, Don't Truncate

Long conversations hit context limits. Most systems handle this by dropping old messages. That's like treating amnesia by forgetting harder.

Akatskii's compaction engine does something different:

A daemon monitors conversation token count
At 180K tokens, it triggers compaction
Gemini extracts structured facts: decisions, preferences, technical details, context
It generates dual summaries — a short continuity hint (2-3 lines) and a detailed snapshot (1-2 paragraphs)
Facts persist to a knowledge base. Snapshots persist as episodic memory.
The conversation resumes with compressed context

Target compression: 3x. A 180K token conversation becomes ~60K tokens of distilled context, and nothing meaningful is lost. The user sees: "A moment while I gather my thoughts..." — then the conversation continues seamlessly.

Room-Aware Personality

Luna isn't one personality. She adapts based on context.

In an engineering room, she's technical and direct. In a trading room, she's analytical and cautious. In a creative room, she writes prose. Each room also filters which tools are available — the trading room gets market tools, the build room gets code execution, and they can't cross boundaries.

Same brain, different capabilities, different voice. This is implemented through room configs that define system prompts, tool allowlists, and persona adjustments per context.

Background Autonomy

Three daemon processes run independently:

Heartbeat (every 5 min): evaluates trigger conditions, syncs calendar, fires proactive notifications
Scout (every 4 hours): monitors HackerNews, Reddit, and GitHub for relevant news, scores findings, caches for later surfacing
Shadow Runner: picks up queued tasks and executes them through the full agentic loop — autonomously, with no user interaction

The Shadow Runner is the most interesting. It's essentially the same brain, but running headless on queued work. It loads room-specific configs, decomposes complex tasks, retries on failure, and reports results back to the task queue. Autonomous execution without supervision.

What I'd Do Differently

The router patterns are hand-crafted. 40 regex patterns work, but they're brittle. A learned classifier (fine-tuned on routing decisions) would generalize better. I haven't done this because the regex approach works well enough and costs nothing.

Tool definitions are static. The MCP bridge maps capabilities to tools at import time. A more dynamic system would discover tools at runtime and let the LLM choose from the full inventory. MCP's tool discovery protocol supports this — I just haven't needed it yet.

Compaction loses nuance. Fact extraction captures the "what" but sometimes misses the "how we got there." The reasoning chain that led to a decision is harder to compress than the decision itself. I'm exploring storing reasoning traces alongside facts.

The Stack

Layer	Technology
Runtime	Python 3.11, FastAPI, asyncio
LLM Providers	Gemini 2.5 Flash, Groq Llama 3.3 70B, Claude Sonnet 4
Tools	Model Context Protocol (MCP) — 40+ tools
Memory	SQLite + fastembed (all-MiniLM-L6-v2, 384-dim vectors)
Voice	OpenAI Whisper (STT), ElevenLabs soundboard + Edge TTS
Process Management	PM2

Try It

The full source is at github.com/AlexlaGuardia/Akatskii. The MCP server it connects to is at github.com/AlexlaGuardia/guardia-mcp.

If you're building something similar — or if you've solved any of the problems I mentioned differently — I'd genuinely like to hear about it.

I'm Alex, a full-stack software engineer building AI systems, game engines, and production platforms. I write Python, Rust, and TypeScript. Find me on GitHub or LinkedIn.