The Ecosystem

8gent OS — 8gentos.com Parent site. Paid product. Revenue engine.

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

8gent — 8gent.app Consumer GUI client for the OS.

8gent World — 8gent.world Ecosystem story, docs, 14 presentation decks.

8gent Games — 8gent.games Agent simulation playground.

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

Quick Start

npm install -g @podjamz/8gent-code
8gent

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

From source (contributors)

git clone https://github.com/PodJamz/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 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 (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 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/ 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 | |------|------| | 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 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/
  eight/         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

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 | |:---------|:-----| | 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