Genesis Oss

Architecture · TUI · Web UI · VS Code · Providers · Tools · Swarm · Subagents · Channels · Telegram · Discord · Slack · Setup · Vault

Genesis is a universal autonomous AI agent built in Zig. It runs in the terminal, in the browser, and inside messaging platforms — with multi-agent swarm execution when a single agent isn't enough.

https://github.com/user-attachments/assets/0bd73c66-89f8-4419-ab65-5a2cf847f1a5

Why Genesis

• Single binary, zero dependencies -- built in Zig with no runtime, no GC, no node_modules. Cross-compiles to 6 targets from one machine.
• Not just a coding agent -- a universal autonomous agent that handles DevOps, research, communication, scheduled work, and software development equally well.
• 8 LLM providers and growing, no vendor lock-in -- Anthropic, OpenAI, Google, OpenRouter, z.ai, Chutes, Moonshot, MiniMax with per-model routing and overrides. Switch providers with a flag. More providers coming soon.
• Swarm intelligence -- 5 coordination algorithms (SGF, GWC, HTA, WDG, MD) with role differentiation (architect, scout, worker, reviewer, integrator) — not just parallel tool calls.
• Runs everywhere -- TUI, web browser, Telegram, Discord, Slack, X, WebSocket server — all first-class, all feature-complete.
• Encrypted vault built in -- XChaCha20-Poly1305 + Argon2id for secrets. No plain-text API keys on disk, ever.
• MIT licensed -- fully open, fork it, embed it, ship it.

Highlights

• Interactive TUI -- streaming chat, markdown rendering, tool previews, 6 themes (dark/light), dialogs, notifications
• Web UI -- React-based browser interface with artifact viewer, file browser, inline downloads, themes
• VS Code extension -- full-featured sidebar with chat, sessions, settings, voice input, file attachments
• Channel adapters -- Telegram, Discord, Slack, X (Twitter) with bidirectional messaging; custom channels via JSON-RPC stdio protocol
• Cross-channel communication -- agents can send messages between channels via channel_send / channel_list tools
• Vision fallback -- automatic image/video analysis routing for non-vision models
• Voice input -- speech-to-text via /voice command or voice button
• Multi-provider routing -- Anthropic, z.ai, OpenAI, Google, OpenRouter, Chutes, Moonshot, MiniMax
• Swarm engine -- parallel agents coordinated by SGF, GWC, HTA, WDG, and MD
• Subagent runtime -- lightweight parallel tasks with workspace isolation
• MCP support -- dynamic external tools through Model Context Protocol
• Built-in tools -- file editing, shell, glob, web search/fetch, TODOs, scheduler, vault, channel messaging
• Secrets vault -- XChaCha20Poly1305 encrypted storage with Argon2id key derivation
• Session persistence -- provider/account-aware snapshots in ~/.genesis/sessions
• Permission system -- safe/normal/auto/yolo modes with destructive command detection
• Docker support -- single image with genesis server + web UI

What you can do with Genesis

Autonomous task execution:

• Solve complex multi-step tasks end-to-end with file I/O, shell, and web tools
• Delegate work to parallel subagents or a full swarm (architect, scout, workers)
• Schedule recurring jobs — monitoring, reports, backups, any background work

Software development:

• Build full applications from a single prompt with swarm mode
• Refactor codebases across hundreds of files with parallel subagents
• Debug, fix, test, and review code with file reading, shell, and web search
• Generate tests, documentation, configs, CI/CD pipelines

DevOps and server management:

• Run on a server as a persistent agent for infrastructure control
• Monitor services, analyze logs, respond to incidents via shell and scheduled tasks
• Manage deployments, containers, and cloud resources
• Automate Git workflows, CI/CD pipelines, and release processes
• Store and inject secrets via encrypted vault

Research and analysis:

• Web research with source aggregation and synthesis
• Analyze files, logs, datasets with shell pipelines and search
• Competitive analysis across multiple data sources

Communication:

• Manage Telegram/Discord/Slack bots that execute real tasks
• Cross-channel message routing (receive in Telegram, respond in Slack)
• Broadcast announcements to all connected channels
• Build custom channel adapters for any platform via JSON-RPC stdio protocol

Access anywhere:

• Interactive TUI in the terminal
• Web UI in the browser with full feature parity
• Messaging platforms as first-class interfaces
• Shared server mode for team access via WebSocket

Install

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/deadraid/genesis/main/packaging/install.sh | bash

npm

npm install -g @genesis-agent/cli

pip

pip install genesis-ai

Homebrew

brew install deadraid/genesis/genesis

Requirements

• Zig >= 0.16.0
• Bun (for web UI only)

Build

zig build              # build genesis binary
zig build test         # full test suite
zig build cross        # cross-compile for all platforms

Binary: zig-out/bin/genesis

Quick start

Interactive TUI

genesis
genesis --provider anthropic --model claude-sonnet-4-6
genesis --provider z.ai --model glm-4.7

Server + Web UI

# Terminal 1: genesis server
genesis --server --transport ws --listen 127.0.0.1:7700 --mode auto --cwd /path/to/project

# Terminal 2: web UI
cd web && bun install && bun run build && bun run dev
# Open http://localhost:3000

Swarm

genesis --task "Implement a REST API for user management"
genesis --task "Refactor auth module" --agents 6 --cycles 5

Docker

docker build -t genesis .
docker run -p 3000:3000 -p 7700:7700 \
  -e GENESIS_MODE=auto \
  -e GENESIS_CWD=/home/genesis \
  genesis

Scheduler

genesis --scheduler
genesis --scheduler --scheduler-once

CLI flags

Flag	Purpose
--chat, -i	interactive TUI mode
--task <prompt>	swarm mode
--server	server mode
--transport <ws|stdio>	server transport
--listen <addr>	WebSocket bind address
--auth-token-file <path>	server auth token file
--cwd <path>, -d	working directory
--provider <name>, -p	provider override
--model <name>, -m	model override
--mode <safe|normal|auto|yolo>	permission mode
--budget <usd>	budget limit
--thinking	enable extended reasoning
--thinking-budget <n>	thinking token budget
--reasoning-effort <e>	reasoning effort level
--expand-thinking	expand thinking blocks in TUI
--agents <n>, -a	swarm agent count
--cycles <n>, -c	swarm max cycles
--session <name>	load session by name
--run <mode>	run mode
--mcp-config <path>	MCP server config file
--hooks-config <path>	hooks config file
--scheduler	scheduler mode
--scheduler-once	run scheduler once and exit
--verbose, -v	verbose output

TUI

Commands

/help                          show help
/providers                     list providers
/provider use <name> [account] switch provider
/model, /llm                   model picker dialog
/session, /load, /new          session management
/theme                         theme picker (6 themes x dark/light)
/thinking, /effort             reasoning config
/mode <safe|normal|auto|yolo>  permission mode
/sandbox                       toggle sandbox
/mcp list|add|remove|...       MCP server management
/channels list|add|remove|...  channel management
/secrets status|unlock|lock|.. secrets vault
/diff, /undo                   file change review
/tools, /skills                tool/skill listing
/settings                      settings hub
/context                       project context
/cost                          token cost
/jobs                          scheduled jobs
/swarm                         run swarm
/clear                         clear chat
/compact                       compact history
/exit, /quit                   quit

Key bindings: Enter submit, Shift+Enter newline, Tab completion, Ctrl+C/Esc Esc abort, PageUp/Down scroll, Ctrl+N notifications, Ctrl+T sandbox toggle, Settings → UI → E toggle error visibility.

Providers

Provider	API style	Notes
anthropic	Anthropic	Claude models
z.ai	Anthropic/OpenAI	GLM routing
openai	OpenAI	GPT and compatible
openai-code	OpenAI (Codex)	ChatGPT coding-plan (OAuth/auth token)
google	Gemini	Gemini API
openrouter	OpenAI-compatible	multi-model router
chutes	OpenAI-compatible	API mode
moonshot	OpenAI-compatible	Kimi models
minimax	OpenAI-compatible	MiniMax models

Per-model overrides: context_window, temperature, top_p, top_k, max_new_tokens.

Details: docs/llm-providers.md

Tools

Built-in tools:

Tool	Level	Description
file_read	safe	Read file contents
file_write	write	Create/overwrite files
edit	write	Exact string replacement
list_dir, glob, grep	safe	Directory listing and file search
shell, terminal	execute	Run shell and PTY-backed terminal sessions
web_fetch, web_search	network	HTTP fetch and web search
todo	safe	Task list management
ask_user	safe	Ask user a question
attach	safe	Attach file to conversation
schedule_task	write	Schedule background tasks
task_list, task_status, task_wait, task_kill	safe	Process management
vault_list	safe	List named secrets
swarm	safe	Launch swarm execution
subagents	safe	Launch parallel subagents
supervisor_verify	safe	Verify results against the task
channel_send	network	Send message to a channel
channel_list	safe	List connected channels and users

Permission levels: safe (always allowed), write (ask in normal), execute (ask in normal), network (ask in normal), destructive (ask in normal+auto).

Details: docs/tools.md

Channels

Genesis integrates with messaging platforms through channel adapters. Each adapter is a standalone process communicating via JSON-RPC over stdio.

Channel	Directory	Features
Telegram Bot	channels/telegram/	text, photos, documents, inline keyboards, message editing, typing
Discord	channels/discord/	text, embeds, DM, file upload, typing, message editing
Slack	channels/slack/	text, mrkdwn, DM (conversations.open), file upload, message editing
X (Twitter)	channels/x/	DM, graceful edit/delete fallback

Channel admin commands

Users can manage genesis through channels via / commands (configurable per-channel):

/status, /config, /usage       view session info
/model <name>                   switch model
/provider <name>                switch provider
/sessions                       list sessions
/mode <auto|normal|safe>        change permission mode
/sandbox                        toggle sandbox
/help                           show available commands

Admin access is configurable per-channel in settings with block-level and granular control.

Cross-channel messaging

Agents can send messages between channels:

channel_list                              -- see connected channels and known users
channel_send(channel="telegram", to="reid", text="Hello!")  -- send by display name
channel_send(channel="discord", to="*", text="Broadcast")   -- broadcast to all

Identity resolution: display name (case-insensitive) -> channel identity -> unified identity.

Details: docs/channel-protocol-spec.md

Web UI

Browser-based interface in web/. Built with React 19, Bun bundler, Zustand state management.

Features:

• Chat with markdown rendering, syntax highlighting, KaTeX math, Mermaid diagrams
• Artifact sidebar -- preview images, HTML, video from workspace
• File browser -- navigate workspace, multi-select download
• Inline file links -- download icons on file names in agent responses
• Session management (create, switch, delete, rename)
• Permission and question prompts
• Swarm and subagent progress panels
• Trace timeline
• Settings modal: themes (6 x dark/light), model, provider, reasoning, voice, permissions, MCP, channels, secrets
• Voice input (speech-to-text)
• 6 themes with dark/light variants
• Auth via Genesis server password (no separate token)

cd web
bun install
bun run build
bun run start        # production on port 3000

Environment variables:

• GENESIS_WS_URL -- genesis WebSocket URL (default: ws://127.0.0.1:7700)
• WEB_PORT -- web server port (default: 3000)
• GENESIS_CWD -- working directory for file serving (default: process.cwd())

Full documentation: web/README.md

VS Code Extension

Full-featured sidebar extension in extensions/vscode/.

Features:

• Chat with streaming markdown, syntax highlighting, Mermaid diagrams
• File attachments (drag-drop, paste, file picker)
• Voice input (speech-to-text)
• Session management and history
• Swarm mode with progress visualization
• Settings panel with all configuration options
• 6 Genesis themes synced with editor

Install from .vsix or marketplace. Requires Genesis server running.

Full documentation: extensions/vscode/README.md

Swarm

Parallel multi-agent execution with:

• SGF (Stigmergic Gradient Field) -- shared knowledge
• GWC (Global Workspace Competition) -- artifact selection
• HTA (Hebbian Topology Adapter) -- agent clustering
• WDG (Work Decomposition Graph) -- task breakdown
• MD (Morphogenetic Differentiation) -- role assignment

Roles: architect, scout, worker, reviewer, integrator.

Details: docs/swarm.md

Subagents

Lightweight parallel task runtime:

• Built-in subagents tool for delegating independent tasks
• Overlay workspace isolation per subagent
• Automatic merge of changes back to base directory
• TUI progress panel with per-subagent status

Details: docs/subagents.md

Permission system

Four modes controlling tool approval:

Mode	safe	write	execute	network	destructive
yolo	auto	auto	auto	auto	auto
auto	auto	auto	auto	auto	ask
normal	auto	ask	ask	ask	ask
safe	auto	deny	deny	deny	deny

Destructive detection covers: rm, rmdir, git reset --hard, DROP TABLE, shutil.rmtree(), os.remove(), fs.unlink(), pathlib.Path().unlink(), dd if=, mkfs., and 30+ other patterns across Python, Node.js, Ruby, and SQL.

Vault

Genesis includes an encrypted secrets vault for API keys, tokens, and passwords. Nothing sensitive is ever written to disk in plain text.

• Encrypted with XChaCha20-Poly1305, key derived with Argon2id
• Stores per-provider API keys, channel tokens, MCP credentials
• Unlocked once per session with a passphrase

/secrets unlock <passphrase>   # initialize or unlock
/secrets status                # check vault state
/secrets lock                  # lock the vault

Details: docs/vault.md

Configuration

All settings stored in ~/.genesis/config/global.json:

• Active provider and account
• Agent defaults (model, mode, sandbox, thinking, budget)
• UI settings (theme, expand_thinking)
• MCP servers
• Channels (command, args, env, admin access)
• Per-model overrides

Secrets stored in ~/.genesis/secrets/vault.v1 (encrypted).

Sessions stored in ~/.genesis/sessions/.

Architecture

src/
  agent/        interactive agent, tool loop, streaming
  channels/     channel bridge, runtime, manager, admin, identity
  console/      console output utilities
  context/      history compaction, model registry, project context
  core/         shared types, events, memory utilities
  debug/        debug tooling
  llm/          providers, transport, routing, sampling defaults
  main/         CLI parsing, runtime entry points
  math/         math utilities
  mcp/          MCP runtime and config
  process/      shell runner and sandbox
  prompts/      system prompts for channels, swarm synthesis
  runtime/      runtime lifecycle
  scheduler/    background jobs and notifications
  secrets/      encrypted vault, crypto, persistent unlock
  server/       ws/stdio server, service, handlers, session lifecycle
  session/      snapshot persistence and codec
  settings/     schema, merge, store, validation
  skills/       agent skills
  subagents/    delegated agent runtime
  swarm/        swarm engine and algorithms
  themes/       6 theme definitions with dark/light variants
  tools/        builtin tools, registry, permissions, executor, workspace
  ui/           rtui application, widgets, events, dialogs
  utils/        shared utilities

channels/       channel adapter processes (telegram, discord, slack, x)
web/            React web UI (Bun + Zustand)
packaging/      npm, pip, brew, nfpm, install.sh

License

MIT