Genesis
MCP server for Genesis UI Design System - provides AI assistants with access to components, hooks, and design tokens
Ask AI about Genesis
Powered by Claude · Grounded in docs
I know everything about Genesis. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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_listtools - Vision fallback -- automatic image/video analysis routing for non-vision models
- Voice input -- speech-to-text via
/voicecommand 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
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
subagentstool 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
