// Guidelines for managing zylos components via CLI and C4 channels. Use when installing, upgrading, or uninstalling components, or when user asks about available components.
| name | component-management |
| description | Guidelines for managing zylos components via CLI and C4 channels. Use when installing, upgrading, or uninstalling components, or when user asks about available components. |
Guidelines for installing, upgrading, and managing zylos components.
zylos is a global npm command (installed via npm install -g zylos).
Run it directly as zylos, NOT as ~/zylos/zylos or ./zylos.
Detailed step-by-step workflows for each operation (Session + C4 modes):
# Check zylos-core version
zylos --version
# List installed components (with versions)
zylos list
# Search available components
zylos search <keyword>
# Component status
zylos status
# Check for zylos-core updates
zylos upgrade --self --check
# Check for beta/prerelease updates
zylos upgrade --self --check --beta
# Check all components for updates
zylos upgrade --all --check
Components declare their configuration requirements in SKILL.md frontmatter:
---
name: my-component
version: 1.0.0
description: Component description
config:
required:
- name: ENV_VAR_NAME
description: Human-readable description
sensitive: true # Optional: marks as secret
optional:
- name: OPTIONAL_VAR
description: Optional setting
default: "default-value"
---
When sensitive: true, the value should be handled carefully and not logged.
New components may declare a non-interactive configure hook:
lifecycle:
hooks:
configure: hooks/configure.js
When present, collect config.required values and pipe them as stdin JSON to the hook. The component owns how those values are stored, usually in ~/zylos/components/<name>/config.json. Components without hooks.configure are legacy-compatible and still receive collected values through ~/zylos/.env.
When user sends requests via C4 comm-bridge (Telegram, Lark, etc.), use streamlined flows with two-step confirmation. Replies must be plain text (no markdown).
The request is from C4 when the message arrives via a communication channel
(e.g., <user> said: ... with a reply via: instruction).
All --json outputs include structured data and a reply field (pre-formatted fallback).
Preferred: Use the JSON data fields to craft a clear, user-friendly plain text reply.
Fallback: If you're unsure how to format the reply, use the reply field directly.
CRITICAL: "add <name>" and "upgrade <name>" MUST ONLY run --check. NEVER execute install/upgrade without the word "confirm" in the user's message.
CRITICAL: confirm flow now always re-downloads (no temp-dir reuse):
--check is for preview/analysis only; any temporary download from check is cleaned up after the check completes.upgrade <name> confirm and upgrade zylos confirm always download a fresh package.--temp-dir; it is no longer supported and the CLI will fail fast.| User says | CLI command |
|---|---|
| list / list components | zylos list |
| info <name> | zylos info <name> --json |
| check / check updates | zylos upgrade --all --check --json |
| check <name> | zylos upgrade <name> --check --json |
| upgrade <name> | zylos upgrade <name> --check --json (CHECK ONLY) |
| upgrade <name> confirm | zylos upgrade <name> --yes --skip-eval --json |
| upgrade <name> beta | zylos upgrade <name> --check --beta --json (CHECK ONLY) |
| upgrade <name> beta confirm | zylos upgrade <name> --yes --skip-eval --beta --json |
| add <name> | zylos add <name> --check --json (CHECK ONLY) |
| add <name> confirm | zylos add <name> --json |
| upgrade zylos | zylos upgrade --self --check --json (CHECK ONLY) |
| upgrade zylos confirm | zylos upgrade --self --yes --json |
| upgrade zylos beta | zylos upgrade --self --check --beta --json (CHECK ONLY) |
| upgrade zylos beta confirm | zylos upgrade --self --yes --beta --json |
| uninstall <name> | zylos uninstall <name> --check --json (CHECK ONLY) |
| uninstall <name> confirm | zylos uninstall <name> confirm --json |
| uninstall <name> purge | zylos uninstall <name> purge --json |
info --json: format as <name> v<version>\nType: <type>\nRepo: <repo>\nService: <name> (<status>)add --check --json: format as <name> (v<version>)\n<description>\nType: <type>\nRepo: <repo>, ask user to confirmadd --json (install result): format as <name> installed (v<version>), mention required config if anycheck --json: format as <name>: <current> -> <latest>, actively analyze changes<name> upgraded: <from> -> <to>, include change summaryerror and message fields, display message (human-readable)| Aspect | Claude Session | C4 |
|---|---|---|
| Confirmation | Interactive dialog | Two-step: preview + "confirm" command |
| Output format | Rich (emoji, formatting) | Plain text only |
| Config collection | Interactive prompts | User provides via follow-up messages |
| Upgrade eval | Claude evaluation runs | Skipped (--skip-eval) |
C4 communication bridge — central gateway for ALL external communication (Telegram, Lark, etc.). Use when replying to users via the "reply via" path, sending proactive messages to external channels, querying recent conversations or checkpoint status (prefer c4-db.js CLI; sqlite3 OK for unsupported queries), fetching conversation history for Memory Sync, or creating checkpoints after sync. Incoming messages are queued by channel bots and delivered to Claude via a PM2 dispatcher daemon. Session-start hooks automatically provide conversation context and can trigger Memory Sync when unsummarized conversations exceed the configured threshold.
Built-in web interface for communicating with Claude without external services. Use when setting up or configuring the web console channel, or troubleshooting browser-based access.
Guardian service that monitors the active runtime agent's state and automatically restarts it if stopped. Use when checking agent liveness state or understanding the auto-restart mechanism.
Start a new session when context is high. Claude uses /clear, Codex uses /exit. Use when context is high or when a fresh session is needed.
Use when the user asks to restart Claude Code, or after changing settings/hooks/keybindings.
Upgrade Claude Code to the latest version with graceful shutdown and auto-restart. Use when the user asks to upgrade or when a new Claude Code version is available.