How mrinalsunny/gemiflow works
1. What this repo is
GemiFlow is a monorepo for a multi-agent CLI platform built around Gemini CLI, with a large v3 rewrite and a compatibility/plugin layer around it. The main runtime is TypeScript/Node, with a few Rust/WASM components for performance-sensitive and trust-sensitive paths.
2. Top-level architectural split
The repo has three big surfaces:
- Core platform/runtime in v3/ and root CLI entrypoints.
- Plugin ecosystem in plugins/, plugin/, .claude-plugin/, and generated .gemiflow/ assets.
- Operational assets in docs/, verification/, scripts/, tests/, github/ workflows, and benchmark outputs.
3. Primary execution path
User commands enter through the CLI (bin/cli.js, v3/@gemiflow/cli/src/commands/*) or through MCP (v3/mcp, v3/@gemiflow/mcp, shared MCP server code). Those entrypoints route into application services, which then call memory, swarm, security, plugin, or provider subsystems depending on the task.
4. Orchestration and control plane
The orchestration layer lives in packages like v3/@gemiflow/shared, v3/@gemiflow/swarm, v3/@gemiflow/hooks, v3/@gemiflow/integration, and v3/@gemiflow/cli. This layer handles:
- task dispatch
- agent spawning and lifecycle
- hooks and daemons
- statusline/monitoring
- worker pools and background automation
It is the “brainstem” that keeps agent activity coordinated.
5. Agent and swarm subsystem
v3/@gemiflow/swarm provides agent/task coordination, topology management, and consensus variants such as Raft, gossip, and Byzantine-style flows. Related packages in the root and v3/plugins/* expand this with specialized roles, worker dispatch, queen/coordinator patterns, and federated transport.
6. Memory, retrieval, and learning
Memory is a major subsystem, centered in v3/@gemiflow/memory, v3/@gemiflow/embeddings, v3/@gemiflow/neural, v3/@gemiflow/rag-memory, and related packages. The flow is roughly:
- capture task/session artifacts
- embed and index them
- retrieve via hybrid search / vector search / graph reasoning
- feed results back into planning and routing
This is what enables cross-session recall and self-improvement.
7. Guidance and governance layer
v3/@gemiflow/guidance acts like a policy/control plane for capability gating, trust, proof, uncertainty, and memory writes. It also includes a WASM kernel (v3/@gemiflow/guidance/wasm-kernel) used for deterministic enforcement and scoring. In architecture terms, this sits between agent intent and tool execution.
8. Security and trust boundaries
Security is not a sidecar here; it is a first-class boundary. v3/@gemiflow/security, plugins/ruflo-aidefence, v3/plugins/prime-radiant, and federation-related packages enforce:
- input validation
- path/tool output guardrails
- plugin integrity checks
- authorization propagation
- PII filtering and trust scoring
The federation stack is explicitly zero-trust and treats remote peers as untrusted until verified.
9. Plugin architecture
The repo is built to be extended by plugins with a common shape: metadata, agents, commands, skills, MCP tools, and tests. Many packages under plugins/ and v3/plugins/ follow this pattern, exposing domain-specific capability bundles such as browser automation, cost tracking, workflows, neural trading, DDD, docs, and federation. The plugin registry/discovery code lives in v3/@gemiflow/plugins, v3/@gemiflow/cli/src/plugins, and shared plugin interfaces.
10. External integration points
Material external dependencies include:
- LLM providers: Gemini, OpenAI, Anthropic, Cohere, Ollama, OpenRouter/compatible endpoints
- Storage/backends: SQLite/sqljs, AgentDB/RVF, Mongo in the web UI, GCS, IPFS
- Collaboration surfaces: GitHub APIs/workflows, MCP servers, federation peers
- Cloud/runtime: Supabase for the goal UI, Cloud Run/containers for some deployments
These are plugged in through provider, storage, transport, and bridge packages rather than being hardwired into core logic.
11. Web and product surfaces
There are separate product UIs outside the CLI:
- v3/goal_ui for the GOAP planner and live agent dashboard
- the hosted “flo.ruv.io” chat UI described in the README
These are not the main runtime, but they consume the same orchestration and tool concepts as the CLI.
12. Build, test, and verification pipeline
The repo is heavily instrumented with CI, smoke tests, benchmarks, and verification artifacts. Key boundaries here are:
- package-level Vitest suites
- repo-wide smoke/audit scripts
- GitHub Actions workflows
- verification manifests and witness data under verification/
- benchmark corpora/results under docs/benchmarks and v3/docs/benchmarks
This indicates the architecture is optimized not just for features, but for reproducibility and trust.
13. How to draw the main diagram
A useful diagram would show:
- Clients: Gemini CLI, MCP clients, hosted UIs
- Control plane: CLI/MCP server, hooks, swarm/orchestrator, guidance/security
- Capability planes: agents, plugins, workflows, federation, background workers
- State plane: memory, embeddings, neural, RVF/AgentDB, event/ledger stores
- External systems: LLM providers, GitHub, storage, cloud services, peer nodes
The most important arrows are: user intent → orchestration → agent/tool execution → memory/learning → routing/planning feedback.
14. Main architectural takeaway
This repo is less “one app” and more a platform for composing agentic systems. The stable seams are the control plane, memory/learning plane, security/trust boundary, and the plugin/MCP extension model. Everything else is built around those seams.
Main entry points: src/index.ts CLI App · src/index.ts Security · server.ts MCP Server · src/index.ts Memory
Components 19
Clients
User-facing entrypoints and surfaces that initiate work.
- Root CLI · Top-level command entrypoint for the monorepo.
bin/cli.js - MCP Server · Shared model-context protocol server and transport layer.
v3/mcp/server.ts - Goal UI · Planner/dashboard surface for live agent workflows.
v3/goal_ui/src/App.tsx
Control Plane
CLI, MCP, orchestration, hooks, and policy enforcement.
- CLI App · Main v3 command surface and command routing.
v3/@gemiflow/cli/src/index.ts - Shared Core · Common config, event, hook, MCP, plugin, and resilience primitives.
v3/@gemiflow/shared/src/index.ts - Hooks · Hook execution, daemons, statusline, and worker coordination.
v3/@gemiflow/hooks/src/index.ts - Plugin Registry · Plugin discovery, loading, trust, and package registry.
v3/@gemiflow/plugins/src/index.ts
Capabilities
Agentic subsystems and extension packages that perform work.
- Swarm · Agent/task coordination, topology, and consensus orchestration.
v3/@gemiflow/swarm/src/index.ts - Integration · Bridges between the core runtime and specialized workers/providers.
v3/@gemiflow/integration/src/index.ts - Workflows · Benchmark, deployment, release, and GAIA-style workflow automation.
v3/@gemiflow/deployment/src/index.ts - Plugin Packs · Domain plugins for browser, intelligence, cost, docs, QA, IO, and more.
plugins/README.md
State & Trust
Memory, learning, provider, security, and federation boundaries.
- Memory · Persistent memory, retrieval, indexing, and migration subsystem.
v3/@gemiflow/memory/src/index.ts - Embeddings · Embedding, chunking, normalization, and cache-backed vector features.
v3/@gemiflow/embeddings/src/index.ts - Neural · Pattern learning, routing, reasoning bank, and SONA integration.
v3/@gemiflow/neural/src/index.ts - Guidance · Capability gating, proof, trust, uncertainty, and deterministic enforcement.
v3/@gemiflow/guidance/src/index.ts - Security · Input validation, path/output guardrails, integrity, and safe execution.
v3/@gemiflow/security/src/index.ts - Providers · Model-provider abstraction for Gemini, OpenAI, Anthropic, Ollama, and others.
v3/@gemiflow/providers/src/index.ts - Federation · Zero-trust peer coordination, discovery, claims, and transport for remote nodes.
v3/@gemiflow/plugin-agent-federation/src/index.ts
Ops & Verification
Build, test, benchmark, docs, and release assets.
- Verification · Smoke tests, benchmarks, witness data, and cross-platform validation artifacts.
verification/README.md
Connections 28
- Root CLI → CLI App: launches · Root CLI delegates to the v3 command application.
- Root CLI → MCP Server: starts · CLI can also bootstrap the MCP server.
- Goal UI → Shared Core: consumes · UI reuses shared event and orchestration primitives.
- CLI App → Shared Core: uses · Command handling relies on shared config, hooks, MCP, and plugins.
- CLI App → Hooks: invokes · CLI commands activate hook and daemon automation.
- CLI App → Swarm: orchestrates · Agent spawning and task routing flow through swarm coordination.
- CLI App → Memory: reads/writes · CLI routes recall and persistence into the memory subsystem.
- CLI App → Guidance: enforces · Capability and trust decisions are mediated by guidance.
- CLI App → Security: guards · Inputs, paths, tool output, and plugin integrity are checked here.
- CLI App → Providers: routes to · Model access is abstracted through provider adapters.
- CLI App → Plugin Registry: discovers · CLI discovers and loads plugin capabilities through the registry.
- CLI App → Workflows: triggers · Higher-level workflows and benchmarks are launched from commands.
- MCP Server → Shared Core: shares · MCP server uses the same core abstractions as the CLI.
- MCP Server → Security: validates · Protocol payloads and tool surfaces are validated at the boundary.
- MCP Server → Plugin Registry: exposes · Plugins register tools and prompts over MCP.
- Swarm → Integration: delegates · Swarm coordination hands work to integration workers and bridges.
- Integration → Providers: adapts · Workers and routers call into model providers through adapters.
- Integration → Memory: persists · Worker and agent activity feeds memory and retrieval.
- Memory → Embeddings: indexes · Memory uses embeddings for search and retrieval.
- Embeddings → Neural: feeds · Embedding and retrieval signals support learning and routing.
- Neural → Guidance: informs · Learning signals contribute to policy, scoring, and gating.
- Guidance → Security: delegates · Guidance enforcement depends on security primitives and trust checks.
- Plugin Packs → Plugin Registry: extends · Domain plugins are installed and discovered through the registry.
- Workflows → Verification: produces · Automated runs emit evidence, benchmarks, and witness artifacts.
- Security → Verification: audits · Security checks are corroborated by verification artifacts.
- Federation → Security: trusts through · Remote peers remain untrusted until authenticated and evaluated.
- Federation → Swarm: connects · Federation extends swarm coordination across peers.
- Federation → Memory: syncs · Claims and shared state can be propagated through memory-backed flows.