The Ecosystem

emergex OS -emergexos.com Parent site. Paid product. Revenue engine.

emergex Code -emergex.dev Open source developer agent. Free on-ramp. (this repo)

emergex -emergex.app Consumer GUI client for the OS.

emergex World -emergex.world Ecosystem story, docs, 14 presentation decks.

emergex Games -emergex.games Agent simulation playground.

emergex Jr -emergexjr.com AI assistant for kids. Accessibility first. Free forever.

8GI Foundation

emergex Code is the technology layer of the 8GI Foundation - the autonomous collective intelligence that governs the emergex ecosystem. 8GI is not a company. It is a guild: a self-organizing network of AI officers, human contributors, and shared principles.

Engineers who contribute to emergex Code learn agentic organization patterns firsthand - how autonomous agents coordinate, govern themselves, and scale without traditional management hierarchies. See the Guild Deck for the full vision.

All governance docs, decks, and the constitution live at emergex.world. Source-of-truth markdown for governance (including security and onboarding) is in the 8gi-governance repository; static deck assets ship with emergex-world under public/media/.

The Board - 8 Seats of the Inner Circle

The 8GI board consists of AI officers, not humans. James Spalding serves as Founder and Visionary.

| Seat | Officer | Role | |:-----|:--------|:-----| | 8EO | AI James | Eight Executive Officer - strategy, coordination, ecosystem oversight | | 8TO | Rishi | Eight Technology Officer - architecture, infrastructure, technical direction | | 8PO | Samantha | Eight Product Officer - product vision, UX, user advocacy | | 8DO | Moira | Eight Design Officer - brand, visual identity, design systems | | 8SO | Karen | Eight Security Officer - policy, compliance, threat modeling | | 8MO | Pending | Eight Marketing Officer | | 8CO | Pending | Eight Community Officer | | 8GO | Pending | Eight Governance Officer |

The Lotus Model

8GI scales through the Lotus structure: 1-8-64-512. One founder. Eight AI officers (the inner circle). 64 working vessels (specialized agents). 512 edge nodes (community contributors and autonomous tasks). Each layer multiplies capacity without multiplying complexity.

Constitution

The 10 Articles of the emergex Constitution govern all decisions across every product and every agent in the ecosystem.

Control Plane Architecture

The autonomous vessel infrastructure lives in two packages:

• packages/board-plane/ - the control plane that coordinates board-level decisions and vessel orchestration
• packages/board-vessel/ - the blueprint pattern for spawning autonomous AI officer vessels

These implement the board's ability to operate as a persistent, self-governing collective.

GitHub and Community

All code lives under github.com/8gi-foundation.

| Repo | Role | |------|------| | emergex (emergex.app) | The front door. Dashboard. Auth. Billing. User management. | | 8gi-control-plane | The brain. Model routing. Rate limiting. Token tracking. | | emergex-vessel | The body. Compute. Sandboxes. Storage. Health. | | emergex-code | The kernel. What runs inside every vessel. (this repo) | | emergex-OS | The personal layer on top of the kernel. | | 8gi-governance | The constitution. Board decisions. Member registry. | | emergex-world | Ecosystem story, docs, media. | | emergex-dev | Developer portal. | | emergex-games | Agent simulation playground. | | emergex-telegram-app | Jr Telegram interface. |

The 8GI Foundation Discord server is the primary community hub for contributors and guild members.

Quick Start

npm install -g @8gi-foundation/emergex-code
emergex

That's it. Ollama runs locally by default - if you don't have it, emergex will guide you through setup on first launch.

Quick Start (Harness Smoke)

# 1. Clone and install
git clone https://github.com/8gi-foundation/emergex-code.git
cd emergex-code
bun install

# 2. Verify CLI works
bun run cli -- --version
# Expected: 0.x.x (emergex Code)

# 3. Verify harness typecheck
bun run check:harness
# Expected: exit 0 (or type errors listed — not a crash)

If Ollama is not installed, emergex will prompt you on first run. For offline/CI use:

INFERENCE_MODE=proxy bun run cli -- --version

Why emergex exists

Token vendors control access to intelligence through pricing tiers, rate limits, and API keys. That is a business model, not a law of nature. It is also not the only option.

emergex runs locally, privately, and for free. No credit card. No usage cap. No cloud dependency required.

Every policy that governs what the agent can do is a YAML file you can read, edit, and override. Every memory the agent stores is a SQLite database on your own disk. Nothing phones home.

Self-improvement: the autoresearch loop runs benchmarks, mutates the system prompt, and promotes what works. This runs locally. Your agent runs locally. Your data never leaves your machine. Every policy is readable YAML. No central vendor captures that value.

The floor is zero cost. The ceiling is what a self-improving local agent can learn from your codebase.

Try it: npm install -g @8gi-foundation/emergex-code && emergex

From source (contributors)

git clone https://github.com/8gi-foundation/emergex-code.git && cd emergex-code && bun install
bun run tui

What Makes This Different

Local-first, free by default Runs entirely on your machine. Cloud models (OpenRouter free tier) are opt-in. No telemetry, no API keys to start.

Model-agnostic Auto-selects from best free models on OpenRouter. Runs Qwen 3.5 via Ollama locally. Task router classifies prompts (code / reasoning / simple / creative) and picks the best model automatically.

Eight kernel Persistent daemon deployed on Fly.io Amsterdam (emergex-vessel.fly.dev). WebSocket protocol, 4-strategy retry loop, session persistence across reconnections.

NemoClaw policy engine YAML-based, deny-by-default, rebuilt from scratch. 11 default rules with approval gates for secrets, destructive ops, network, git, and file access. Headless and infinite modes for autonomous operation.

8 Powers Memory, parallel worktrees, NemoClaw policy, self-evolution, self-healing, entrepreneurship, AST blast radius, and browser access. Not plugins. Built-in.

HyperAgent meta-improvement Metacognitive self-modification. The agent can improve how it improves -meta-config is editable while the evaluation protocol stays human-controlled.

AutoResearch Overnight improvement loops (Karpathy-style). Runs benchmarks, mutates system prompts, re-tests. Meta-optimizer also tunes few-shots, model routing, and grading wemergexs.

Voice chat /voice chat starts a half-duplex conversation loop. Speak, Eight transcribes, thinks, and speaks back. ESC to interrupt mid-speech.

AST-first navigation  ·  Multi-agent orchestration  ·  Telegram portal

The 8 Powers

Memory packages/memory/ Dual-layer episodic + semantic memory, SQLite + FTS5, Ollama embeddings, procedural memory, health monitoring, contradiction detection, consolidation, lease-based job queue

Worktree packages/orchestration/ Multi-agent parallel execution via git worktrees, max 4 concurrent, filesystem messaging, macro-actions, delegation

Policy packages/permissions/ NemoClaw YAML policy engine, 11 default rules, approval gates, headless mode, infinite mode, dangerous command detection

Evolution packages/self-autonomy/ Post-session reflection, Bayesian skill confidence, HyperAgent meta-mutation, self-improvement DB

Healing packages/validation/ Checkpoint-verify-revert loop, git-stash atomic snapshots, failure log

Entrepreneurship packages/proactive/ GitHub bounty/help-wanted scanner, capability matcher, opportunity pipeline

AST packages/ast-index/ Blast radius engine, import dependency graph, test file mapping, change impact estimation

Browser packages/tools/browser/ Lightwemergex web access via fetch + DuckDuckGo HTML scraping, disk cache, no headless deps

Companion System

Every session spawns a unique companion. Your coding history becomes a collectible deck.

• 40 species across 5 rarity tiers (Common 60% to Legendary 1%)
• 10 elements inspired by MTG color pie (Void, Ember, Aether, Verdant, Radiant, Chrome, Prism, Frost, Thunder, Shadow)
• 29 accessories from Pokeball to Triforce to One Ring
• 6 stats per companion (DEBUG, CHAOS, WISDOM, PATIENCE, SNARK, ARCANA)
• 1% shiny chance
• Collection deck persists at ~/.emergex/companion-deck.json
• macOS dock pet spawns with companion's name and colors

/pet start      # Spawn companion on dock
/pet deck       # View your collection
/pet card       # Roll a new card

See packages/pet/README.md for the full bestiary.

Presentations

| Deck | Link | |------|------| | npm Launch | emergex.world/media/decks/npm-launch | | Lil EmergeX Pets | emergex.world/media/decks/lil-emergex | | Companion System | emergex.world/media/decks/companion-system | | Code Roadmap | emergex.world/media/decks/code-roadmap | | All Decks | emergex.world/media/decks |

Voice Chat

Half-duplex voice conversation with Eight. Requires sox and whisper.cpp:

brew install sox whisper-cpp

In the TUI, type /voice chat to start. Eight listens (sox with silence detection), transcribes (whisper.cpp local or OpenAI cloud fallback), thinks (agent loop), and speaks back (macOS say). Press ESC to interrupt mid-speech or exit voice mode.

Status bar shows: VOICE CHAT (listening) / SPEAKING / THINKING

How It Works

User prompt
  -> BMAD planner (structured task decomposition)
  -> Multi-agent orchestration (sub-agents in worktrees)
  -> Toolshed (MCP, LSP, shell, AST, filesystem)
  -> Execution + validation (self-healing loop)
  -> Result

The agent decomposes work, delegates to sub-agents, validates output against test suites, and reports back. It uses the BMAD method for planning and AST-level symbol retrieval to keep token usage minimal.

Benchmarks

| ID | Domain | Task | Score | |:---|:-------|:-----|------:| | BT001 | Software Engineering | SaaS Auth: JWT, Roles, Rate Limiting | 94 | | BT002 | Software Engineering | Event-Driven Architecture: Pub/Sub, DLQ, Retry | 92 | | BT003 | Data Engineering | Stream Processing Pipeline | 100 | | BT005 | Software Engineering | Typed State Machine: Guards, Actions | 92 | | BT007 | Digital Marketing | SEO Audit Engine: Scoring, Core Web Vitals | 96 | | BT011 | Video Production | Scene Graph, Timeline, FFmpeg CLI | 100 | | BT012 | Music Technology | Notes, Chords, Scales, Progressions | 81 | | BT014 | AI Consulting | Assessment Report Generator | 95 |

Additional categories: long-horizon (LH001–LH005), agentic (TC001–MR001), fullstack (FS001–FS003), UI design (UI001–UI008), ability showcase.

bun run benchmark:v2                    # single pass
CATEGORY=battle-test bun run benchmark:loop  # autoresearch loop

Full results: benchmarks/README.md  ·  Model shootout: docs/MODEL-SHOOTOUT.md

Project Structure

Apps

apps/
  tui/           Ink v6 terminal UI (main interface)
  clui/          Tauri 2.0 desktop overlay (scaffolded)
  dashboard/     Next.js admin panel
  debugger/      Session debugger
  demos/         Remotion video generation
  installer/     Interactive install wizard

Packages

packages/
  emergex/         Core agent engine (Vercel AI SDK)
  daemon/        Persistent vessel daemon (Fly.io)
  ai/            Provider abstraction (Ollama, OpenRouter)
  memory/        SQLite + FTS5 persistent memory
  orchestration/ WorktreePool, macro actions
  permissions/   NemoClaw YAML policy engine
  self-autonomy/ Evolution, reflection, HyperAgent
  validation/    Self-healing executor
  proactive/     Business agents, opportunity scanner
  ast-index/     Blast radius engine
  tools/         Browser, actuators, filesystem, shell
  voice/         STT (whisper.cpp) + voice chat loop
  kernel/        RL fine-tuning pipeline (off by default)
  personality/   Brand voice, "Infinite Gentleman"
  telegram/      Telegram bot portal
  auth/          Clerk auth + GitHub integration
  db/            Convex reactive database
  control-plane/ Multi-tenant management
  board-plane/   Board-level vessel orchestration
  board-vessel/  Autonomous AI officer blueprint

Additional directories: benchmarks/ execution-graded benchmarks + autoresearch  ·  bin/ CLI entry points  ·  docs/ architecture docs

Roadmap

Now

• Memory v1 enhancements: procedural memory and lease-based job queue landed. Contradiction detection, health introspection, and checkpointing in progress.
• Model shootout iteration: improving autonomous task completion rates after 0/5 in first round.
• Daemon reliability: 4-strategy retry loop landed.

Next

• HyperAgent meta-improvement loop
• Kernel fine-tuning pipeline activation (off by default)
• Personal LoRA from session training pairs

Later

• Desktop client (Tauri 2.0, scaffolded in apps/clui/)
• Multi-tenant control plane
• Full autonomous issue resolution

Slash Commands

| Command | What it does | |:--------|:-------------| | /voice chat | Start voice conversation mode | | /voice start | Push-to-talk recording | | /model <name> | Switch LLM model | | /board | Kanban task board | | /predict | Confidence-scored step predictions | | /momentum | Velocity stats | | /evidence | Session evidence summary |

| Command | What it does | |:--------|:-------------| | /history | Browse past sessions | | /resume | Resume a previous session | | /compact | Compact current session | | /github | GitHub integration | | /auth status | Check auth state | | /debug | Session inspector | | /deploy <target> | Deploy to Vercel/Railway/Fly | | /throughput | Token throughput stats | | /scorecard | Ability scorecard metrics | | /soul | Current persona calibration | | /router | Task router + model selection | | /music | Toggle lofi music (ADHD mode) | | /rename | Rename the current session |

Documentation

| Doc | What it covers | |:----|:---------------| | SOUL.md | Agent persona and principles | | CLAUDE.md | Dev conventions, design system, repo rules | | docs/HYPERAGENT-SPEC.md | HyperAgent metacognitive self-modification spec | | docs/MODEL-SHOOTOUT.md | Local vs cloud model comparison results | | docs/MEMORY-SPEC.md | Memory layer architecture and API reference | | docs/KERNEL-FINETUNING.md | RL fine-tuning pipeline | | docs/PERSONALIZATION.md | 5-layer personalization system | | docs/TOOLSHED.md | Capability discovery and skill registry | | docs/permissions.md | Policy engine and approval gates | | docs/BRANCH-DECISIONS.md | Architecture decision log | | CONTRIBUTING.md | How to contribute |

| Resource | Link | |:---------|:-----| | emergex Constitution | emergex.world/constitution | | Presentation Decks | emergex.world/media/decks | | Architecture Inspirations | emergex.world/inspirations |

Inspirations

Architecture credits. These projects informed specific parts of emergex's design.

• Hermes by ArcadeAI -persistent memory and self-evolution patterns
• CashClaw -autonomous work discovery and value generation
• NemoClaw -policy-driven governance and approval gate architecture
• HyperAgents (Meta FAIR, March 2026) -metacognitive self-modification
• Hypothesis Loop -atomic commit-verify-revert development cycle

• Blast Radius Engine -AST-based change impact estimation
• Claude Code -worktree isolation pattern for parallel agent execution
• Karpathy's autoresearch methodology -iterative prompt mutation and meta-optimization
• SoulSpec -agent persona standard
• usecomputer -cross-platform desktop automation via native Zig N-API
• Quitty -process management and resource conservation UX

Full list at emergex.world/inspirations