The Ecosystem

8gent Code -8gent.dev Open source developer agent. Free on-ramp. Shipped. (this repo)

8gent Jr -8gentjr.com AI assistant for kids. Accessibility first. Free forever. Shipped.

8gent OS -8gentos.com Paid personal OS. In development.

8gent -8gent.app Single pane of glass dashboard. In development.

8gent World -8gent.world Ecosystem story, docs, presentation decks. In development.

8gent Games -8gent.games Agent simulation playground. In development.

8GI Foundation

8gent Code is the technology layer of the 8GI Foundation - the autonomous collective intelligence that governs the 8gent 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 8gent 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 8gent.world. Source-of-truth markdown for governance (including security and onboarding) is in the 8gi-governance repository; static deck assets ship with 8gent-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 8gent 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 | |------|------| | 8gent (8gent.app) | The front door. Dashboard. Auth. Billing. User management. | | 8gi-control-plane | The brain. Model routing. Rate limiting. Token tracking. | | 8gent-vessel | The body. Compute. Sandboxes. Storage. Health. | | 8gent-code | The kernel. What runs inside every vessel. (this repo) | | 8gent-OS | The personal layer on top of the kernel. | | 8gi-governance | The constitution. Board decisions. Member registry. | | 8gent-world | Ecosystem story, docs, media. | | 8gent-dev | Developer portal. | | 8gent-games | Agent simulation playground. | | 8gent-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/8gent-code
8gent

That's it. 8gent uses an adaptive 11-provider router. Default active provider is 8gent local (model eight-1.0-q3:14b) with ollama also enabled by default. Cloud providers (OpenRouter, Groq, OpenAI, Anthropic, Mistral, Together, Fireworks, Replicate, Grok) are opt-in via API key. Failover chain: local 8gent, then local Qwen, then OpenRouter free tier.

Quick Start (from source)

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

If no local model is available, 8gent will guide you through interactive onboarding on first run. The adaptive provider router tries local 8gent, then Ollama, then OpenRouter free tier.

Why 8gent 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.

8gent 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/8gent-code && 8gent

From source (contributors)

git clone https://github.com/8gi-foundation/8gent-code.git && cd 8gent-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 Adaptive 11-provider router: 8gent local, Ollama, OpenRouter, Groq, OpenAI, Anthropic, Mistral, Together, Fireworks, Replicate, Grok. Everything except 8gent/ollama is opt-in via API key. Task router classifies prompts (code, reasoning, simple, creative) and picks the best model automatically.

Eight kernel Persistent daemon deployed on Fly.io Amsterdam (eight-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 weights.

Voice macOS TTS voices (Moira, Daniel, Samantha, Karen, Rishi) with KittenTTS neural voices as optional upgrade. Full-duplex Moshi backend scaffolded for Apple Silicon. /voice chat to start.

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, skill compounding (tasks become reusable skills), KittenTTS voice onboarding

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/ Lightweight 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 ~/.8gent/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 | |------|------| | Feature Set Audit | 8gent.world/media/decks/feature-set | | npm Launch | 8gent.world/media/decks/npm-launch | | Lil Eight Pets | 8gent.world/media/decks/lil-eight | | Companion System | 8gent.world/media/decks/companion-system | | Code Roadmap | 8gent.world/media/decks/code-roadmap | | All Decks | 8gent.world/media/decks |

Voice

Half-duplex (/voice chat) - listen, transcribe, think, speak, repeat. Requires sox and whisper.cpp:

brew install sox whisper-cpp

TTS output - macOS say voices (Moira, Daniel, Samantha, Karen, Rishi) work out of the box. KittenTTS neural voices (8 voices, free, local) are available as an optional upgrade - offered during onboarding.

Full-duplex (experimental) - simultaneous listen and speak via Moshi (Kyutai) on Apple Silicon. Backend code exists in packages/voice/backends/moshi-mlx.ts but requires manual setup (pip install moshi).

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, shipped)
  clui/          Tauri 2.0 desktop overlay (scaffolded)
  dashboard/     Next.js admin panel (scaffolded)
  debugger/      Session debugger (scaffolded)
  demos/         Remotion video generation
  installer/     Interactive install wizard (shipped)

Packages

packages/
  eight/         Core agent engine (Vercel AI SDK) - shipped
  providers/     11-provider adaptive router + failover - shipped
  memory/        SQLite + FTS5 persistent memory - shipped
  orchestration/ WorktreePool, role registry, macro actions - shipped
  permissions/   NemoClaw YAML policy engine - shipped
  self-autonomy/ Evolution, reflection, HyperAgent - shipped
  validation/    Self-healing executor - shipped
  proactive/     Business agents, opportunity scanner - shipped
  ast-index/     Blast radius engine - shipped
  tools/         75 tools: filesystem, shell, git, browser, AST - shipped
  voice/         STT (whisper.cpp) + TTS (macOS/KittenTTS) - partial
  kernel/        RL fine-tuning pipeline (off by default) - shipped
  personality/   Brand voice, "Infinite Gentleman" - shipped
  pet/           Companion system + dock pet - shipped
  telegram/      Telegram bot portal - shipped
  daemon/        Persistent vessel daemon (Fly.io) - partial
  auth/          Clerk auth + GitHub integration - scaffolded
  db/            Convex reactive database - scaffolded
  control-plane/ Multi-tenant management - scaffolded
  board-plane/   Board-level vessel orchestration - scaffolded
  board-vessel/  Autonomous AI officer blueprint - scaffolded

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

Roadmap

Now

• Per-tab model routing - each agent tab (Orchestrator/Engineer/QA) gets its own provider and model, with Apple Foundation as lightweight chat option
• Documentation sweep - aligning all docs, README, and live sites with audited feature set
• PR cleanup - merging 12+ pending PRs with verification
• Voice hardening - KittenTTS integration, full-duplex Moshi backend stabilization

Next

• MCP server support - expose 8gent tools as MCP servers for external agent consumption
• Context window compaction - smarter compression beyond token threshold
• Extension system - ExtensionCrafter for autonomous source-to-extension generation
• HyperAgent meta-improvement loop
• Kernel fine-tuning pipeline activation

Later

• Desktop client (Swift AppKit, apps/lil-eight/)
• Multi-tenant control plane via 8GI gateway
• Full autonomous issue resolution
• Personal LoRA from session training pairs
• Dead code cleanup (music/DJ package)

Slash Commands

| Command | What it does | |:--------|:-------------| | /voice chat | Start voice conversation mode | | /model <name> | Switch LLM model | | /provider <name> | Switch LLM provider | | /kanban | Kanban task board | | /predict | Confidence-scored step predictions | | /evidence | Session evidence summary | | /router | Task router + model selection |

| 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 | | /music | Toggle lofi music (ADHD mode) | | /pet | Companion dock pet | | /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 | |:---------|:-----| | 8gent Constitution | 8gent.world/constitution | | Presentation Decks | 8gent.world/media/decks | | Architecture Inspirations | 8gent.world/inspirations |

Inspirations

Architecture credits. These projects informed specific parts of 8gent'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 8gent.world/inspirations