Builderforce MCP Server

Builderforce.ai

A human-in-the-loop, fully agentic cloud — train your own AI agents and use them inside your own agent, manage your whole workforce on a Kanban board, and review and approve every action without ever leaving VS Code.

---

What is Builderforce.ai?

Builderforce.ai is a human-in-the-loop, fully agentic cloud where ideas become software and software becomes agents. You stay in control of every step while AI agents do the work — train your own specialist agents and put them to work inside your own agent, manage the whole workforce from a Kanban board, and review, validate, and approve everything without leaving your editor. It combines a full in-browser IDE with an AI training pipeline, a Workforce Registry for specialist agents, and an orchestration portal for self-hosted BuilderForce Agents meshes.

Three capabilities at the core:

One platform. Three roles:

---

Key Capabilities

In-Browser IDE

• Full Node.js runtime via WebContainers — run npm install, Vite dev servers, and interactive shells without leaving the browser
• Monaco Editor with syntax highlighting, IntelliSense, multi-file tabs, and real-time collaborative editing via Yjs CRDT
• xterm.js terminal connected directly to the WebContainer shell — full PTY, shared across collaborators
• AI Chat Panel — streaming AI assistant with full project file context; can apply code changes and create files directly
• Live Preview — iFrame running the Vite dev server; updates on save

AI Training Studio

• In-browser LoRA fine-tuning — uses @seanhogg/builderforce-memory / Transformers.js with WebGPU; trains Mamba-1/2/3 and GPT-style models up to 2B parameters entirely client-side
• Hybrid Local Brain — Mamba State Engine (mamba-engine.ts) runs an O(n) selective scan alongside transformer inference; agent state persists to IndexedDB as a compact Float32 state vector and is embedded in exported AgentPackage JSON
• Dataset generation — LLM-assisted JSONL instruction dataset creation with SSE streaming progress
• AI evaluation — independent judge scores model outputs on code correctness, reasoning quality, and hallucination rate (0.0–1.0)
• WebGPU fallback — CPU software path via forceFallbackAdapter: true; platform reports gpuMode: 'cpu-fallback' transparently

Workforce Registry

• Publish specialist agents — bundle a LoRA adapter, capability profile, and MambaStateSnapshot into a portable AgentPackage JSON artifact
• Skill-based discovery — agents are searchable by skills, evaluation score, and hire count
• Hire and deploy — one click to register an agent in your BuilderForce Agents mesh; PowerShell install script for local deployment
• Iterative improvement — training_sessions table tracks dataset → training → evaluation → re-training loops for continuous agent quality improvement

Local LLM Inference Pipeline

• Per-agent inference endpoint — POST /api/ide/agents/:id/chat routes inference through OpenRouter with the agent's persona injected into the system prompt; X-Inference-Mode: lora | hybrid | base | fallback-base header signals which path ran
• Mamba state injection — v2.0 agents carry a MambaStateSnapshot; each inference call prepends [Memory: step=N signal=X context="..."] to the system prompt, giving the agent persistent conversational memory without re-training
• Mamba state sync — PUT /api/ide/agents/:id/mamba-state accepts a MambaStateSnapshot from CoderClaw after each session; upgrades the agent package to v2.0 and recomputes inference_mode; GET /api/ide/agents/:id/mamba-state retrieves the stored snapshot
• Package versioning — agent packages are v1.0 (LoRA only) or v2.0 (LoRA + Mamba state); GET /api/ide/agents/:id/package returns the correct format and increments request_count
• Workforce routing in chat — POST /api/ai/chat with model: "coderclawllm/workforce-<agentId>" auto-routes to the agent inference endpoint; no client-side changes required
• Inference logging — agent_inference_logs table captures model ref, latency, token counts, status, and inference mode per request for observability and billing

BuilderForce Agents Orchestration Portal

Builderforce.ai is the cloud-side control plane for BuilderForce Agents self-hosted agents:

• Fleet registration — Claws register at POST /api/claws with machine profile (IP, workspace dirs, ports, tunnel metadata)
• Heartbeat + capability sync — PATCH /api/claws/:id/heartbeat keeps capability maps and machine profiles current
• Assignment context — GET /api/claws/:id/assignment-context delivers assigned project metadata and context hints; CoderClaw syncs to .coderClaw/context.yaml
• Claw-to-claw mesh relay — ClawRelayDO Durable Object proxies WebSocket connections between Claws; POST /api/runtime/forward dispatches tasks to remote agents with HMAC-SHA256 payload verification (X-Claw-Signature)
• Approval gates — human-in-the-loop control for high-impact agent actions; agents request approval before executing; outcomes are audited
• Task management — tasks and executions tables track work assigned to specific Claws; POST /api/tasks/next feeds the next task to a waiting agent

Multi-Tenant Platform

• JWT auth with web token (global) + tenant token (workspace-scoped) dual-token model
• Multi-auth — email/password, OAuth social login (Google, GitHub, LinkedIn, Microsoft), and magic link sign-in all coexist on the same account
• Tenant isolation — all resources (projects, claws, agents, training jobs) are scoped to a tenant; no cross-tenant data access
• Multi-workspace — users belong to multiple tenants; bf_default_tenant_id auto-selects on login
• Admin observability — /admin surface for platform admins (superadmin flag); logs/global-errors.txt in R2; /observability LLM usage metrics

Billing & Subscriptions (Stripe)

• Stripe only — src/infrastructure/payment/StripeProvider.ts (Stripe Checkout + Billing, hosted payment page, webhook-activated). There is deliberately no provider switch and no manual fallback: a fallback that activated plans without charging meant an unconfigured deploy handed out paid plans for free.
• PaymentProvider interface — src/infrastructure/payment/PaymentProvider.ts keeps TenantService off the concrete Stripe client and lets tests inject a fake; it is not a provider-swap seam.
• Checkout flow — POST /api/tenants/:id/subscription/checkout always returns a hosted checkoutUrl. The plan activates only when the signed webhook confirms payment — never from the request itself.
• Webhook handler — POST /api/webhooks/payment receives Stripe events; HMAC-verified with a 5-minute replay window; activates/cancels subscriptions via normalised WebhookEvent
• Configuration — set the STRIPE_* Worker secrets (see src/infrastructure/payment/index.ts). They are validated lazily: absent secrets return 503 from the billing routes and never break Worker boot.

Dev Analytics & Team Intelligence

• Contributor profiles — cross-platform developer identity reconciliation (GitHub, Jira, Bitbucket); GET /api/contributors
• Activity ingestion — POST /api/contributors/activity receives PR opened/merged/reviewed, commit, issue events with automatic daily metric aggregation
• Weighted activity score — per-contributor daily score (commits×1 + PRs×3 + reviews×2 + issues×1.5); active dev day = ≥1 commit or PR action
• PR cycle time — end-to-end hours from pr_opened to pr_merged events tracked on each activity record
• Integration credential manager — AES-256-GCM encrypted platform credentials stored per-tenant; GET/POST/PUT/DELETE /api/integrations; per-provider connectivity tests (POST /api/integrations/:id/test)
• Team hierarchy — nested dev teams with manager–member relationships; GET/POST/PATCH/DELETE /api/dev-teams; member add/remove endpoints
• Standup report — GET /api/reports/standup — daily summary: active contributors, commits, PRs merged, issues resolved; recent PRs and resolved issues
• Code review report — GET /api/reports/code-review — 14-day window; stale PRs (>7 days old), average cycle time, reviewer activity
• Executive summary — GET /api/reports/executive — KPIs over configurable date range: contributor counts, total commits, PRs merged, lines added, average activity score, top contributors
• Report schedules — GET/POST/PATCH/DELETE /api/reports/schedules; cron-style delivery config (daily/weekly) with hour-of-day and recipient list
• Report subscriptions — GET/POST /api/reports/subscriptions; per-user opt-in/opt-out per report type

Platform Infrastructure

• Per-tenant rate limiting — TenantRateLimiterDO Cloudflare Durable Object; sliding window (60 RPM FREE, 300 RPM PRO, 1000 RPM TEAMS); X-RateLimit-Limit/Remaining/Reset + Retry-After headers
• Auto-approval rules — GET/POST/PATCH/DELETE /api/approval-rules; rule evaluation on POST /api/approvals by actionType, max cost, max files changed; bypasses human gate when conditions match
• Approval notifications — Slack webhook + Resend email alerts on new approval requests and decisions; configurable via SLACK_APPROVAL_WEBHOOK_URL + RESEND_API_KEY
• Escalation cron — GET /api/approvals/escalate?secret= expires timed-out pending approvals and fires Slack alert; suitable for Cloudflare Cron Triggers
• OTel telemetry proxy — POST /api/telemetry/spans ingest; GET /api/telemetry/spans query; GET /api/telemetry/traces list; costs stored as millicent integers; W3C X-Trace-Id header forwarded from CoderClaw

---

Latest Capabilities

The platform has grown from an IDE-plus-training studio into a full system of record for agentic work. These are the most recent additions — the enterprise delivery, quality, knowledge, and FinOps surfaces that sit on top of the agent workforce.

Planning Spine — Portfolio to Task (mig 0213, 0225)

• One dated, cost-bearing hierarchy — portfolio → initiative → epic → task, with Objectives and Key Results attaching as a goal layer at any level. Every level is dated and rendered on a single nested Gantt (PlanningSpineGantt).
• Cost rolls up from the leaf — LLM spend (priced at write time from llm_usage_log) plus human effort (member cost rate × hours) rolls up to every ancestor. No parallel finance system, no backfill.
• CAPEX / OPEX split — each node carries a cost_class resolved in priority order (explicit → inherited → agent-classified by investment category → GAAP-conservative default). A child class that contradicts its parent is flagged as an anomaly for PM reconciliation.
• Endpoints — GET /api/pmo/spine, GET /api/pmo/spine/export.csv, GET /api/pmo/rollup (portfolio/initiative/workspace), PATCH /api/pmo/cost-class, POST /api/pmo/cost-class/classify, initiative POST/DELETE /api/pmo/dependencies (cycle-checked) → on-demand critical path. Surface: /projects?tab=portfolio, gated by insights.portfolio / insights.pm.

Quality — Error Observability + One-Click Agent Fix (mig 0240)

• Multi-source ingest — one canonical event shape behind five adapters: native (the @seanhogg/builderforce-quality browser SDK), OTLP, Sentry, PostHog, LogRocket (webhooks HMAC-verified; Sentry connections can backfill).
• Fingerprint grouping — events upsert into error_groups keyed by (tenant, project, fingerprint) — explicit fingerprint or derived from the top stack frame + normalized message; occurrence + exact distinct-user counts; resolved bugs reopen on recurrence.
• One-click fix loop — POST /api/quality/groups/:id/fix creates a board task (titled + prioritized from the error, briefed with the stack trace) and dispatches a cloud agent that ships a pull request. Crash → group → task → PR on one surface.
• Endpoints — authenticated /api/quality/* (collectors, integrations, rules, groups, fix); public keyed/HMAC ingest /api/quality-ingest/{events,otlp/v1/logs,otlp/v1/traces,webhooks/:collectorId/:provider}. Dashboard: /quality. Metered as error_events.

Knowledge Management & Compliance (mig 0227)

• Versioned SOPs, processes & docs — live editable body plus an immutable snapshot on every publish (version number + change note + publisher).
• Audit-ready acknowledgements — read-acknowledgements bind to a specific version with a timestamp; per-user state is acknowledged / pending / overdue, with manager rollups at GET /api/knowledge/compliance — evidence for SOX, TISAX, ISO 27001.
• AI authoring + analysis — POST /api/knowledge/ai/draft streams a Markdown draft; POST /api/knowledge/documents/:id/analyze returns structured findings (inefficiency / gap / risk / clarity) + an improved flow. Metered through the LLM gateway.
• Real-time co-editing — Yjs CRDT over NEXT_PUBLIC_COLLAB_WS_URL with presence awareness; per-document editor/viewer collaborators on top of workspace roles; falls back to autosave when collaboration is unconfigured. Surface: /knowledge.

Single-Pane Board Connectors (mig 0221)

• Two-way sync across 10 systems — each provider implements fetchTicketsSince(cursor) + pushUpdate(externalId, changeSet), normalizing to one ticket shape stamped with its source.
  • PM / work: GitHub Issues, Jira, Linear, monday.com, Asana, ClickUp
  • ITSM: ServiceNow, Freshservice
  • Incident: Sentry, PagerDuty
• Webhooks where supported (GitHub, Jira, Linear, monday, Sentry, PagerDuty), polling otherwise. Agents act on a ticket or incident wherever it originates; changes flow back to the system of origin — single pane, no migration.
• Endpoints — GET /api/board-connections/providers (catalog), CRUD /api/board-connections, POST /api/board-connections/:id/sync, GET /api/board-connections/:id/links.

Platform Migration & Integration Hub (mig 0256)

Move off a competitor tracker without fear, or just sync data in — a staged importer on top of the connector framework. Nothing lands in real projects/tasks/members until you commit.

• Provider discovery — discover() enumerates external projects, item types, and users for Jira, monday, Rally, GitLab, Bitbucket, GitHub (the migration-eligible providers; new Rally/GitLab/Bitbucket adapters added).
• Staging buffer — import_runs + import_staged_{projects,items,users} + import_type_mappings; combine several external projects into one BuilderForce project, map item types → task type/status, and invite/map users — all reviewed before import.
• Migrate / sync / both — one-time historical import, an ongoing board_connections sync, or both. The persistent board_type_mappings makes ongoing sync land tasks in the mapped type/status (not a hardcoded backlog). Imported items keep their assignee (mapped to a member) and story points.
• Integrations gallery — /settings/integrations is the workspace home: cards by category (PM / SCM / ITSM / incident), per-provider config panel (Credentials · Connections · Activity/diagnostics), and a "Start migration" launcher. GitHub/GitLab/Bitbucket connect both issues (migration) and repositories (code).
• Brain-drivable — the whole flow is in the gateway MCP catalog (integrations.create_credential/test, migrations.start/set_mappings/stage/commit); the Brain (right-docked) opens the migration panel on the left via open_migration_panel.
• Endpoints — /api/migrations (start/list/get/:id/mappings/:id/stage/:id/commit, MANAGER+, cached + version-bumped).

Agentic Tester — Autonomous QA (mig 0063, 0206)

• Heatmap-ranked exploration — journey events (POST /api/qa/events) rank route-and-element zones by recency-weighted frequency (GET /api/qa/heatmap); explorations plan from the hottest zones within a budget.
• AI-generated Playwright — POST /api/qa/generate turns a flow into an executable spec and resolves a persona credential; a deterministic heatmap-only plan is also available (no model cost).
• Authenticated container runs — a harness claims an exploration, logs in as a real persona (encrypted, developer-gated credentials), walks the plan, and captures console/page errors, failed requests, assertion failures, and crashes.
• Findings → board → fix — findings dedupe by fingerprint; with auto-routing enabled, any finding at/above the severity threshold becomes a board task in a fix lane, firing the same lane auto-run a human board drag triggers → a fix agent opens a PR. Schedules run it on cron. Quality trend (escaped vs caught defects) at GET /api/qa/quality.

Consumption Metering (mig 0218)

• Meter on consumption, not visibility — one framework (/api/consumption) reports month-to-date usage for ai_tokens, ingestion (bytes), and error_events against the plan allowance, using the same accountants the gateway and ingestion gate enforce — so the "% used" a member sees equals the cap that's enforced. Cached 60s, keyed per tenant + calendar month.

Coordinated Role Participation & Accountability (mig 0334)

• The right role does the work — first-class agent↔role capability (ide_agents.role_keys) drives role-aware assignment: a producer stage resolves the role from the ticket's action_type and dispatches a role-capable agent/human, never a mis-assigned one. Stops the "a Product Manager was dispatched to write code" class of failure.
• A participation manifest per ticket — ticket_participants derives the required roles from the board's swimlane requirements, resolves each slot by capability, and tracks per-participant state (pending / assigned / in_progress / completed / changes_requested / waived / unstaffed).
• An immutable Accountability Report — an append-only ticket_role_signoffs ledger records Who / When / Verdict / Comments / Contribution per role; default-deny RBAC (only role-capable members may sign off as a role); every sign-off emits to the unified activity log. A Resource Assessment control adds a needed role beyond the template — an unresolved add surfaces as a blocking resource gap.
• Endpoints — GET /api/kanban/tasks/:id/accountability, /participants, POST /participants (assess) / /materialize, plus MCP kanban.participants / kanban.accountability / kanban.assess_resource. Surface: the ticket-drawer Accountability tab + a board X/Y participants chip.

Pre-Sales RFP / RFQ Response (mig 0335)

• Turn a repo into a proposal — CTO + Product Owner built-in agents generate a branded, costed proposal from a project's analyzed capabilities: cost / P&L, a phase Gantt, risks, dependencies, and a capability roster matched to the ask.
• Co-branded output — the requester's palette + logo blend with the responder's for a branded, self-contained proposal document (print-to-PDF / download), with freshness-gated grounding (a >5-day-stale scan re-runs the deterministic system audits before answering).
• Surface — a Projects RFP tab (list / create) + /projects/rfp/[id] detail; /api/rfp routes.

Incident Management & Active Monitoring (mig 0292)

• Incidents close the loop — a Help-Desk / Incident-Manager agent, a Freshdesk connector, on-call rotations, timed escalation, Teams / Slack / email paging, and a per-incident war-room feed. On resolution the RCA is published to Knowledge and fed to the project's Evermind, so the workforce learns and stops repeating causes.
• A monitoring canvas — pin heartbeat / HTTP / webhook / metric monitors onto an uploaded architecture diagram; a */5 sweep evaluates them and a breach auto-starts the on-call investigation (monitor → signal → incident → paging), with reporting on the timeline.

Meetings & Live Collaboration (mig 0292, 0330)

• Video / audio meetings with agents in the room — mesh WebRTC over a CeremonyRoomDO relay; agent attendees speak live via a caption / transcript bridge; recording + transcription produce AI minutes. Google / Microsoft calendar sync. Surface: /meetings.

AI Managers — Types & Coaching (mig 0327)

• Typed managers tied to the role catalog — Dev / QA / Service-Desk / DevOps manager types map to roleCatalog (custom roles become role:<key> types); a human → manager Coaching Session carries directive | task modes with expiry / done state, steering how a manager agent runs its reports.

Memory-First Answering — skip the paid LLM

• Answer from the project's own memory before spending a model call — the web and VS Code webview Brain consult the project's project_facts fact tier + its Evermind SSM first and short-circuit the LLM on a confident hit (an exact-repeat Q&A cache + opt-in Evermind-first inference), single-sourced in resolveMemoryAnswer. Learning fans out to every Evermind under a project (its own head + its IDE builds' heads) via one shared contributeTextToProjectEverminds. Endpoints: GET/POST /api/projects/:id/answer, GET /api/projects/:id/evermind/targets.

---

Authentication

Builderforce.ai supports three sign-in methods that coexist on the same account. A single user can link multiple OAuth providers, set a password, and use magic links interchangeably.

Sign-in methods

Supported OAuth providers: google, github, linkedin, microsoft.

Auth flow diagram

Browser
  │
  ├─ Email/password ──────────────────────────► POST /api/auth/web/login
  │                                              Returns JWT in JSON body
  │
  ├─ OAuth (click button) ────────────────────► GET /api/auth/oauth/:provider
  │                                              302 → provider consent screen
  │                                              Provider → GET /api/auth/oauth/:provider/callback
  │                                              API issues JWT
  │                                              302 → /auth/callback?token=JWT
  │                                              Frontend page writes token to localStorage
  │
  └─ Magic link ──────────────────────────────► POST /api/auth/magic-link
                                                 Email sent with /auth/magic-link?token=…
                                                 Frontend page calls GET /api/auth/magic-link/verify
                                                 Returns JWT in JSON body

JWT strategy

• Web token (localStorage key: bf_web_token) — 24-hour HMAC-SHA-256 JWT; payload: { sub, email, username, amr?, sa?, jti, sid }
• Tenant token (localStorage key: bf_tenant_token) — 1-hour workspace-scoped JWT; issued by POST /api/auth/tenant-token
• Every issued token is tracked in the auth_tokens table (JTI + session ID); webAuthMiddleware validates against this table on every request, enabling instant revocation

Account management endpoints

OAuth security

• CSRF protection — OAuth state parameter is HMAC-SHA-256 signed (using JWT_SECRET) with a nonce and 10-minute expiry; no database required
• Account linking — if an OAuth email matches an existing account, the provider is linked automatically; the user controls their email so this is safe
• Email-only users — OAuth users who haven't set a password are protected from the unlink endpoint; they must POST /api/auth/add-password first

Enabling OAuth providers

Each provider is activated by supplying its client credentials as Cloudflare Worker secrets. Providers with missing credentials silently return 503 — you only need to configure the providers you want.

# Google
wrangler secret put GOOGLE_CLIENT_ID
wrangler secret put GOOGLE_CLIENT_SECRET

# GitHub
wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET

# LinkedIn
wrangler secret put LINKEDIN_CLIENT_ID
wrangler secret put LINKEDIN_CLIENT_SECRET

# Microsoft
wrangler secret put MICROSOFT_CLIENT_ID
wrangler secret put MICROSOFT_CLIENT_SECRET

Register the OAuth callback URL in each provider's dashboard:

https://api.builderforce.ai/api/auth/oauth/{provider}/callback

Replace {provider} with the lowercase provider name: google, github, linkedin, microsoft.

Provider setup

---

Google

1. Go to console.cloud.google.com, create or select a project
2. APIs & Services → OAuth consent screen
   • User Type: External
   • App name, support email, add scopes: email, profile, openid (non-sensitive, no review required)
   • Add your email as a test user while in development
3. APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID
   • Application type: Web application
   • Authorized redirect URIs — add both:

     https://api.builderforce.ai/api/auth/oauth/google/callback
     http://localhost:8787/api/auth/oauth/google/callback
     

4. Copy Client ID and Client Secret:

   wrangler secret put GOOGLE_CLIENT_ID
   wrangler secret put GOOGLE_CLIENT_SECRET
   

Publishing: While in "Testing" mode only test users can sign in. Click Publish App on the consent screen when ready for production — email/profile/openid are standard scopes and are typically approved immediately with no manual review.

---

LinkedIn

1. Go to linkedin.com/developers → Create App
   • App name, LinkedIn Company Page (required — create one if needed), logo
2. Auth tab → Authorized redirect URLs — add both:

   https://api.builderforce.ai/api/auth/oauth/linkedin/callback
   http://localhost:8787/api/auth/oauth/linkedin/callback
   

3. Products tab → request "Sign In with LinkedIn using OpenID Connect" — click Request access (auto-approved instantly). This unlocks the openid profile email scopes used by the code. Without it the /v2/userinfo endpoint will not return the email address.
4. Back on the Auth tab, copy Client ID and Client Secret:

   wrangler secret put LINKEDIN_CLIENT_ID
   wrangler secret put LINKEDIN_CLIENT_SECRET
   

---

GitHub

1. GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
   • Homepage URL: https://builderforce.ai
   • Authorization callback URL:

     https://api.builderforce.ai/api/auth/oauth/github/callback
     

2. Click Register application, then Generate a new client secret
3. Set secrets:

   wrangler secret put GITHUB_CLIENT_ID
   wrangler secret put GITHUB_CLIENT_SECRET
   

Local dev: GitHub allows only one callback URL per app. Create a separate OAuth App (e.g. "builderforce-dev") pointing to http://localhost:8787/api/auth/oauth/github/callback and use its credentials in api/.dev.vars.

---

Microsoft

1. Azure Portal → Microsoft Entra ID → App registrations → New registration
   • Supported account types: "Accounts in any organizational directory and personal Microsoft accounts"
   • Redirect URI (Web):

     https://api.builderforce.ai/api/auth/oauth/microsoft/callback
     

2. Certificates & secrets → New client secret — copy the value immediately (it's only shown once)
3. Copy the Application (client) ID from the Overview page
4. Set secrets:

   wrangler secret put MICROSOFT_CLIENT_ID
   wrangler secret put MICROSOFT_CLIENT_SECRET
   

---

Local development

For local development, use api/.dev.vars — Wrangler loads this file automatically for wrangler dev, and it is gitignored:

# api/.dev.vars
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
LINKEDIN_CLIENT_ID=your_linkedin_client_id
LINKEDIN_CLIENT_SECRET=your_linkedin_client_secret
GITHUB_CLIENT_ID=your_github_dev_app_client_id
GITHUB_CLIENT_SECRET=your_github_dev_app_client_secret
APP_URL=http://localhost:3000

The OAuth callback URL is derived from the incoming request's Origin header at runtime, so no extra API_URL variable is needed — it resolves to http://localhost:8787 locally and https://api.builderforce.ai in production automatically.

Magic link email

The sendMagicLinkEmail function in api/src/presentation/routes/oauthRoutes.ts is a placeholder that logs the link to the console. Wire it to your email provider (Resend, SendGrid, Mailgun, etc.) before using magic links in production:

// api/src/presentation/routes/oauthRoutes.ts  ~line 253
async function sendMagicLinkEmail(to, name, token, frontendUrl) {
  const magicUrl = `${frontendUrl}/auth/magic-link?token=${encodeURIComponent(token)}`;
  // TODO: call your email provider here
}

Frontend routes added

---

Integration with BuilderForce Agents

Developer workstation
  └─ BuilderForce Agents (self-hosted, MIT)
       ├─ 7-role agent DAG (Code, Review, Test, Debug, Refactor, Document, Architect)
       ├─ Staged diff review (accept/reject before writing to disk)
       ├─ Agent-to-agent mesh (remote:<id>, remote:auto[caps], HMAC-signed dispatch)
       ├─ Workflow telemetry → .builderforce/telemetry/ + portal timeline
       ├─ Execution lifecycle → running/completed/failed reported to portal
       ├─ Approval gate → blocks on manager decision from portal
       ├─ Skill registry → loads portal-assigned skills at startup
       ├─ Cron scheduler → executes portal-managed jobs on schedule
       └─ BUILDERFORCE_API_KEY → heartbeat → Builderforce.ai
                                                      │  ←task.assign / task.broadcast
                                                      │  ←approval.decision
                                                      │  ←cron jobs / skill assignments
                                              ┌───────▼───────┐
                                              │ Builderforce  │
                                              │  .ai          │
                                              │               │
                                              │ • Fleet view  │
                                              │ • Task assign │
                                              │ • Approvals   │
                                              │ • Audit log   │
                                              │ • AI training │
                                              │ • Registry    │
                                              │ • Cron jobs   │
                                              │ • Skills mkt  │
                                              └───────────────┘

Configure CoderClaw to connect:

export BUILDERFORCE_API_KEY=<your-api-key>
export BUILDERFORCE_URL=https://api.builderforce.ai
coderclaw start

CoderClaw operates fully standalone without Builderforce. The connection unlocks fleet visibility, task assignment with live execution tracking, enforced approval gates, portal-managed skill assignments, scheduled cron execution, and access to the Workforce Registry.

---

On-Device AI Stack

Builderforce.ai is built on the open-source @seanhogg/builderforce-memory stack for on-device AI:

@seanhogg/builderforce-memory-engine  (engine)
  └─ WebGPU WGSL kernels: Mamba-1 (S6), Mamba-2 (SSD), Mamba-3 (complex MIMO+ET), causal attention
        ↓
@seanhogg/builderforce-memory  (runtime)
  └─ MambaSession.create() — one-call GPU init, tokenizer, model, checkpoint, persistence
  └─ Inference routing · distillation · semantic memory · SSMAgent
        ↓
Builderforce.ai IDE
  └─ mamba-engine.ts  — Hybrid Local Brain (SSM state + IndexedDB)
  └─ agent-runtime.ts — step() → inference → confidence scoring → cloud escalation
  └─ webgpu-trainer.ts — LoRA fine-tuning pipeline (Transformers.js + WebGPU)

The on-device AI layer runs in O(n) time (vs O(n²) for attention), making it suitable for continuous low-latency state updates and fine-tuning entirely in the browser.

Both packages are published on npm: @seanhogg/builderforce-memory-engine (engine) and @seanhogg/builderforce-memory (runtime).

Cross-surface semantic cache (token savings)

The biggest cost lever in the stack is an embedding-keyed semantic cache that reuses a prior answer when a new prompt is a paraphrase of one already answered — so the frontier model is never called for semantically-repeated work. It is two-tier and shared across surfaces:

• L1 (local, free): in-process cosine match using on-device SSM embeddings — runs in the browser IDE and in each agent.
• L2 (shared): the gateway's POST /v1/semantic-cache/{lookup,store} (tenant-scoped, KV-backed). A paraphrase answered in the web app is reusable by an agent, and vice-versa.

The same portable SemanticCache from @builderforce/memory powers both surfaces — the embedder (on-device SSM) and the L2 backend are injected, so there is no browser/Node fork. On-device embeddings make L1 free; the gateway L2 turns one tenant's cache hits into platform-wide savings.

Hybrid retrieval & answer evaluation

Builderforce.ai implements the full seven-layer agent stack — and the two layers most stacks leave conventional-thin (RAG retrieval and evaluation) are built out:

• Hybrid RAG. Retrieval fuses dense (SSM / OpenAI embeddings, cosine) and sparse (Okapi BM25 keyword) signals with Reciprocal Rank Fusion, then reranks with MMR for relevance and diversity — over documents chunked with a recursive splitter + overlap. Dense search alone misses exact tokens (identifiers, error codes, rare names); the hybrid path catches them. It degrades gracefully (no embedding → BM25-only; no overlap → dense-only). Lives zero-dependency in @seanhogg/builderforce-memory/retrieval (chunkText, bm25Search, reciprocalRankFusion, maximalMarginalRelevance, hybridRetrieve, MemoryStore.recallHybrid) and powers the LanceDB long-term-memory extension.
• Semantic evaluation + drift. Every cloud run is scored for faithfulness, answer relevance, and hallucination rate — inline and zero-cost (lexical), with an LLM-as-judge upgrade on demand at POST /api/eval (billed through the metered gateway). Scores persist on the run record; a drift monitor (mean-shift z-score + Population Stability Index) compares baseline vs recent windows per (action-type × model) and raises an alert when quality regresses — daily on cron and on demand at GET /api/eval/drift. A wrong answer no longer hides behind a green dashboard.

See the write-up: The AI Agent Tech Stack, Built.

---

Architecture

Documentation truncated — see the full README on GitHub.