Holix 0.1.11__tar.gz

holix-0.1.11/.env.example

@@ -0,0 +1,131 @@
+# Holix environment — copy to ~/.holix/.env (primary location)
+# Optional: ./.env in a project dir (lower priority than ~/.holix/.env)
+
+# --- Environment ---
+HOLIX_ENV=development
+# HOLIX_HOME=   # override data dir (default: ~/.holix, XDG_DATA_HOME/helix, or %LOCALAPPDATA%\Holix on Windows)
+# production: forces auth, stricter Telegram/CORS checks
+
+# --- LLM (legacy single-provider; prefer holix models setup + profile providers) ---
+MODEL=qwen2.5-coder:32b
+BASE_URL=http://localhost:11434/v1
+API_KEY=ollama
+TEMPERATURE=0.7
+
+# --- Cloud provider API keys (used via ${ENV:VAR} in ~/.holix/profiles/*/config.yaml) ---
+# OPENAI_API_KEY=
+# OPENROUTER_API_KEY=
+# OPENROUTER_HTTP_REFERER=https://github.com/your-org/helix
+# DEEPSEEK_API_KEY=
+# MOONSHOT_API_KEY=
+# XAI_API_KEY=
+# GROQ_API_KEY=
+# GOOGLE_API_KEY=
+# MISTRAL_API_KEY=
+# TOGETHER_API_KEY=
+# FIREWORKS_API_KEY=
+# CEREBRAS_API_KEY=
+# LITELLM_API_KEY=
+# Hosts for local / remote inference (used by holix models add ollama|litellm|vllm)
+# OLLAMA_HOST=http://127.0.0.1:11434
+# LITELLM_API_BASE=http://127.0.0.1:4000
+# VLLM_HOST=http://127.0.0.1:8000
+
+# --- Agent ---
+MAX_STEPS=15
+DATA_DIR=data
+
+# --- Logging (holix logs) ---
+# HOLIX_LOG_LEVEL=INFO
+# HOLIX_LOG_DEBUG=false
+# HOLIX_LOG_MAX_BYTES=10485760
+# HOLIX_LOG_BACKUP_COUNT=10
+# HOLIX_LOG_ROTATION_DAYS=14
+
+# --- Web TUI (holix tui --web) ---
+# HOLIX_TUI_WEB_TOKEN=   # required for --allow-lan / production; optional on 127.0.0.1
+
+# --- Gateway ---
+HOLIX_GATEWAY_HOST=127.0.0.1
+HOLIX_GATEWAY_PORT=8000
+# HOLIX_GATEWAY_WITH_DOCS=1
+# HOLIX_DOCS_HOST=127.0.0.1
+# HOLIX_DOCS_PORT=8080
+
+# --- Documentation-site chat widget (site-only assistant, no tools) ---
+# HOLIX_DOCS_CHAT_ENABLED=1
+# HOLIX_DOCS_CHAT_PROFILE=docs
+# HOLIX_DOCS_CHAT_TOKEN=   # random secret; used by docs server proxy → gateway (not in browser)
+# HOLIX_DOCS_CHAT_RATE_LIMIT_RPM=30
+# HOLIX_DOCS_CHAT_MODEL=smart          # non-reasoning model; avoid coder (uses reasoning tokens)
+# HOLIX_DOCS_CHAT_MAX_TOKENS=4096
+# Profile `docs`: only LLM keys in ~/.holix/profiles/docs/.env — no terminal/file tools used
+
+HOLIX_REQUIRE_AUTH=true
+HOLIX_CORS_ORIGINS=http://127.0.0.1:8000,http://localhost:8000
+HOLIX_API_KEYS_DB=data/security/api_keys.db
+# Required when HOLIX_REQUIRE_AUTH=true (generate: openssl rand -hex 32)
+HOLIX_API_KEY_PEPPER=
+HOLIX_RATE_LIMIT_RPM=100
+HOLIX_ADMIN_RATE_LIMIT_RPM=30
+HOLIX_ENABLE_PROMETHEUS_METRICS=true
+
+# --- Tools (production: disable risky tools) ---
+HOLIX_ENABLE_CODE_EXECUTOR=true
+HOLIX_ENABLE_TERMINAL_TOOL=true
+HOLIX_TERMINAL_COMMAND_WHITELIST=true
+# Extra allowed commands/prefixes (comma-separated): holix gateway start, docker, make
+# HOLIX_TERMINAL_WHITELIST_EXTRA=helix,uv,docker,make
+
+# --- Telegram (optional: uv sync --extra telegram) ---
+TELEGRAM_BOT_TOKEN=
+# HOLIX_TELEGRAM_ACCESS_REQUESTS=true  # default: users send /start, admin approves via CLI
+# HOLIX_TELEGRAM_ADMIN_USER_ID=       # single Telegram admin (set via: holix telegram requests approve … --set-admin)
+# HOLIX_TELEGRAM_ADMIN_PROFILE=admin  # Holix profile for the Telegram admin
+HOLIX_TELEGRAM_ALLOWED_USERS=
+# HOLIX_TELEGRAM_ALLOW_ALL=true  # dev only: allow any Telegram user (never use in production)
+HOLIX_TELEGRAM_PROFILE=default
+
+# --- Voice Messages (Telegram) ---
+# Вариант A — OpenAI Whisper напрямую:
+# OPENAI_API_KEY=sk-...
+# HOLIX_WHISPER_MODEL=whisper-1
+#
+# Вариант B — через LiteLLM proxy (нужна модель whisper в config LiteLLM):
+# HOLIX_WHISPER_BASE_URL=http://192.168.88.252:4000/v1
+# HOLIX_WHISPER_API_KEY=sk-...        # virtual key LiteLLM
+# HOLIX_WHISPER_MODEL=whisper         # model_name из LiteLLM config, не whisper-1
+#
+# Вариант C — тот же litellm-провайдер из профиля (HOLIX_WHISPER_USE_PROFILE_LITELLM=true):
+# HOLIX_WHISPER_MODEL=whisper
+#
+# Вариант D — локально на машине с агентом (без облака, нужен ffmpeg):
+# uv sync --extra voice
+# HOLIX_WHISPER_BACKEND=local
+# HOLIX_WHISPER_LOCAL_MODEL=base      # tiny | base | small | medium | large-v3
+# HOLIX_WHISPER_LOCAL_DEVICE=cpu        # cuda для GPU
+# HOLIX_WHISPER_LOCAL_COMPUTE_TYPE=int8 # float16 на GPU
+# HOLIX_WHISPER_AUTO_DOWNLOAD=true      # скачать модель при старте бота (по умолчанию)
+# HOLIX_WHISPER_LOCAL_DOWNLOAD_ROOT=    # каталог кэша (по умолчанию ~/.holix/models/whisper)
+# HOLIX_TELEGRAM_VOICE_LANGUAGE=ru
+#
+# HOLIX_WHISPER_BACKEND=auto            # local если установлен faster-whisper, иначе API
+# HOLIX_TELEGRAM_VOICE_ENABLED=true
+
+# --- Telegram files (photos, documents) ---
+# HOLIX_TELEGRAM_FILES_ENABLED=true
+# HOLIX_TELEGRAM_MAX_FILE_MB=20
+# HOLIX_TELEGRAM_MEDIA_GROUP_DELAY_MS=800  # пауза перед обработкой альбома
+# HOLIX_TELEGRAM_VISION_MODEL=smart      # имя модели в LiteLLM с поддержкой vision
+# Требуются также LITELLM_API_KEY + LITELLM_API_BASE (или holix models setup)
+
+# --- Browser (optional: uv sync --extra browser) ---
+ENABLE_BROWSER_TOOLS=true
+BROWSER_HEADLESS=true
+BROWSER_ALLOWED_HOSTS=
+
+# --- Web search (holix search configure) ---
+# FIRECRAWL_API_KEY=fc-...
+# SEARXNG_BASE_URL=http://127.0.0.1:8080
+
+# Profile secrets in config.yaml: use ${OPENAI_API_KEY} or ${ENV:OPENAI_API_KEY}

holix-0.1.11/.gitignore

@@ -0,0 +1,86 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+.virtualenvs/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Logs
+logs/
+*.log
+
+# Data and databases
+data/
+*.db
+*.sqlite
+*.sqlite3
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# ChromaDB
+chroma_data/
+**/vector_db/
+**/skills_db/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.hypothesis/
+
+# Docker
+.docker/
+
+# Temporary files
+*.tmp
+*.temp
+.cache/
+.idea
+
+# Local experiments (not part of Helix product)
+mcp_registry_system.py
+mcp_registry_tool.sh
+mcp_system_config.json
+MCP_REGISTRY_SYSTEM_REPORT.md
+
+# Helix local runtime
+.helix/
+.langgraph_api/
+.pid

holix-0.1.11/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Holix Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

holix-0.1.11/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: Holix
+Version: 0.1.11
+Summary: Self-improving AI agent with memory, skills, MCP, CLI, and TUI
+Project-URL: Homepage, https://holix-agent.ru
+Project-URL: Documentation, https://holix-agent.ru
+Project-URL: Repository, https://github.com/javded-itres/Holix
+Project-URL: Issues, https://github.com/javded-itres/Holix/issues
+Project-URL: Changelog, https://github.com/javded-itres/Holix/blob/master/docs/CHANGELOG.md
+Author: Pavel Lukyanov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,cli,langgraph,llm,mcp,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: chromadb>=0.4.0
+Requires-Dist: croniter>=2.0.0
+Requires-Dist: dishka>=1.10.1
+Requires-Dist: fastapi>=0.136.3
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: langgraph-checkpoint>=4.0.0
+Requires-Dist: langgraph>=1.2.0
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: openai>=1.30.0
+Requires-Dist: prompt-toolkit>=3.0.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: textual>=0.80.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: uvicorn>=0.48.0
+Provides-Extra: all
+Requires-Dist: aiogram>=3.15.0; extra == 'all'
+Requires-Dist: faster-whisper>=1.1.0; extra == 'all'
+Requires-Dist: playwright>=1.49.0; extra == 'all'
+Requires-Dist: psutil>=6.0.0; extra == 'all'
+Requires-Dist: pypdf>=4.0.0; extra == 'all'
+Requires-Dist: textual-serve>=1.1.3; extra == 'all'
+Provides-Extra: browser
+Requires-Dist: playwright>=1.49.0; extra == 'browser'
+Provides-Extra: telegram
+Requires-Dist: aiogram>=3.15.0; extra == 'telegram'
+Requires-Dist: pypdf>=4.0.0; extra == 'telegram'
+Provides-Extra: tui-web
+Requires-Dist: textual-serve>=1.1.3; extra == 'tui-web'
+Provides-Extra: voice
+Requires-Dist: faster-whisper>=1.1.0; extra == 'voice'
+Provides-Extra: windows
+Requires-Dist: psutil>=6.0.0; extra == 'windows'
+Description-Content-Type: text/markdown
+
+# 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.
+
+[![PyPI](https://img.shields.io/pypi/v/Holix.svg)](https://pypi.org/project/Holix/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-en%20%7C%20ru-blue)](docs/README.md)
+
+**Website:** [holix-agent.ru](https://holix-agent.ru) · **PyPI:** [Holix](https://pypi.org/project/Holix/) · **GitHub:** [javded-itres/Holix](https://github.com/javded-itres/Holix) · **Telegram:** [@holix_agent](https://t.me/holix_agent) · **Docs:** [EN](docs/en/README.md) · [RU](docs/ru/README.md) · **Donate:** [Boosty](https://boosty.to/javded/single-payment/donation/805721/target?share=target_link)
+
+---
+
+## 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
+
+**Install from PyPI** (Python 3.12+). Package: [`Holix`](https://pypi.org/project/Holix/), CLI command: `holix`:
+
+```bash
+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):**
+
+```bash
+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](docs/en/PYPI.md)
+
+Developer install:
+
+```bash
+uv sync && uv pip install -e .
+cp .env.example .env
+```
+
+Full guide: [docs/en/INSTALLATION.md](docs/en/INSTALLATION.md)
+
+### Configure and run
+
+```bash
+holix models setup
+holix tui                    # recommended UI
+# or:
+holix chat-command
+holix run "What is in this repo?"
+holix gateway start
+```
+
+---
+
+## Documentation (English)
+
+| Topic | Link |
+|-------|------|
+| Install & update | [INSTALLATION.md](docs/en/INSTALLATION.md) |
+| **CLI reference** | [CLI.md](docs/en/CLI.md) |
+| **Slash commands `/`** | [SLASH_COMMANDS.md](docs/en/SLASH_COMMANDS.md) |
+| TUI | [TUI.md](docs/en/TUI.md) |
+| Configuration | [CONFIGURATION.md](docs/en/CONFIGURATION.md) |
+| Skill Hub | [HUB.md](docs/en/HUB.md) |
+| API Gateway | [GATEWAY.md](docs/en/GATEWAY.md) |
+| Logs | [LOGS.md](docs/en/LOGS.md) |
+| Doctor | [DOCTOR.md](docs/en/DOCTOR.md) |
+| Security | [SECURITY.md](docs/en/SECURITY.md) |
+| Deployment | [DEPLOYMENT.md](docs/en/DEPLOYMENT.md) |
+| Troubleshooting | [TROUBLESHOOTING.md](docs/en/TROUBLESHOOTING.md) |
+| Architecture | [ARCHITECTURE.md](docs/en/ARCHITECTURE.md) |
+
+## Документация (русский)
+
+| Тема | Ссылка |
+|------|--------|
+| Установка | [INSTALLATION.md](docs/ru/INSTALLATION.md) |
+| CLI | [CLI.md](docs/ru/CLI.md) |
+| Слэш-команды | [SLASH_COMMANDS.md](docs/ru/SLASH_COMMANDS.md) |
+| Начало | [START_HERE.md](docs/ru/START_HERE.md) |
+
+---
+
+## CLI at a glance
+
+```bash
+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](docs/en/SLASH_COMMANDS.md).
+
+---
+
+## Architecture
+
+```
+HolixAgent → run_agent_loop() (core/agent_execution.py)
+           → LangGraph / AgentLoop
+```
+
+| Layer | Path |
+|-------|------|
+| Execution | `core/agent_execution.py` |
+| Events | `core/agent_events.py` |
+| Tools | `core/tools/` |
+| Memory | `core/memory/` |
+| CLI | `cli/main.py` |
+| Gateway | `api/gateway.py` |
+
+Details: [docs/en/ARCHITECTURE.md](docs/en/ARCHITECTURE.md)
+
+---
+
+## Docker
+
+```bash
+docker compose up -d
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Run tests before PRs: `uv run pytest -m "not llm"`.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

holix-0.1.11/README.md

@@ -0,0 +1,165 @@
+# 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.
+
+[![PyPI](https://img.shields.io/pypi/v/Holix.svg)](https://pypi.org/project/Holix/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-en%20%7C%20ru-blue)](docs/README.md)
+
+**Website:** [holix-agent.ru](https://holix-agent.ru) · **PyPI:** [Holix](https://pypi.org/project/Holix/) · **GitHub:** [javded-itres/Holix](https://github.com/javded-itres/Holix) · **Telegram:** [@holix_agent](https://t.me/holix_agent) · **Docs:** [EN](docs/en/README.md) · [RU](docs/ru/README.md) · **Donate:** [Boosty](https://boosty.to/javded/single-payment/donation/805721/target?share=target_link)
+
+---
+
+## 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
+
+**Install from PyPI** (Python 3.12+). Package: [`Holix`](https://pypi.org/project/Holix/), CLI command: `holix`:
+
+```bash
+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):**
+
+```bash
+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](docs/en/PYPI.md)
+
+Developer install:
+
+```bash
+uv sync && uv pip install -e .
+cp .env.example .env
+```
+
+Full guide: [docs/en/INSTALLATION.md](docs/en/INSTALLATION.md)
+
+### Configure and run
+
+```bash
+holix models setup
+holix tui                    # recommended UI
+# or:
+holix chat-command
+holix run "What is in this repo?"
+holix gateway start
+```
+
+---
+
+## Documentation (English)
+
+| Topic | Link |
+|-------|------|
+| Install & update | [INSTALLATION.md](docs/en/INSTALLATION.md) |
+| **CLI reference** | [CLI.md](docs/en/CLI.md) |
+| **Slash commands `/`** | [SLASH_COMMANDS.md](docs/en/SLASH_COMMANDS.md) |
+| TUI | [TUI.md](docs/en/TUI.md) |
+| Configuration | [CONFIGURATION.md](docs/en/CONFIGURATION.md) |
+| Skill Hub | [HUB.md](docs/en/HUB.md) |
+| API Gateway | [GATEWAY.md](docs/en/GATEWAY.md) |
+| Logs | [LOGS.md](docs/en/LOGS.md) |
+| Doctor | [DOCTOR.md](docs/en/DOCTOR.md) |
+| Security | [SECURITY.md](docs/en/SECURITY.md) |
+| Deployment | [DEPLOYMENT.md](docs/en/DEPLOYMENT.md) |
+| Troubleshooting | [TROUBLESHOOTING.md](docs/en/TROUBLESHOOTING.md) |
+| Architecture | [ARCHITECTURE.md](docs/en/ARCHITECTURE.md) |
+
+## Документация (русский)
+
+| Тема | Ссылка |
+|------|--------|
+| Установка | [INSTALLATION.md](docs/ru/INSTALLATION.md) |
+| CLI | [CLI.md](docs/ru/CLI.md) |
+| Слэш-команды | [SLASH_COMMANDS.md](docs/ru/SLASH_COMMANDS.md) |
+| Начало | [START_HERE.md](docs/ru/START_HERE.md) |
+
+---
+
+## CLI at a glance
+
+```bash
+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](docs/en/SLASH_COMMANDS.md).
+
+---
+
+## Architecture
+
+```
+HolixAgent → run_agent_loop() (core/agent_execution.py)
+           → LangGraph / AgentLoop
+```
+
+| Layer | Path |
+|-------|------|
+| Execution | `core/agent_execution.py` |
+| Events | `core/agent_events.py` |
+| Tools | `core/tools/` |
+| Memory | `core/memory/` |
+| CLI | `cli/main.py` |
+| Gateway | `api/gateway.py` |
+
+Details: [docs/en/ARCHITECTURE.md](docs/en/ARCHITECTURE.md)
+
+---
+
+## Docker
+
+```bash
+docker compose up -d
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Run tests before PRs: `uv run pytest -m "not llm"`.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)