██╗ ██╗██╗ ██╗██████╗ ███████╗██████╗ ██████╗ ██████╗ ████████╗
██║ ██╔╝╚██╗ ██╔╝██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔═══██╗╚══██╔══╝
█████╔╝ ╚████╔╝ ██████╔╝█████╗ ██████╔╝██████╔╝██║ ██║ ██║
██╔═██╗ ╚██╔╝ ██╔══██╗██╔══╝ ██╔══██╗██╔══██╗██║ ██║ ██║
██║ ██╗ ██║ ██████╔╝███████╗██║ ██║██████╔╝╚██████╔╝ ██║
╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═╝╚═════╝ ╚═════╝ ╚═╝
Your AI. Your rules. Powered by Claude Code.
KyberBot is an open-source personal AI agent that runs on top of Claude Code. It gives your Claude Code instance a persistent brain, self-evolving identity, scheduled tasks, messaging channels, and skill auto-generation -- turning a CLI coding assistant into a full personal AI agent.
No API keys to manage. No inference costs beyond your Claude Code subscription. No vendor lock-in. Your data stays in your repo.
You need three things before you start:
- Node.js 18+ -- Download here
- Docker Desktop -- Download here (used for the memory database)
- Claude Code -- Get it here (requires an active subscription)
This installs the kyberbot command on your machine. You only do this once.
git clone https://github.com/KybernesisAI/kyberbot.git
cd kyberbot
npm install
npm run build
cd packages/cli && npm link && cd ../..Think of this like installing an app. The kyberbot/ folder is the app itself -- you don't work inside it.
Create a new folder anywhere on your machine and run kyberbot onboard inside it:
mkdir ~/my-agent
cd ~/my-agent
kyberbot onboardThe onboard wizard asks you a few questions (agent name, your name, personality style) and sets up everything in this folder -- personality files, memory databases, Claude Code configuration, and more.
This folder is your agent. Everything it knows, everything it learns, its entire personality and memory -- all lives here.
When a new version is released, update the CLI and refresh your agent's template files in one command:
cd ~/my-agent
kyberbot updateThis pulls the latest source, rebuilds the CLI, and refreshes infrastructure files (.claude/CLAUDE.md, settings, commands) while preserving all your agent's data (SOUL.md, USER.md, brain/, skills/, etc.).
Use kyberbot update --check to preview changes before applying them.
From your agent's folder, run:
kyberbotThis starts all background services (memory database, heartbeat scheduler, messaging channels). Leave this terminal running.
Open a second terminal, go to your agent's folder, and start Claude Code:
cd ~/my-agent
claudeClaude Code automatically loads your agent's personality and memory. Just start talking.
See Getting Started for the full walkthrough.
Your agent maintains living documents that evolve over time:
- SOUL.md -- Personality, values, communication style. The agent updates this as it learns who it is to you.
- USER.md -- Everything the agent knows about you. Preferences, projects, routines, goals.
- HEARTBEAT.md -- Recurring tasks the agent should perform on a schedule (daily briefings, health checks, reminders).
KyberBot has a real memory system, not just context window tricks:
- Entity Graph -- Tracks people, companies, projects, and their relationships
- Timeline -- Temporal log of events, conversations, and notes
- Semantic Search -- Vector-based search for meaning-based recall across all memories
- Sleep Agent -- Background process that maintains memory quality (decay, tagging, linking, tiering, summarization, entity hygiene)
- Hybrid Search -- 70% semantic + 30% keyword scoring for accurate recall
Define recurring tasks in HEARTBEAT.md and KyberBot executes them on cadence:
- Morning briefings
- Evening reviews
- Health check-ins
- Project status updates
- Anything you can describe in natural language
Talk to your agent from anywhere:
- Telegram -- Connect via BotFather, chat with your agent on mobile
- WhatsApp -- QR code authentication, full bidirectional messaging
- Extensible channel interface for adding new platforms
When your agent encounters a task it cannot handle, it creates a new skill:
- Skills are markdown files with structured instructions
- The agent generates, tests, and persists skills autonomously
- Skills accumulate over time, making the agent permanently more capable
- Full lifecycle management: list, create, remove, setup
KyberBot is not a framework that wraps an LLM. It is a layer on top of Claude Code that provides:
- Identity -- SOUL.md, USER.md, and HEARTBEAT.md loaded as context
- Memory -- Kybernesis Local databases the agent reads and writes via CLI tools
- Scheduling -- A heartbeat loop that invokes Claude via the Agent SDK for recurring tasks
- Channels -- Telegram/WhatsApp bridges that pipe messages to and from Claude
- Skills -- Markdown skill files that teach the agent new capabilities
Claude Code handles the hard parts: tool use, sub-agent orchestration, MCP servers, file editing, permissions, and reasoning. KyberBot just gives it a brain and a body.
Background operations (heartbeats, channel messages) use the Agent SDK (@anthropic-ai/claude-code) by default, which works with your Claude Code subscription at no extra cost. An Anthropic API key can be used instead for direct SDK access.
┌─────────────────────────────────────────────────────────┐
│ Claude Code │
│ ┌─────────┐ ┌──────────┐ ┌────────┐ ┌───────────┐ │
│ │ SOUL.md │ │ USER.md │ │Skills/ │ │ CLAUDE.md │ │
│ └─────────┘ └──────────┘ └────────┘ └───────────┘ │
├─────────────────────────────────────────────────────────┤
│ KyberBot CLI │
│ ┌───────────┐ ┌───────────┐ ┌────────────────────┐ │
│ │ Heartbeat │ │ Channels │ │ Claude Runtime │ │
│ │ Scheduler │ │ Telegram │ │ (Agent SDK / SDK / │ │
│ │ │ │ WhatsApp │ │ Subprocess) │ │
│ └─────┬─────┘ └─────┬─────┘ └─────────┬──────────┘ │
├────────┼──────────────┼──────────────────┼──────────────┤
│ │ Kybernesis │ │ │
│ │ Local │ │ │
│ ┌─────▼──────────────▼──────────────────▼──────────┐ │
│ │ Semantic Entity Graph brain/ │ │
│ │ Search Timeline (markdown │ │
│ │ (vectors) (structured) knowledge) │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────┐ │
│ │ Sleep Agent │ │
│ │ decay → tag → link → tier → summarize → │ │
│ │ entity hygiene │ │
│ └────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
| Feature | KyberBot | LettaBot | OpenClaw |
|---|---|---|---|
| Runtime | Claude Code (sub-agents, MCP, skills) | Custom Python framework | Custom Python framework |
| Cost | $0 beyond Claude Code subscription | API token costs | API token costs |
| Memory | Kybernesis Local + sleep agent | Custom memory server | Vector DB only |
| Self-Evolution | SOUL.md, USER.md auto-update | Static config | Static config |
| Skill Generation | Agent creates its own skills | Manual tool registration | Manual tool registration |
| Scheduling | HEARTBEAT.md natural language | Cron-based | No built-in scheduler |
| Messaging | Telegram, WhatsApp | API endpoints | API endpoints |
| Setup | Clone + kyberbot onboard (5 minutes) |
Docker + API keys + config | Docker + API keys + config |
| Sub-Agents | Native Claude Code sub-agents | Single agent | Single agent |
| Permissions | Claude Code permission system | Custom auth | Custom auth |
| Open Source | MIT | MIT | Apache 2.0 |
Claude recently restricted OpenClaw and Hermes-Agent from running on Pro and Max subscriptions — they require infrastructure that operates outside the Claude Code harness. KyberBot runs natively inside Claude Code and is completely unaffected.
If you were using either of those tools, you can be up and running in about 5 minutes.
Step 1: Install KyberBot
git clone https://github.com/KybernesisAI/kyberbot.git
cd kyberbot && npm install && npm run build
cd packages/cli && npm link && cd ../..Step 2: Create your agent
mkdir ~/my-agent && cd ~/my-agent
kyberbot onboardStep 3: Start it
kyberbot # Start services (leave running)
# Open a second terminal:
claude # Talk to your agentNo Docker. No API keys. No extra cost beyond your existing Claude subscription.
| Feature | KyberBot | OpenClaw | Hermes-Agent |
|---|---|---|---|
| Works on Claude Pro/Max | Yes | No (restricted) | No (restricted) |
| Extra cost | $0 | API tokens ($10–100+/day) | API tokens |
| Setup time | ~5 minutes | 30+ minutes | 30+ minutes |
| Memory | 6-component system (entity graph, vectors, facts, reasoning, timeline, sleep agent) | Vector DB only | Vector DB only |
| Self-evolving | SOUL.md, USER.md update automatically | Static config | Static config |
| Scheduled tasks | HEARTBEAT.md (natural language) | None | Limited |
| Messaging | Telegram, WhatsApp | API-only | API-only |
| Open source | MIT | Apache 2.0 | Varies |
Visit the GitHub Discussion for migration help, FAQs, and community support.
- Getting Started -- Installation, onboarding, first conversation, updating
- Self-Evolution -- How the agent evolves its identity and knowledge
- Living Documents -- SOUL.md, USER.md, HEARTBEAT.md reference
- Brain -- Memory architecture (Kybernesis Local, sleep agent)
- Skills -- Skill system and auto-generation
- Channels -- Telegram and WhatsApp messaging setup
- Architecture -- System overview, data flow, file structure
- VPS Deployment -- Run KyberBot on a server for 24/7 uptime
- CLI Reference -- Complete command reference (16 commands, 38 subcommands)
- Why KyberBot? -- Positioning and philosophy
See CONTRIBUTING.md for guidelines on how to contribute.
MIT -- see LICENSE.
Built with Claude Code. Maintained by the community.