AgentGem — System Architecture

One Zod contract → REST + MCP + OpenAPI · CLI and Desktop host the same core · optional workflow analyze · archive, targets, registry, and deploy

Hosts · the web UI + local agent reach the same operations Contract surface · one Zod definition → three boundaries (schemas.ts) Workflow-aware recommendation · POST /workflow/analyze (+ SSE) — optional pre-build assist Gem core — src/gem · pure, framework-agnostic redaction trust boundary Desktop (Electron) embeds server · tray · auto-update Web UI (browser) src/public/index.html Local coding agent Claude / Codex / … REST · GemController /api/* — 35+ endpoints MCP · GemTools /mcp — 6 tools OpenAPI 3.1 /explorer (Swagger UI) scan transcripts → WorkflowSignal (deterministic) ACP recommender local Claude · degrades det. → GemSelection pre-checked in the UI feeds buildGem's selection introspect ~/.claude · plugins → ConfigInventory redact strip secrets → SecretRef[] buildGem select + checks → Gem archive manifest + lock fs · tar.gz neutral Gem · manifest + lock (the source every consumer reads) Targets (materialize) Eve · Flue · A2A OpenAI Sandbox · AgentCore → generated FileTree Registry GitHub-backed publish · resolve merge · install Deploy backends Anthropic Managed Agents AWS Bedrock AgentCore + deploy record Testbed & Run local .claude testbed eve / vercel cloudflare run Server state — ~/.agentgem workspaces/ · recents.json · .env (credentials) · deploy records HTTP MCP Host / UI Contract / compose Targets / deploy Archive / state Redaction External

One contract, three boundaries

  • • Each op defined once as a Zod contract
  • • Surfaced as REST (GemController) + MCP (GemTools)
  • • OpenAPI 3.1 + Swagger /explorer derived from it
  • • CLI server and Desktop (Electron) host the same core

Workflow-aware analyze (opt-in)

  • • Scans Claude transcripts → deterministic WorkflowSignal
  • • A local ACP agent clusters + names a Gem
  • • Falls back to a frequency ranking; never throws
  • • Emits a pre-checked GemSelection over SSE

Redaction at capture

  • • Secrets stripped the moment config is read
  • • By value (entropy) and by key name (regex)
  • • Only redacted shapes cross any boundary
  • • buildGem re-redacts as defense in depth

Gem as neutral source

  • • manifest + lock archive (dir or .tar.gz)
  • • Targets (Eve · Flue · A2A · Sandbox · AgentCore), registry, deploy read the same Gem
  • • Composable: merge → re-resolve a single lock
  • • State persisted under ~/.agentgem

AgentGem • System architecture • generated from a codebase review