chitti: An Agentic OS Built From Scratch, Agent in Control

Overview

• ChittiOS — agentic OS built from scratch where the agent is the driver, not Unix reimplementation
• No POSIX, no libc, no ELF loader, no shell scripts — agent plans, OS provides safe primitives, determinism boundary separates stochastic model from hardware
• CI · Apache-2.0
• Demo: 5-min VirtualBox session — boot, hosted model via tool calls, WAV/H.264 playback, 117-page PDF rendered in-kernel, editor, live browser

⚠ Warnings

• Research software — unstable, interfaces/formats/behaviour change without notice, may crash or corrupt data; run in VM only
• Real hardware = wired-network console only; many drivers spec-written, never silicon-verified; no WiFi/BT/GPU/brightness

Agent & security core

• Agent as process — orchestrator runs model→tool→result loop, delegates to isolated sub-agents with strict authority subsets
• Shell is an agent — plain text is a message, /-commands drive OS; first-class sessions save/resume/fork; todos drive multi-step work
• Plan mode & permissions — /mode manual|auto|bypass|plan; /permissions gates via /configs/core/permissions.json
• CPU-only inference — architecture-dynamic GGUF loaders (Qwen hybrid, Gemma4), GGML quants, hand-written SIMD (SSE2/AVX2, NEON+SDOT), OS-managed KV cache; select at boot or /model load//model remote
• Synapse capability ABI — grammar-constrained MCP-shaped tool calls; capability+scope gate; taint gate; deterministic executor; append-only audit log
• Prompt-injection defense — provenance tags per token; destructive work justified only by untrusted content refused or requires confirmation
• Skills & installable agents — signed, progressive-disclosure markdown packages (SOUL+skills+manifest); ECDSA P-256 trust; per-agent home sandbox /agent/<id>/**

Messaging & IPC

• Channels (Telegram first) — /channel add telegram …, pairing/allowlist, poll over HTTPS Bot API; Discord/Slack backends in CHANNELS.md
• Inter-agent IPC — capability-gated byte-stream/datagram + TCP handoff, distinct from messaging channels
• MCP client — /mcp connect registers remote tools as mcp__…

Filesystem & shell UX

• Store FS — /ls, /cat, /mkdir, /cp, /mv, /rm, /touch, /glob, /grep, /pwd over Synapse path store
• Composer UX — bordered input; slash-command and @file suggestion menus; searchable /help Commands browser
• Host clipboard bridge — OSC 52 copy-out + bracketed paste

UI, media & services

• Windowed console — tmux-style chat/action split, tabbed action pane (ktrace, /top, todos, editor, media), mouse/keyboard, syntax highlighting, Geist Mono, fully themable (DESIGN.md)
• Themes — /theme set (dark/light/solarized/nord/dracula/ubuntu) or custom JSON: palette, syntax, cursor, font, wallpaper opacity
• Browser — /browse <url>: HTML/CSS (flow/flexbox), paint, forms, SVG, JS, cookies/localStorage, CORS, history; full in-kernel font stack
• Service agents & web pipeline — native network/http/server stages; content agents = data + SOUL; /agents start <name> [port]; ssh agent for version exchange
• Sound & voice — virtio-snd/HDA/USB Audio Class; /voice (VAD→STT→LLM→TTS) with ONNX models; stereo WAV/MP3; software volume
• Media — PNG/JPEG; WAV/MP3/AAC; H.264/H.265/VP9 with streaming decode, HLS VOD over network
• Networking — TCP/IP (smoltcp): DHCP, DNS, ping, loopback, HTTP(S), WebSocket, downloads to /downloads/

Platform

• Dual-arch, one codebase — x86_64 + aarch64; aarch64 runs natively on Apple Silicon under QEMU-HVF; features do not diverge
• Real drivers — UEFI/Limine/GOP; virtio/NVMe/AHCI; USB xHCI/HID + virtio-input + PL050/PS-2; PCIe/ACPI; same image for QEMU/VirtualBox/real UEFI; coverage uneven on bare metal — HARDWARE.md
• Storage & self-install — GPT/MBR/FAT/ext4; durable agent state on ext4; /install update-in-place
• Microkernel core — unforgeable capabilities, cooperative + preemptive scheduler, SMP, MMU, heap
• Apple Silicon (WIP) — boots on Mac mini M2 via m1n1; shell UI on display, model-via-initrd, native USB keyboard/mouse; DEVELOPMENT.md

Messaging channels (quick start)

• Create bot via @BotFather → copy token
• /channel add telegram home <BOT_TOKEN> pairing → /channel start home
• DM bot, note pairing code → /channel pair home <CODE>
• Chat: messages go to shell agent, replies return on Telegram
• /channel send home <chat_id> Hello · /channel reply home Got it · /channel status

Try it

• Get image: Releases — chitti-aa64.img (aarch64 UEFI) or chitti.iso (x86_64 BIOS/UEFI)
• Write to USB via balenaEtcher or dd (⚠ erases target)

  # macOS
  diskutil unmountDisk /dev/diskN
  sudo dd if=chitti-aa64.img of=/dev/rdiskN bs=4m
  # Linux
  sudo dd if=chitti-aa64.img of=/dev/sdX bs=4M status=progress conv=fsync

• Boot UEFI mode for aarch64; VirtualBox/UTM/QEMU: EFI enabled, image as disk, USB Tablet + USB keyboard; macOS: make vbox

Building & running

make test                 # in-kernel unit suite under QEMU (x86_64)
make e2e                  # end-to-end: boot kernel, drive shell over serial
make run  ARCH=aarch64    # boot natively on Apple Silicon (QEMU + HVF)
make image ARCH=x86_64    # assemble bootable ISO
make vbox                 # rebuild aarch64 image → VirtualBox
make help

• Two test layers: unit tests (cargo xtask test) + end-to-end scenarios (make e2e); new features add to both

Documentation

Doc	Contents
HARDWARE.md	Real-hardware support matrix
CHANNELS.md	Messaging channels setup
DEVELOPMENT.md	Toolchain, build/run/test, VirtualBox
DESIGN.md	Brand, palette, compositor UX
CLAUDE.md	Invariants & standing rules
CONTRIBUTING.md	Contribution workflow
SECURITY.md	Security reporting

License

• Apache 2.0 — LICENSE
• Bundled font: Geist Mono (© Vercel, SIL OFL 1.1) in assets/; model weights: respective authors' licenses