![\"8gent](\".github/assets/readme-header.png\")
\n\n \n
\n The kernel of the 8gent ecosystem.
\n Open source autonomous coding agent powered by local LLMs or free cloud models.
\n No API keys. No usage caps. No cloud dependency.\n
\n ![\"Jr](\"https://img.shields.io/badge/Jr-Live-2D8A56?style=for-the-badge&labelColor=1A1612\"){kind=icon}
![\"Code](\"https://img.shields.io/badge/Code-Open_Source-2D8A56?style=for-the-badge&labelColor=1A1612\"){kind=icon}
![\"OS](\"https://img.shields.io/badge/OS-In_Dev-E8610A?style=for-the-badge&labelColor=1A1612\"){kind=icon}
![\"World](\"https://img.shields.io/badge/World-In_Dev-E8610A?style=for-the-badge&labelColor=1A1612\"){kind=icon}
![\"Games](\"https://img.shields.io/badge/Games-In_Dev-E8610A?style=for-the-badge&labelColor=1A1612\"){kind=icon}
\n ![\"Apache](\"https://img.shields.io/badge/License-Apache_2.0-E8610A?style=for-the-badge&labelColor=1A1612\"){kind=icon}
![\"v0.17.0](\"https://img.shields.io/badge/version-0.17.0-2D8A56?style=for-the-badge&labelColor=1A1612\"){kind=icon}
![\"Daemon\"](\"https://img.shields.io/badge/daemon-Fly.io_Amsterdam-E8610A?style=for-the-badge&labelColor=1A1612\"){kind=icon}
2 shipped · 5 in development · 1 constitution
\n\n| \n\n**8gent Code** -[8gent.dev](https://8gent.dev) \nOpen source developer agent. Free on-ramp. Shipped. (this repo)\n\n**8gent Jr** -[8gentjr.com](https://8gentjr.com) \nAI assistant for kids. Accessibility first. Free forever. Shipped.\n\n | \n\n\n**8gent OS** -[8gentos.com](https://8gentos.com) \nPaid personal OS. In development.\n\n**8gent** -[8gent.app](https://8gent.app) \nSingle pane of glass dashboard. In development.\n\n | \n\n\n**8gent World** -[8gent.world](https://8gent.world) \nEcosystem story, docs, presentation decks. In development.\n\n**8gent Games** -[8gent.games](https://8gent.games) \nAgent simulation playground. In development.\n\n | \n
\n Constitution · Inspirations\n
\n\n| \n\n**Local-first, free by default** \nRuns entirely on your machine. Cloud models (OpenRouter free tier) are opt-in. No telemetry, no API keys to start.\n\n \n\n**Model-agnostic** \nAdaptive 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.\n\n \n\n**Eight kernel** \nPersistent daemon deployed on Fly.io Amsterdam (eight-vessel.fly.dev). WebSocket protocol, 4-strategy retry loop, session persistence across reconnections.\n\n \n\n**NemoClaw policy engine** \nYAML-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.\n\n | \n\n\n**8 Powers** \nMemory, parallel worktrees, NemoClaw policy, self-evolution, self-healing, entrepreneurship, AST blast radius, and browser access. Not plugins. Built-in.\n\n \n\n**HyperAgent meta-improvement** \nMetacognitive self-modification. The agent can improve how it improves -meta-config is editable while the evaluation protocol stays human-controlled.\n\n \n\n**AutoResearch** \nOvernight improvement loops (Karpathy-style). Runs benchmarks, mutates system prompts, re-tests. Meta-optimizer also tunes few-shots, model routing, and grading weights.\n\n \n\n**Voice** \nmacOS 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.\n\n\n\n**AST-first navigation** · **Multi-agent orchestration** · **Telegram portal**\n\n | \n
| \n\n**Hands** (motor) \n packages/hands/\nmacOS desktop driver: click, type, scroll, drag, hover, press, screenshot, windows, clipboard. Backed by `cliclick` + `osascript` fallback. Used by the `desktop_*` agent tools and the `run_computer_task` CUA loop.\n\n | \n\n\n**Eyes** (perception) \n packages/eyes/\nCapture, annotate, locate, describe, wait_for, diff, observe. Bundled native AX bridge at `~/.8gent/bin/8gent-ax-bridge` (Swift, no Homebrew dep). Real perceptual diff (pngjs). Two-phase VisionProvider: resolve provider id, then tier-check, then call. Agent tools `eyes_see` / `eyes_find` / `eyes_describe` / `eyes_wait_for`. Headless `apps/8gent-eyes/` CLI.\n\n | \n\n\n**Handeyes** (sensorimotor coordination) \n packages/handeyes/\nThird body-part. Selectively engaged when the agent is observably stuck on a hands-only or eyes-only flow. 5 compound tools (`handeyes_locate_and_click`, `handeyes_click_and_verify`, `handeyes_type_and_confirm`, `handeyes_engage_struggle_mode`, `handeyes_exit_struggle_mode`). 4 trigger heuristics (3 live in v0.17, trigger 4 from DoomLoopDetector emitter wired pending shared accessor).\n\n | \n
| \n\n**Memory** \n packages/memory/\nDual-layer episodic + semantic memory, SQLite + FTS5, Ollama embeddings, procedural memory, health monitoring, contradiction detection, consolidation, lease-based job queue\n\n | \n\n\n**Worktree** \n packages/orchestration/\nMulti-agent parallel execution via git worktrees, max 4 concurrent, filesystem messaging, macro-actions, delegation\n\n | \n\n\n**Policy** \n packages/permissions/\nNemoClaw YAML policy engine, 11 default rules, approval gates, headless mode, infinite mode, dangerous command detection\n\n | \n\n\n**Evolution** \n packages/self-autonomy/\nPost-session reflection, Bayesian skill confidence, HyperAgent meta-mutation, skill compounding (tasks become reusable skills), KittenTTS voice onboarding\n\n | \n
| \n\n**Healing** \n packages/validation/\nCheckpoint-verify-revert loop, git-stash atomic snapshots, failure log\n\n | \n\n\n**Entrepreneurship** \n packages/proactive/\nGitHub bounty/help-wanted scanner, capability matcher, opportunity pipeline\n\n | \n\n\n**AST** \n packages/ast-index/\nBlast radius engine, import dependency graph, test file mapping, change impact estimation\n\n | \n\n\n**Browser** \n packages/tools/browser/\nLightweight web access via fetch + DuckDuckGo HTML scraping, disk cache, no headless deps\n\n | \n
Execution-graded tests across professional domains. Local inference via the adaptive router (8gent / Ollama defaults).
Code compiles and runs against bun:test suites, or it fails. No string matching, no vibes.
| \n\n### Apps\n\n```\napps/\n tui/ Ink v6 terminal UI (main interface, shipped)\n clui/ Tauri 2.0 desktop overlay (scaffolded)\n dashboard/ Next.js admin panel (scaffolded)\n debugger/ Session debugger (scaffolded)\n demos/ Remotion video generation\n installer/ Interactive install wizard (shipped)\n```\n\n | \n\n\n### Packages\n\n```\npackages/\n eight/ Core agent engine (Vercel AI SDK) - shipped\n providers/ 11-provider adaptive router + failover - shipped\n memory/ SQLite + FTS5 persistent memory - shipped\n orchestration/ WorktreePool, role registry, macro actions - shipped\n permissions/ NemoClaw YAML policy engine - shipped\n self-autonomy/ Evolution, reflection, HyperAgent - shipped\n validation/ Self-healing executor - shipped\n proactive/ Business agents, opportunity scanner - shipped\n ast-index/ Blast radius engine - shipped\n tools/ 75 tools: filesystem, shell, git, browser, AST - shipped\n voice/ STT (whisper.cpp) + TTS (macOS/KittenTTS) - partial\n kernel/ RL fine-tuning pipeline (off by default) - shipped\n personality/ Brand voice, \"Infinite Gentleman\" - shipped\n pet/ Companion system + dock pet - shipped\n telegram/ Telegram bot portal - shipped\n daemon/ Persistent vessel daemon (Fly.io) - partial\n auth/ Clerk auth + GitHub integration - scaffolded\n db/ Convex reactive database - scaffolded\n control-plane/ Multi-tenant management - scaffolded\n board-plane/ Board-level vessel orchestration - scaffolded\n board-vessel/ Autonomous AI officer blueprint - scaffolded\n```\n\n | \n
benchmarks/ execution-graded benchmarks + autoresearch · bin/ CLI entry points · docs/ architecture docs\n\n| \n\n### Just shipped (v0.17.0)\n\n**Body-parts taxonomy** - the agent now sees and selectively coordinates eyes+hands when stuck.\n\n- Eyes: spec + bundled native AX bridge + perceptual diff + vision-router + agent tools + CLI\n- Handeyes: third body-part (#2526), 5 compound tools, 3 of 4 triggers live\n- DoomLoopDetector EventEmitter (#2527, RFC Option A)\n\n**v0.14 hardened kernel** (folded into this release):\n\n- DoomLoopDetector / SecretScanner / PathGuard / BashParser\n- ToolResultCache / ArtifactStore / TwoStageCompactor\n- PreToolRouter / TurnJournal\n\n | \n\n\n### Next\n\n- **Trigger 4 wire** (#2537) - one line in agent.ts when shared DoomLoopDetector accessor lands\n- **`apps/8gent-handeyes` CLI** (#2538) - headless parity per dispatch-everywhere rule\n- **Mid-click re-locate** (#2539) - auto-invoke the wired hook in hands-queue\n- **BashParser runtime wiring** (#2484) - wire `gateBashCommand` into the spawn site\n- **TUI bug fixes** - slash registry race (#2473), frame buffer corruption (#2474)\n- **Per-tab model routing** - each agent tab gets its own provider/model\n- **Voice hardening** - KittenTTS integration, full-duplex Moshi backend stabilization\n- **Keychain test fix** (#2510) - clear the perpetual Validate-red blocker\n\n | \n\n\n### Later / under evaluation\n\n- **Virtuoso + OPAL eval** (#2486) - federated knowledge-graph substrate for Lotus / 8gentOS data spaces. 1-week scoped spike, decision criteria filed.\n- **MCP server support** - expose 8gent tools as MCP servers for external agent consumption\n- **Extension system** - ExtensionCrafter for autonomous source-to-extension generation\n- [HyperAgent meta-improvement loop](docs/HYPERAGENT-SPEC.md)\n- [Kernel fine-tuning pipeline](docs/KERNEL-FINETUNING.md) activation\n- Desktop client (Swift AppKit, `apps/lil-eight/`)\n- Multi-tenant control plane via 8GI gateway\n- Personal LoRA from session training pairs\n\n | \n
| \n\n| Command | What it does |\n|:--------|:-------------|\n| `/voice chat` | Start voice conversation mode |\n| `/model | \n\n\n| Command | What it does |\n|:--------|:-------------|\n| `/history` | Browse past sessions |\n| `/resume` | Resume a previous session |\n| `/compact` | Compact current session |\n| `/github` | GitHub integration |\n| `/auth status` | Check auth state |\n| `/debug` | Session inspector |\n| `/deploy | \n
| \n\n- [Hermes by ArcadeAI](https://github.com/ArcadeAI/hermes) -persistent memory and self-evolution patterns\n- [CashClaw](https://github.com/nicepkg/CashClaw) -autonomous work discovery and value generation\n- NemoClaw -policy-driven governance and approval gate architecture\n- HyperAgents (Meta FAIR, March 2026) -metacognitive self-modification\n- Hypothesis Loop -atomic commit-verify-revert development cycle\n\n | \n\n\n- Blast Radius Engine -AST-based change impact estimation\n- Claude Code -worktree isolation pattern for parallel agent execution\n- Karpathy's autoresearch methodology -iterative prompt mutation and meta-optimization\n- [SoulSpec](https://github.com/OpenSoul-org/SoulSpec) -agent persona standard\n- [usecomputer](https://github.com/remorses/usecomputer) -cross-platform desktop automation via native Zig N-API\n- [Quitty](https://github.com/iad1tya/Quitty) -process management and resource conservation UX\n\n | \n
\n Apache 2.0 - 8GI Foundation, Founder and Visionary\n
\n\n\n X / Twitter · \n GitHub · \n 8gent.dev · \n 8gent.world\n
\n\n\n Your OS. Your rules. Your AI.\n
\n","readmeFilename":"README.md"}