Hero Skills

Claude Code skills and shell tools for Hero ecosystem development.

Quick Install

curl -sSfL https://forge.ourworld.tf/lhumina_code/hero_skills/raw/branch/development/tools/install.sh | bash

This will:

• Clone hero_skills to ~/hero/code/hero_skills (or pull if already present)
• Install nushell and set it as your default shell
• Configure nushell modules (agent, forge, secrets, installers)
• Set up zoxide and fzf integrations

---

Environment Setup

Run once to configure your environment:

init setup    # first-time wizard: sets ROOTDIR, FORGE_TOKEN, writes secrets.nu
init main     # load Hero environment into current shell

You must be inside nu, not bash/zsh. init setup is a nushell command. If you ran the installer over SSH/mosh and dropped back into bash (e.g. chsh has not taken effect for the current session, or mosh cached the old shell), running init setup from bash prints Expected single character argument because bash parses setup as short flags. Fix: type nu to enter nushell first, then run init setup. A fresh login (after chsh) or exec nu also works.

Required Environment Variables

These must be set (done by init main) — all modules fail explicitly if missing:

Variable	Description
ROOTDIR	Root of your Hero filesystem (e.g. /Volumes/T7)
CODEROOT	Always $ROOTDIR/code0 — where repos live
BUILDDIR	Always $ROOTDIR/build — Cargo and build artifacts

FORGE_URL defaults to https://forge.ourworld.tf. FORGE_TOKEN is required for any API operations.

---

Modules (tools/modules/)

Coding Conventions

• Every module function that uses ROOTDIR, CODEROOT, or BUILDDIR calls ensure_env_vars first — it fails with a clear message if any are missing. Never use | default fallbacks for these vars inside functions.
• Repo resolution always goes through forge_resolve $name — never construct $CODEROOT/name paths directly. forge_resolve is offline-first: searches local code0 before hitting the API.
• Positional args, not flags for nr (worktree number) and search terms — follow the forge cd pattern: name first, nr second, both optional.

---

forge cd — Navigate code directories

forge cd                  # cd to $CODEROOT (code0)
forge cd hero             # cd to matching dir in code0
forge cd 2                # cd to $ROOTDIR/code2 (created if missing)
forge cd hero 2           # cd to matching dir in code2 (runs forge worktree if missing)

• If nr given and $ROOTDIR/codeN doesn't exist, it is created automatically.
• If a search term is given but no match found in the target dir, forge worktree <name> <nr> is called automatically.

---

forge worktree — Clone and manage worktrees

forge worktree hero_lib       # clone into $CODEROOT (code0), cd to it
forge worktree hero_lib 1     # clone into $CODEROOT, create worktree in $ROOTDIR/code1
forge worktree hero_lib 2     # clone into $CODEROOT, create worktree in $ROOTDIR/code2

• Worktree is based on the current branch in code0 (not hardcoded to development)
• Branch named <current_branch>_<nr> (e.g. development_1)
• If the repo already exists locally, just cd to it.

---

forge workspace — Create worktree from current code0 repo

forge workspace 1    # create worktree in $ROOTDIR/code1 for current repo
forge workspace 2    # create worktree in $ROOTDIR/code2 for current repo

• Must be run from inside code0/<repo>
• Auto-detects repo name and current branch from cwd

---

forge workmerge — Merge worktree back into code0

forge workmerge               # auto-detect repo and nr from cwd, confirm, then merge
forge workmerge hero_lib 1    # merge $ROOTDIR/code1/hero_lib back into $CODEROOT
forge workmerge hero_lib 2    # merge $ROOTDIR/code2/hero_lib back into $CODEROOT

• nr must be > 0 (a worktree, not the main clone).
• When run from inside a worktree, detects repo name and nr automatically and asks confirmation.
• On merge conflicts: calls a 0 agent to resolve, git add, and git commit --no-edit.
• After successful merge: removes the worktree and deletes the branch.

---

forge workdiscard — Discard a worktree

forge workdiscard             # auto-detect from cwd (must be inside codeN)
forge workdiscard 1           # list all repos in code1, ask to discard each
forge workdiscard 2           # same for code2
forge workdiscard 1 hero_proc # discard code1/hero_proc specifically

• Shows workspace path and branch, warns about data loss, asks [y/N]
• cd back to code0/<repo> after discarding
• Removes the worktree and deletes the branch (-D force delete)

---

forge new — Create a repo on Forgejo

forge new lhumina_c/my_repo            # create repo with Apache 2.0, README, Rust .gitignore
forge new lhumina_c/my_repo --private  # same, private repo
forge new lhumina_c/my_repo --no-agent # skip agent setup after creation
forge new lhumina_c/my_repo --instruction "build a hero_proc client"

• Partial org name matching (lhumina_c matches lhumina_code)
• Auto-initializes with Apache 2.0 license, README.md, and Rust .gitignore (via Forgejo templates)
• If the remote repo already exists: warns with a danger message and asks to delete + recreate
• If the local directory already exists and is not empty: asks to delete it
• Sets up a development branch and launches a 0 to scaffold the Rust project

---

forge delete — Delete a repo

forge delete lhumina_code/my_repo   # delete local dir and/or remote repo
forge delete my_repo                # partial name also works

• Checks locally ($CODEROOT/<name>) — if found, asks [y/N] to delete
• Checks remote on Forgejo — if found, warns with danger message and asks [y/N] to delete
• Each step is independent (can delete one without the other)
• cds out of the directory first if you're currently inside it

---

forge pull / forge push — Sync repos

forge pull                    # pull current repo (auto-detects from cwd)
forge pull hero_proc              # clone if missing, otherwise pull (auto-resolves conflicts)
forge push                    # add → commit (agent writes message) → pull → push
forge push hero_lib           # same, for a named repo

• No message argument — the agent reads the diff and writes a meaningful commit message
• Auto-detects repo from current directory (walks up to find .git root)
• On conflict: auto-launches a 0 agent to resolve, git add, and git commit --no-edit

---

forge find / forge list / forge info — Discover repos

forge list                          # all repos
forge list hero                     # repos with 'hero' in name
forge list lhumina/hero             # partial org + partial name
forge find --org lhumina_code       # all repos in org
forge find --search hero_proc --one     # single match → returns URL
forge info hero_lib                 # details: branch, stars, forks, clone URLs, local path

Name matching — all commands accept a partial name (hero) or org/repo (lhumina/hero). Errors if 0 or >1 match. Local paths resolve to $CODEROOT/<reponame>.

---

forge edit / forge add / forge commit

forge edit                      # cd + open $EDITOR for current repo (auto-detects)
forge edit geomind/hero_proc        # cd + open $EDITOR for named repo
forge add hero_lib              # git add -A in repo path
forge commit hero_lib "fix: x"  # git commit in repo path

forge edit, forge pull, and forge push all auto-detect the repo from the current directory — they walk up from pwd to find the .git root and use that repo name.

---

forge secrets — Personal secrets repo

secrets source                  # load secrets into current shell
secrets_edit                    # open secrets.toml in $EDITOR
secrets push                    # commit + push secrets repo (agent writes commit message)
secrets_sync                    # clone/pull your private secrets repo from Forgejo

Secrets live at $ROOTDIR/code0/secrets/secrets.nu — a private repo on Forgejo.

---

init — Environment initialization

init setup    # first-time wizard
init main     # load env: ROOTDIR, CODEROOT, BUILDDIR, FORGE_URL, EDITOR, sccache

init main sources ~/hero/cfg/init.sh then secrets.nu, derives CODEROOT and BUILDDIR from ROOTDIR, and fails if any critical variable cannot be set.

---

a — AI model launcher

a 0                          # Claude Haiku
a 1                          # Claude Sonnet
a 2                          # Claude Opus
a 1 -i "refactor this file"  # Sonnet with opening instruction
a 6                          # OpenRouter: MiniMax M2.5

#	Model
0	Claude Haiku
1	Claude Sonnet
2	Claude Opus
4	OpenRouter: Mercury-2
5	Groq: Kimi K2 (requires GROQ_API_KEY)
6	OpenRouter: MiniMax M2.5
7	DeepGram: Nemotron 3 120B (requires DEEPGRAM_API_KEY)
10	Groq: Kimi K2 (requires GROQ_API_KEY)

---

Installers

install_base    # curl, fzf, zoxide, yazi, p7zip + yazi plugins & keymaps
install_ai      # Claude Code AI assistant
install_py      # Python via uv + ipython, pudb, openai SDK

install_base installs essential utilities with yazi plugins (chmod, git) and custom keymaps (c m for chmod, n u for nushell). It also registers the shared sccache server as a service inside root's hero_proc — so root's hero_proc must be running before you call it, otherwise the sccache step fails with root's hero_proc is not responding — start it (start_hero_proc as root) and retry. Start it once as root:

start_hero_proc     # as root — supervises sccache + other system services
check_hero_proc     # idempotent: starts it only if not already healthy
install_base        # now safe to run

install_ai downloads Claude Code from claude.ai/install.sh.

install_py installs Python via uv with ipython, pudb, and the openai SDK for AI library access.

---

skills_edit — Edit hero_skills repo

skills_edit     # Open ~/hero/code/hero_skills in $EDITOR

Opens the hero_skills repository in your default editor (zed, code, etc.) so you can browse or edit skills and tools.

---

skills_sync — Sync skills and nushell modules

skills_sync     # Pull latest hero_skills, update ~/.claude/skills/, and refresh nushell modules

This command:

• Pulls the latest hero_skills repo from ~/hero/code/hero_skills
• Auto-resolves merge conflicts (if any) using Claude Sonnet
• Backs up removed skills to ~/.claude/backups/
• Installs/updates skills to ~/.claude/skills/ via rsync
• Refreshes nushell modules by running install.nu
• Prompts you to restart nushell to activate changes

---

hero_utils — Utility functions

y                       # Yazi file manager (cd to navigated dir on exit)
ls-big [path] --top N   # List largest files in dir (default: top 10)
to bytes                # Convert filesize string to bytes
str stats               # Count lines, words, characters in string
to md-table             # Convert table records to markdown table

---

services — Hero service management

Two layers exist, both loaded by the Hero shell:

Stack commands (from tools/modules/services.nu) — clone + make run a whole set of repos at once:

service_core       # hero_skills, hero_lib, hero_proc, hero_lib_rhai, hero_router, hero_logic, hero_code
service_mycelium   # geomind_code/mycelium_network
service_slides     # browser stack (hero_browser)
service_complete   # service_core + matrixchat, slides, whiteboard, osis, rpc, db, embedder, indexer, books, biz, proxy, foundry
service_start [ "org/repo" ... ]   # ad-hoc: start any list of forge locations

All accept --update (pull + forge push before building) and --reset (force rebuild).

Per-service commands (from tools/modules/services/) — manage a single service through root's or the user's hero_proc:

service_proc         install | start | stop                  # hero_proc itself
service_router       install | start | stop | status
service_proxy        install | start | stop | status
service_browser      install | start | stop | status
service_mycelium     install | start | stop | status | bridge_test
service_embedder     install | start | stop | status
service_codescalers  install | start | stop | status | reset

Typical restart (picks up code changes, re-registers, restarts):

service_codescalers start --reset            # user-level service
service_router      start --root --reset     # system-level service (runs under root's hero_proc)

If the command is not found, the services module hasn't been loaded into this shell — run use services/mod.nu * or re-enter the Hero shell.

The older service_hero_proc / service_hero_aibroker / service_browser_mcp names no longer exist. Use service_core (which starts hero_proc as part of the core stack) or service_proc start --root for hero_proc alone.