Holix — Self-Improving AI Agent

Holix is a self-improving AI agent with persistent memory, a skills system, tool calling, MCP integration, and multiple interfaces: CLI, TUI, API gateway, and Telegram.

Website: holix-agent.ru · PyPI: Holix · GitHub: javded-itres/Holix · Telegram: @helix_agent · Docs: EN · RU · Donate: Boosty

Features

• Tool calling — files, shell, web, code execution, optional Playwright browser tools
• Persistent memory — SQLite conversations + ChromaDB semantic search
• Skills — markdown skills with auto-generation and hub catalogs (ClawHub, Hermes, Claude plugins)
• MCP — configure and assign Model Context Protocol servers per agent
• Multi-provider — Ollama, LiteLLM, OpenAI, Groq, and any OpenAI-compatible API
• Interfaces — holix tui, holix chat-command, holix run, holix gateway
• Security — API keys, rate limits, command whitelist, confirmation prompts
• Operations — holix doctor, holix logs, background gateway supervisor, Docker

Quick start

Install

One-line install (detects OS language, asks full vs minimal, runs holix bootstrap for LLM + Telegram):

curl -fsSL https://raw.githubusercontent.com/javded-itres/Holix/main/scripts/install.sh | bash

Russian systems use Russian prompts automatically; English systems choose EN/RU. See docs/en/INSTALLATION.md.

Install from PyPI (Python 3.12+). Package: Holix, CLI command: holix:

pipx install Holix              # global CLI (recommended)
pipx install "Holix[all]"       # + telegram, browser, tui-web, voice

# or in a virtualenv:
pip install Holix
pip install "Holix[telegram,browser]"

Do not use pip install helix — that is a different package on PyPI.

Update later: holix update --channel pypi

From source (developers):

git clone https://github.com/javded-itres/Holix.git
cd Holix
./scripts/install.sh          # macOS / Linux
# Windows: .\scripts\install.ps1

holix version
holix doctor

Publishing: docs/en/PYPI.md

Developer install:

uv sync && uv pip install -e .
cp .env.example .env

Full guide: docs/en/INSTALLATION.md

Configure and run

holix models setup
holix tui                    # recommended UI
# or:
holix chat-command
holix run "What is in this repo?"
holix gateway start

Documentation (English)

Документация (русский)

CLI at a glance

holix tui                          # main UI
holix run "query"                  # one-shot
holix models setup                 # providers
holix hub browse                   # external skills
holix mcp setup                    # MCP servers
holix gateway start|status|stop|reload
holix logs [-s agent] [-f]
holix doctor [--fix]
holix install | holix update

In TUI/Telegram, type /help for slash commands. See docs/en/SLASH_COMMANDS.md.

Architecture

HolixAgent → run_agent_loop() (core/agent_execution.py)
           → LangGraph / AgentLoop

Details: docs/en/ARCHITECTURE.md

Docker

cp docker/env.example .env
# set TELEGRAM_BOT_TOKEN, MODEL, BASE_URL, API_KEY, HOLIX_API_KEY_PEPPER
docker compose up -d --build

Drop-in extensions: put packages under ./extensions/. Full guide: docs/en/INSTALLATION.md § Path B.

Contributing

See CONTRIBUTING.md. Run tests before PRs: uv run pytest -m "not llm".

Extensions

Build extensions with the separate holix-sdk package (stable public API):

pip install holix-sdk Holix

Repository: github.com/javded-itres/holix-sdk

holix extensions list
holix extensions agent-list

Reference: packages/holix-extension-demo in this repo.

License

Holix core: MIT — see LICENSE.

Holix Studio is a separate extension package (holix-studio) under the Holix Studio Source Available License (source visible, no redistribution or resale). Install from the Studio repository when needed (pip install / clone). Holix loads it via the holix.extensions entry-point API — see THIRD_PARTY_LICENSES.md.