Installation

Install the app once on each computer. Keep your personal voice home separate from the app checkout.

Prerequisites

• An agent that reads Agent Skills. The installer has targets for Claude Code, Codex and Kilo. Other compatible agents can load the skill folder directly.
• Git and Python 3 for the local helpers. The plugin's Python scripts use the standard library and need no pip packages. They use modern type syntax; use Python 3.10 or newer.
• Access to the private randrescastaneda/voice-forge repository. A public documentation site does not grant access to its source or installer.
• Optional: GitHub CLI (gh) if you want setup to create and verify a private backup repository. You can use the voice home locally without GitHub.

git --version
python3 --version

Each command should print a version. On macOS, accept the Command Line Tools installation if Git prompts for it. If cloning fails, check your GitHub account's repository access and authentication.

Install into Claude Code, Codex or Kilo

git clone https://github.com/randrescastaneda/voice-forge ~/voice-forge
cd ~/voice-forge
python3 scripts/build.py install

The installer creates links for the main skill and every shortcut:

Kilo uses ~/.kilocode/skills/ when that older directory exists and ~/.kilo/ does not. Links point to the app checkout; keep that folder where you installed it. Start a fresh agent session if newly installed skills are not listed.

Preview the changes, select agents, or copy instead of linking:

python3 scripts/build.py install --dry-run
python3 scripts/build.py install --agents codex
python3 scripts/build.py install --agents claude,kilo --copy

--copy creates separate files. A later install skips those existing directories unless you deliberately replace them. Follow the copied-install update steps below after app updates. Read the actual installer help before replacing anything.

Claude Code plugin option

Inside Claude Code, send these two commands in order:

/plugin marketplace add randrescastaneda/voice-forge
/plugin install voice-forge@voice-forge

Private repository access is still required. Plugin skills use a namespace:

/voice-forge:vf-setup
/voice-forge:vf-new explainer-en
/voice-forge:vf-train explainer-en

Choose the linked skills route or the plugin route for a client. If you install both, take care to invoke the intended copy and keep it updated.

Set up the voice home

In your agent, run:

/vf-setup

In Codex:

$vf-setup

Setup asks for a folder, normally ~/.voice-forge, and can create default-en or default-es. It records the location in ~/.config/voice-forge/config.json. An existing voice home is preserved.

Setup offers a private GitHub repository for backup and use across computers. It asks before creating one. When GitHub authentication is needed, it may ask you to run gh auth login. Declining the remote still leaves a working local voice home.

The same local setup is available from your terminal:

python3 ~/voice-forge/skills/voice-forge/scripts/vf.py setup --path ~/.voice-forge --profile default-en

Creating a remote is a separate, optional step:

python3 ~/voice-forge/skills/voice-forge/scripts/vf.py github --name voice-forge-private

Agents may need permission to write to the voice home from another project. Grant access through your client's normal controls, or start the agent from the voice home. See what is stored and synchronized.

Other agents and plain chat

An Agent Skills client can load skills/voice-forge/ and the shortcut folders. Use its skill name or plain language if the client has no slash or dollar notation. File access, PDF extraction and separate reviewers depend on that client.

ChatGPT and claude.ai can use a flattened packet built from one profile:

cd ~/voice-forge
python3 scripts/build.py packet --profile default-en

The output is dist/voice-forge-default-en.md. Attach it to a chat or put it in a project or custom GPT. It contains private profile text and may contain samples and rewrites. Do not publish it. Scripts cannot run inside a plain chat; the agent returns changes for you to save manually. Rebuild the packet after training. More about packet limits.

Update or remove linked skills

cd ~/voice-forge
git pull
python3 scripts/build.py install

Existing links see updated files immediately. Running install also registers any new shortcuts. Update a plugin installation through Claude Code's plugin controls.

For an earlier --copy installation, inspect the installed directories first. Replacing them removes any local edits there. Choose the same target clients you originally installed, preview the replacement, then refresh deliberately. This example refreshes Codex copies:

python3 scripts/build.py install --agents codex --copy --force --dry-run
python3 scripts/build.py install --agents codex --copy --force

Use claude,codex,kilo if those are the copied targets you intend to replace. A plain install --copy skips existing directories and does not refresh them.

To preview removal of links owned by this checkout:

python3 scripts/build.py uninstall --dry-run

Remove --dry-run to unlink them. This command removes matching symlinks; it does not remove installed copies or erase your voice home. Continue with your first profile.