A lean, local-first, LLM-agnostic AI agent framework.
Built for people who actually work for a living.
One model. RAG memory. Dynamic skills. Self-modifying plugins.
pi-like extension system. Token budget. Hybrid terminal+browser.
Runs locally, costs nothing, grows its own capabilities.
CyborgOS is an AI agent framework that strips away the bloat of LangChain and Agent Zero and replaces it with a clean, modular architecture centered around:
- One model doing the work — no separate utility models burning tokens in the background
- RAG-based persistent memory — retrieves context only when relevant, not on every single call
- Dynamic skills system — skills auto-load based on what you're asking, not preloaded into every context window
- Plugin architecture — extend capability without touching core code
- LLM agnostic from day one — swap models by changing one line in config
⚡ New in v1.1: CyborgOS can now write its own plugins — Pi-style self-modification. Describe what you need, and the agent writes, installs, and hot-reloads the code at runtime. Smart token budgeting prevents Agent Zero-style token burn.
This is the Cyborg approach. Human grit plus machine efficiency.
pip install cyborg-os
cyborgOpen http://localhost:3000.
git clone https://github.com/derycktheaiguy/CyBorg-OS.git
cd CyBorg-OS
cp .env.example .env
docker-compose upOpen http://localhost:3000 — you're running.
git clone https://github.com/derycktheaiguy/CyBorg-OS.git
cd CyBorg-OS
# Install Python dependencies (includes FastAPI backend and CLI)
pip install -r backend/requirements.txt
# Configure
cp .env.example .env
# Edit config/cyborg.yaml with your model settings
# Run
python backend/main.pyOpen http://localhost:3000.
python cli/cyborg_cli.py chat┌─────────────────────────────────────────────────────────┐
│ CyborgOS │
├─────────────┬─────────────┬─────────────────────────────┤
│ WebUI │ CLI │ REST API │
│ (WebSocket) │ (Click) │ (FastAPI) │
├─────────────┴─────────────┴─────────────────────────────┤
│ Agent Core │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Memory │ │ Skills │ │ Plugins │ │ Commands │ │
│ │ (AST-RAG)│ │ (SKILL.md│ │ (Drop-in)│ │ (Dynamic) │ │
│ │ │ │ Auto) │ │ │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └───────────┘ │
├─────────────────────────────────────────────────────────┤
│ Tool Layer │
│ Files │ Search │ Code │ Terminal │ Browser │ ImageGen │
│ │ │ ┌───────────────────────┐ │
│ │ │ │ Zero-Trust Docker │ │
│ │ │ │ Cryptographic Sandbox │ │
│ │ │ └───────────────────────┘ │
│ │ │ │
│ ┌─────┴────────┴──────────┐ ┌──────────────────────┐ │
│ │ 🔥 Self-Modify Pipeline │ │ 📊 Token Budget │ │
│ │ create_plugin │ │ Per-session tracking │ │
│ │ generate_plugin (LLM) │ │ 85% warn / 95% block │ │
│ │ install_dependency │ │ Context compaction │ │
│ │ reload_plugins (hot) │ │ /budget command │ │
│ │ update_config │ │ │ │
│ └─────────────────────────┘ └──────────────────────┘ │
├─────────────────────────────────────────────────────────┤
│ Universal Provider Layer │
│ Ollama │ HuggingFace │ OpenAI │ Anthropic │ DeepSeek │
└─────────────────────────────────────────────────────────┘
CyborgOS works with any LLM provider via dynamic convention-based discovery. Change your model with one line in config/cyborg.yaml:
| Provider | Config Example | Env Var Required |
|---|---|---|
| Ollama | provider: ollama / name: qwen2.5:7b |
No |
| Hugging Face | provider: huggingface / name: meta-llama/Llama-3.1-8B-Instruct |
HUGGINGFACE_API_KEY |
| OpenAI | provider: openai / name: gpt-4o |
OPENAI_API_KEY |
| Anthropic | provider: anthropic / name: claude-sonnet-4-20250514 |
ANTHROPIC_API_KEY |
| DeepSeek | provider: deepseek / name: deepseek-chat |
DEEPSEEK_API_KEY |
| Groq | provider: groq / name: llama-3.3-70b |
GROQ_API_KEY |
| OpenRouter | provider: openrouter / name: meta-llama/llama-3.3-70b |
OPENROUTER_API_KEY |
provider: gemini / name: gemini-2.5-pro |
GOOGLE_API_KEY |
|
| Any Custom Server | provider: custom / api_base: http://your-endpoint/v1 |
Varies |
Swap models at runtime with /model <name> — no restart needed.
CyborgOS ships with 27 built-in slash commands and a dynamic command system that lets you create new commands at runtime.
| Command | Description |
|---|---|
/help |
Show all available commands |
/skills |
List all loaded skills |
/skill <name> |
Manually load a specific skill |
/plugins |
List all active plugins |
/plugin <name> |
Get info on a specific plugin |
/remember <text> |
Save something to memory |
/forget <text> |
Delete a specific memory |
/memories |
Open memory dashboard |
/clear |
Clear current conversation |
/model <name> |
Swap the active model |
/config |
View current configuration |
/tools |
List available tools |
/search <query> |
Web search |
/run <command> |
Execute a terminal command |
/budget |
📊 View token usage and budget |
/new |
Start a new conversation |
/save |
Save conversation to file |
/export |
Export conversation as markdown |
/status |
System status overview |
/history |
Show conversation history |
/sessions |
List all sessions |
/version |
Show CyborgOS version |
| Command | Description |
|---|---|
/commands |
List all registered commands |
/newcommand |
Create a new command interactively |
/editcommand <name> |
Modify an existing command |
/deletecommand <name> |
Remove a command |
/exportcommands |
Export commands to portable JSON |
/importcommands <file> |
Import commands from JSON |
Commands are stored as JSON and can be created by you, the agent, or imported from other CyborgOS instances. They persist across sessions and support versioning with rollback.
"What makes Pi truly shine is its extension system." — Deryck Stidham
CyborgOS now has the same capability. The Self-Modify Pipeline gives the agent 5 tools to extend itself at runtime — no restart required.
| Tool | What It Does | How to Use |
|---|---|---|
create_plugin |
Write a new Python plugin to /plugins/ |
Give it the code, it writes the file |
generate_plugin |
Describe what you want → the LLM writes the code | "Build me a weather plugin that calls OpenWeatherMap" |
install_dependency |
pip install any package |
"I need beautifulsoup4 for web scraping" |
reload_plugins |
Hot-reload all plugins without restart | Called automatically after creating a plugin |
update_config |
Modify cyborg.yaml with auto-backup |
"Change the temperature to 0.5" |
You: "Create a plugin that tracks stock prices"
↓
Agent uses generate_plugin → LLM generates Python code
↓
create_plugin writes plugin.py to /plugins/stock_tracker/
↓
install_dependency installs yfinance
↓
reload_plugins hot-loads the new plugin
↓
Agent: "Done. You can now use the `get_stock_price` tool."
The agent literally writes its own software upgrades — just like Pi's extension system.
All plugin names are validated against path traversal attacks. The pipeline creates config backups before writes, uses subprocess timeouts on pip, and never executes shell=True.
Traditional agent frameworks (Agent Zero, LangChain) have a "major token burn" problem — they consume your entire context window without warning. CyborgOS tracks every token.
| Feature | Behavior |
|---|---|
| Per-session tracking | Every LLM call adds to the running total |
| 85% warning | WebSocket event + UI notification at 85% of budget |
| 95% compaction | Auto-compresses chat history to stay under budget |
| 100% block | Refuses further calls — prevents runaway costs |
/budget command |
Real-time view of used/remaining tokens |
| API endpoint | /api/status includes full budget breakdown |
CyborgOS now ships with a live terminal panel in the WebUI alongside Chat, Memory, Skills, Plugins, and Commands. The headless browser is enabled by default.
- Terminal Panel: WebSocket-connected terminal with command history, Ctrl+L clear, styled output
- Browser Tool: Playwright-based headless browser for web automation and scraping
- Both sandboxed via Docker's zero-trust execution model
CyborgOS is pip-installable and automatically tested:
pip install cyborg-os # Core installation
pip install cyborg-os[browser] # With Playwright browser support
pip install cyborg-os[dev] # With testing/linting toolsGitHub Actions pipeline:
- 🧪 Test — pytest on Python 3.11/3.12 with JUnit results
- 🔍 Lint — ruff on backend/ and cli/
- 🐳 Docker Build — Full image build + health check verification
- 📦 PyPI Publish — Automatic publish on version tag push (OIDC trusted publishing)
Extend CyborgOS without touching core code. Drop a plugin folder into /plugins/ and it registers automatically.
- Tool Plugins — Add new capabilities to the agent
- Memory Plugins — Add new memory backends
- Provider Plugins — Add new LLM providers
- UI Plugins — Add new WebUI panels
CyborgOS can build its own plugins from scratch. It has a built-in Plugin Development skill that teaches the agent how to write executable Python code to extend its own capabilities.
Just ask: "Create a tool that fetches the current price of Bitcoin."
The agent will write the plugin.py file to disk, write the metadata, and instantly hot-reload its own internal context via the reload_plugins system command. It writes its own software upgrades.
CyborgOS uses the open SKILL.md standard — compatible with Claude Code, Agent Zero, Cursor, and Goose.
- Drop skill folders into
/skills/ - Each skill has a
SKILL.mdwith frontmatter metadata - Skills auto-load based on semantic similarity to your input
- Or manually load with
/skill <name>
---
name: Code Review
description: Reviews code for bugs, performance issues, and best practices
version: 1.0.0
author: Your Name
tags: [code, review, quality]
---
# Code Review
Instructions for the model go here...CyborgOS is compatible with existing skill libraries out of the box.
Single config file at config/cyborg.yaml. Every setting is documented:
model:
provider: ollama # Any LiteLLM-supported provider
name: qwen2.5:7b # Model name
api_base: http://localhost:11434
api_key: ""
context_window: 32000
temperature: 0.7
max_tokens: 4096
memory:
enabled: true
auto_save: true
similarity_threshold: 0.75
max_results: 5
skills:
auto_load: true
similarity_threshold: 0.70
max_skills_per_call: 3See config/cyborg.yaml for the full reference.
# Run all tests
python -m pytest tests/ -v
# Run specific test suite
python -m pytest tests/test_memory.py -v- Fork the repo
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Skills — Write skills for specific domains and share them
- Plugins — Build plugins that extend CyborgOS capability
- Commands — Create command packs for specific workflows
- Core — Improve the agent loop, memory system, or provider support
MIT License. See LICENSE for details.
"This is the Cyborg approach. Human grit plus machine efficiency. Built by a blue collar operator with 30 years of real world experience, not a Silicon Valley engineer who has never held a tool."
CyborgOS is deliberately lean. No multi-agent hierarchy. No separate utility models. No per-call vector embeddings. No framework bloat. Just one model, one agent, one job — done right.
Built by Deryck Stidham
⚡ Human Grit + Machine Efficiency ⚡