An open-source agent skills router and tool manager for the cto-legends ecosystem.

Tell your agent what you want to do. cto-legends helps it find the right module, install a verified version, and maintain the components you actually use. Each module remains its own open-source project. Register one central skill, then load specialized instructions only when a task needs them. This is the single-skill router: install one skill; every module loads on demand.

This is a curated cto-legends module manager, not a directory of every third-party skill. It manages verified releases and separate tool environments, while your agent supplies the reasoning. How agent skills and modules fit together.

The central recipe targets Grok, Codex, Gemini, Google Antigravity, Claude, Cursor, Windsurf, Aider, and MetaMuse. Use the documented host registration or explicitly load the portable skill. Host discovery and operational verification are tracked separately.

Table of contents

• Why this exists
• Optional Home compatibility
• Quick start and usage
• Install agent skills for your chosen host
• One entry point, instructions loaded on demand
• The module ecosystem
• Architecture and how it works
• Use an installed module
• Keep the ecosystem current
• Where things live
• Central agent discovery
• Research memory
• Verify the complete task
• FAQ
• Development, contributing, and license

Why this exists

cto-legends is the tool coordinator for Empire Craft: building and maintaining your own working environment, with independent modules for infrastructure, web engineering, research, recording, audio, and knowledge capture. legends-empire supplies the workspace and memory direction.

It can sit alongside AI Marketing Hub workflows and other agent tools. Its focus is discovering and operating cto-legends modules and connecting their work to your chosen workspace. It is independently developed and maintained by Benjamin; it is not an AI Marketing Hub product or an official integration.

For research, the shared evidence workflow connects provider collection, full saved responses, offline verification and reuse checks with reviewed Empire intake. Client evidence belongs in the user's workspace, separate from replaceable module installations.

Optional Home compatibility

legends-empire can prepare a Home-ready shared Empire root and original project records while remaining useful without AI Marketing Hub Home. An independently authorized Home capability layer can later use the same canonical business and project directories. Explicit composition preserves Empire's session entry point.

This is a headless capability integration, not a full Home desktop installation or automatic Obsidian plugin setup. Home is not required for standalone Empire. The public catalog neither grants private repository access nor redistributes Home. Follow the adapter handoff for task-specific readiness and reviewed prepare, install, compose, and binding plans. No second agent skill or whole-ecosystem installation is needed.

For access to the AI Marketing Hub Home system, join AI Marketing Hub Pro.

Quick start and usage

Python 3.11 or newer is required across the manager and all Python ecosystem modules. No Git, provider account, background service, or MCP server is needed to install the ecosystem manager.

Install the 0.2.5 wheel, or from source:

python -m pip install https://github.com/avalonreset/cto-legends/releases/download/v0.2.5/cto_legends-0.2.5-py3-none-any.whl
cto-legends route "Google Maps ranking grids"
cto-legends install legends-geogrid
cto-legends install legends-geogrid --apply
cto-legends doctor

If your scripts directory is not on PATH, use python -m cto_legends instead of cto-legends. Installation previews are offline. --apply downloads source and Python dependencies; it never runs paid research.

Install agent skills for your chosen host

Copy the included routing skill into your chosen agent's skill directory:

cto-legends install-skill --directory ~/.agents/skills --apply

Use the directory your agent actually reads (for example a configured Codex skills directory, ~/.gemini/config/skills, or ~/.claude/skills). This is an explicit choice: the installer does not scan or rewrite every agent configuration. Existing skills are never overwritten. Reload your agent's skills, then ask:

Can we generate some AI music?

The central skill selects the audio workflow and reads its installed recipe. It checks model access and hardware before promising generation. No separate Stable Audio skill registration is needed. Try "study my business on Google Maps", "convert my WordPress site to Astro v7", or "save this research in my vault" for other outcomes.

Agents without native skill loading can read the same instructions and use the CLI. Registration writes the skill; successful automatic discovery depends on your agent's configuration. No plugin host is required.

One entry point, instructions loaded on demand

For dependable discovery, connect the central index to startup instructions as well as registering its skill:

cto-legends startup-setup codex
cto-legends startup-setup codex --apply
cto-legends startup-status codex

This preserves existing instructions and provides a checked restoration manifest. Use gemini, antigravity, or claude for their documented user instruction files. Cursor, Grok and MetaMuse need an explicit host-verified instruction file. Read the startup contract and acceptance procedure. Registration alone does not prove that a fresh agent loads or follows the instructions.

Use cto-legends capabilities --markdown for the outcome-based directory and cto-legends handoff <module> for the exact installed instructions. Routing returns bounded candidates and reasons, not an automatic installation decision. The agent handles paraphrases and multi-part goals using the capability index. Discovery contract and limits.

The module ecosystem

Modules are organized across four capability layers (matching the ecosystem directory):

Module	Use it for	Managed setup
legends-empire	Digital ontology, source-cited vault memory, vault stewardship (legends-vault-stewardship), and optional AI Marketing Hub Home adapter	Python 3.11+; POSIX/WSL and native Windows local NTFS transaction support
legends-hetzner	Hetzner Cloud inventory, Cost-Optimized CX/CAX stock radar, Fractional CTO sizing, 10-check preflight, and guarded VPS sniping	Portable Python CLI over hcloud; attachable Empire knowledge library
legends-coolify	Coolify inventory, deployment history, resource status, backup schedules and planning	Read-only Python CLI; packaged source-cited library with optional Empire attachment
legends-cloudflare	Cloudflare zone and DNS inventory, nameservers, preview-first DNS record changes and readback	Dependency-free Python CLI; Obsidian knowledge vault and attachable Empire library
legends-astro	Astro v7 readiness, WordPress and HTML migration contract extraction, Content Layer scaffolding, and dist/ build parity checks	Dependency-free Python and Node CLI; vendored withastro/docs snapshot and attachable Empire library
legends-gohighlevel	GoHighLevel CRM, Workflows v3, Voice/Conversation AI, Custom Objects, and 5-layer agency governance (location-unnerf, user-unnerf, unlock-dashboards, smtp-unlock, rebilling-sync)	Dependency-free Python CLI; preview-first mutations, API readback, and attachable Empire library
legends-geogrid	Google Maps rank grids, local visibility matrices, street maps, and client reports	Research workflow + report libraries + DataForSEO + optional Jev 1.14 signage check
legends-dataforseo	Search, keywords, Google Business Profile, queued research and reusable evidence	Python library + CLI + evidence exporter
legends-firecrawl	Web search, scraping, crawling, Alexandria queries, and provider catalog	Python client + offline catalog; vendor CLI and key need module setup
legends-github	Repository audits, DataForSEO keyword research, README, metadata, social preview, and release preparation	Headless workflows + live research transport
legends-grant	Business, nonprofit, tribe, and government grant finding, matching, and application	Markdown lanes + verified federal API routes; agent submits once per authorization
legends-jev	Typed optical recognition (OCR), storefront signage verification, and action advice from supplied text and image evidence	Isolated Python CLI; operator validates, existing tools actuate; Jev 1.14 optical grounding
legends-obs	OBS recording, scenes, settings, verification, optional cursor overlay extra	Prebuilt CLI; requires Node.js 22+; live control targets Windows
legends-captions	Caption correction, forced-alignment timing, active-word rendering, and proof frames	Pip-installed CLI; stdlib only, speech envs optional
legends-yt-dlp	Repeatable video pulls, transcripts, search, and clip-building with pacing and guardrails	Pip-installed CLI; yt-dlp binary and ffmpeg need module setup; Mullvad opt-in
legends-stable-audio-3	Instrumental music, sound effects, continuous mixes, and batch planning	Python planning CLI; model/GPU setup separate
legends-hyperyap	Local voice typing and desktop dictation powered by NVIDIA Parakeet	Guided desktop installation for Windows, macOS, or Linux
legends-ambient-intelligence	Ambient audio capture, deduplicated archiving, offline transcription, and vault distillation	Pip-installed CLI; ffmpeg and faster-whisper/NeMo need module setup

Pinned versions live in the catalog, not here: cto-legends catalog shows the exact verified set your manager carries. Module recipes load through the router on demand; no module needs its own skill registration.

Seventeen modules have managed CLI installations. The one native module uses cto-legends guide <module>: pinned setup instructions, release downloads, platform information, and published asset checksums. install for those modules returns that handoff, including with --apply; it does not run an app installer, modify OBS scenes, or claim that a native application is installed. Their native updates remain guided and are not part of managed update or rollback.

legends-geogrid report libraries are installed; browser binaries and Linux system libraries need module setup. legends-github may need gh authentication for remote work. Follow each module's README; the manager's doctor verifies its managed Python capabilities, not every optional feature or provider credential.

Python modules get separate environments, so their dependency versions can differ safely. legends-obs uses a verified prebuilt Node package and your Node runtime. Installing legends-geogrid supplies its provider dependency automatically; you only need a standalone module installation for direct module use.

Architecture and how it works

1. Frozen single-skill router, living catalog: Your agent registers a single unchanging skill (cto_legends/SKILL.md). Module recipes, versions, commit pins, and SHA-256 archive checksums live in cto_legends/catalog.json (validate_catalog).
2. Just-in-time remote catalog peek: Local route and handoff use your active catalog first with zero network delay when a local match exists. If route gets no_match or handoff is called for a newly released module not yet in your local catalog, cto-legends performs a bounded, read-only peek of the canonical remote catalog (validating its schema and checksums in memory without writing to disk) and tells you when cto-legends sync will unlock the new capability. When handoff runs for an existing module that has a newer pin upstream, it attaches a non-blocking remote_update_available hint.
3. Isolated per-module environments and atomic activation: Each managed Python module installs into its own virtual environment under releases/<module>/<version>-<hash>/ and must pass its offline readiness probes before state.json switches the active version.

Use an installed module

cto-legends run legends-geogrid -- --help
cto-legends run legends-dataforseo -- routes
cto-legends run legends-github -- capabilities
cto-legends install legends-astro --apply
cto-legends run legends-astro -- doctor --json
cto-legends install legends-stable-audio-3 --apply
cto-legends run legends-stable-audio-3 -- plan --hours 1 --vram-gb 16
cto-legends install legends-obs --apply
cto-legends run legends-obs -- manifest
cto-legends guide legends-hyperyap
cto-legends status

status returns the runtime, source, and agent-guide paths (Python is null for the Node module). Advanced module tools can use that interpreter directly. Execution keeps your current working directory so your outputs belong to your project. Store reports outside the managed source directories.

Audio installation does not download model weights or PyTorch, accept model licenses, or spend hosted credits. OBS installation does not connect to OBS or change settings; follow its first-run guide before live operation.

Credentials stay in your environment. Research tools retain their own explicit execution and spending controls. Installation neither collects credentials nor authorizes paid calls.

Keep the ecosystem current

cto-legends check-updates
cto-legends sync
cto-legends sync --apply
cto-legends update --apply

check-updates compares installed versions, your active catalog, and upstream releases, naming the next step for each drift. sync previews a refreshed catalog from the canonical live copy; --apply adopts it (the previous catalog is kept, and sync --rollback restores it). update --apply then refreshes installed modules only to the new pins. Module updates and new modules arrive through catalog syncs: no manager upgrade and no skill change needed. Your agent can handle those steps when you ask it to update cto-legends. A new upstream tag is not automatically a tested combination.

Source archives and the prebuilt OBS package are pinned to versions and SHA-256 checksums, with their source commits recorded. New managed installations must pass their checks before the active set changes. Failed setups leave the previous active set intact. Previous environments are retained:

cto-legends rollback legends-geogrid
cto-legends rollback legends-geogrid --apply

Rollback switches one module to its previous environment, including its own dependencies. It does not undo work performed by that module.

Where things live

Default: ~/.cto-legends. Set CTO_LEGENDS_HOME or pass --home PATH before the command to choose another location. Module versions live under releases/; state.json selects active versions, and catalog.json holds your synced catalog with catalog.previous.json as its rollback copy. Do not move this folder after installation: Python virtual environments are not relocatable.

Interrupted installations retain diagnostics in install.log. If a process was killed while holding operation.lock, confirm it has stopped before removing that lock. Failed or previous environments are not automatically deleted.

Central agent discovery

One shared skill supports Codex, Gemini, Google Antigravity, Claude, Cursor, Grok and Muse adapters. Preview cto-legends agent-setup gemini; add --apply to register it. Repeat for the hosts you use. --directory PATH selects a different skill root. Existing unmanaged or edited instructions are preserved. Reload the host after registration; actual discovery must be confirmed in that host, not inferred from a file being written. No live parity across all hosts is claimed.

Only this central skill needs registration. It reads the chosen module's instructions on demand. Host tool permissions and operating-system dependency support still apply. Gemini on a remote execution host needs installation there.

For an existing local product not in the public catalog: cto-legends register-guide my-notes /path/to/notes/SKILL.md --apply. This registers a guide only: no installation, update, execution or readiness claim. Such guides resolve through capabilities, route, and handoff, appear in status, stay private, and remain user-managed. They never shadow a catalog module of the same name.

See agent discovery and readiness for the distinction between registration, discovery, and an operational host.

Research memory

cto-legends install legends-empire --apply installs the verified catalog pin of the public source in an isolated Python environment. Run cto-legends run legends-empire -- contracts --check-only to verify its portable contracts, then read the router path returned by status. Python 3.11+ is required. Vault writes use POSIX/WSL or native Windows local NTFS; installing the module never creates or changes a vault.

Verify the complete task

cto-legends task-readiness checks more than CLI installation: map browser execution, provider credential presence, reusable evidence support, and artwork dependencies. It makes no paid calls and does not certify provider authentication. Missing credentials block live research, not offline analysis.

Use agent-audit HOST to inspect discovery roots, and isolate-skills HOST to preview reversible consolidation. See host setup and recovery. Windows and WSL are separate installations.

FAQ

Do I need to upgrade cto-legends or reinstall my agent skill when a new module comes out?

No. The registered router skill (cto_legends/SKILL.md) is generic and names no modules. When a new module is released into the catalog, cto-legends route and cto-legends handoff automatically detect it via the read-only remote catalog peek and prompt you to run cto-legends sync (--apply when authorized).

Does installing cto-legends install all 17 modules on my machine?

No. Installing cto-legends installs only the lightweight Python router and catalog manager. You preview and install individual modules (cto-legends install <module> --apply) only when a task actually needs them.

How do I connect cto-legends and legends-empire to AI Marketing Hub Home?

Install legends-empire to prepare a Home-ready shared Empire root (docs/HOME-ADAPTER.md). For access to the private AI Marketing Hub Home capability layer, join AI Marketing Hub Pro.

Development, contributing, and license

python -m unittest discover -s tests -v
python -m pip install build twine
python -m build
python -m twine check dist/*

See architecture, contributing, code of conduct, security, support, and third-party notices. Python dependencies installed by individual modules may come from PyPI and are not all reproducibly locked by this manager. Module licenses remain in their packages. The manager is MIT licensed. Audio uses Apache-2.0; legends-hyperyap uses AGPL-3.0; OBS Cursor uses GPL-2.0-or-later. They remain separate projects and keep their own licensing and model terms.

• Community & Home system access: AI Marketing Hub Pro
• Website: cto-legends.com