forward-nexus
v2.3.0
Published
Forward Nexus, the CLI for the open agent ecosystem
Maintainers
fastforwardKeywords
Readme
Forward Nexus
Forward Nexus is the CLI for the open agent ecosystem.
Supports OpenCode, Claude Code, Codex, Cursor, and 41 more.
Forward Nexus installs and manages reusable AI agent customizations without forcing you to manually copy files into each agent's folder.
What It Installs
| Item | What it is | Typical destination |
| ----------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Skills | Reusable task-specific instructions packaged as SKILL.md directories | Agent skill folders such as .claude/skills/ or .github/skills/ |
| Instruction files | Repository-wide guidance such as .instructions.md files | .github/instructions/ |
| Custom agents | Repository-provided agent/chatmode definitions | .github/agents/ |
If you are new to the ecosystem, start with a skill install. That gives you the quickest end-to-end confirmation that your agent is picking up installed customizations.
Install
Forward Nexus requires Node.js 22 or newer.
# Try it without a global install
npx forward-nexus --help
# Or install it once and use the command directly
npm install -g forward-nexus
forward-nexus --helpQuick Start
# 1. Preview what a source repo offers
npx forward-nexus add vercel-labs/agent-skills --list
# 2. Install one skill
npx forward-nexus add vercel-labs/agent-skills --skill deploy-to-vercel
# 3. Confirm what is installed in the current project
npx forward-nexus listTo install repository instruction files or custom agents instead of skills:
npx forward-nexus add ./repo-with-customizations --instruction project-standards
npx forward-nexus add ./repo-with-customizations --custom-agent reviewerInstruction files and custom agents are always project-scoped. They can also pull in linked skills, instructions, or custom agents declared in frontmatter. In non-interactive runs, any linked skills default to the universal project target unless you pass --agent.
Source formats
<source> accepts several forms:
| Form | Example | Installs |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| GitHub/GitLab/Bitbucket shorthand | owner/repo, owner/repo/path, owner/repo@skill | A repo (optionally a subpath or single named skill) |
| Repo, directory, or file URL | https://github.com/owner/repo, .../tree/<ref>/<path>, .../blob/<ref>/<path>/SKILL.md, https://raw.githubusercontent.com/owner/repo/<ref>/<path>/SKILL.md | The repo, the directory's skills, or the single skill a blob/raw URL points at |
| Hosted single file | https://your-host/<name>/SKILL.md | One hosted skill (just that SKILL.md; ship resources/ via a repo or well-known endpoint) |
| Well-known endpoint | https://your-host (serving /.well-known/agent-skills/index.json) | Every skill the endpoint publishes |
| Local path | ./repo, ./repo/path, ./path/to/SKILL.md | A local directory's skills, or a single local SKILL.md |
Choosing what to install
When you run add <source> without naming items (no --skill/--instruction/--custom-agent), Forward Nexus shows a single grouped, searchable picker covering everything it found in the repo — skills, instruction files (including a top-level AGENTS.md), and custom agents — grouped under section headers. Type to filter, space to toggle, enter to confirm. --yes only assumes default answers — it does not pick what to install. To install everything without the picker, pass --all (it installs every skill, instruction, and custom agent the source offers, across every agent target — skills only when combined with --global); running non-interactively with several items and no --all errors instead of installing everything. A source offering a single item is installed without prompting. --global installs only skills, since instructions and custom agents are project-scoped.
Common Workflows
| Goal | Command | More detail |
| ---------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Browse installable items in a repo | npx forward-nexus add <source> --list | Getting started |
| Install one or more skills | npx forward-nexus add <source> --skill <name> | Command reference |
| Install repo instructions or custom agents | npx forward-nexus add <source> --instruction <name> | Customizations guide |
| See what is installed | npx forward-nexus list | Command reference |
| Search for skills | npx forward-nexus find typescript | Command reference |
| Inspect a skill before installing | npx forward-nexus info <source> [item] | Command reference |
| Check which items have updates available | npx forward-nexus outdated | Command reference |
| Update tracked items | npx forward-nexus update | Command reference |
| Check project drift before changing files | npx forward-nexus sync | Sync guide |
| Orient at session start (agents) in one call | npx forward-nexus context --toon | Command reference |
| Restore tracked items from lockfile | npx forward-nexus restore | Command reference |
| Sync node_modules skills and regenerate IDE files | npx forward-nexus sync-modules | Command reference |
| See which agents are supported and where they install | npx forward-nexus agents | Command reference |
| Add an agent target to everything already installed | npx forward-nexus agents add <agent> | Command reference |
| Drop an agent target from everything installed | npx forward-nexus agents remove <agent> | Command reference |
| Diagnose environment or auth issues | npx forward-nexus doctor | Troubleshooting |
| Install shell completions | npx forward-nexus completion zsh | Full command reference |
| Remove something you installed | npx forward-nexus remove <item> | Command reference |
| Set a persistent default (agent, version policy, color, …) | npx forward-nexus config set <key> <value> | Command reference |
Global Flags
These flags work on every command, including list and init:
| Flag | Short | What it does |
| ------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| --quiet | -q | Hides the banner and diagnostic progress/status, and runs non-interactively. Primary data is still printed: read commands like list, find, info, agents, outdated, doctor, config get/list, completion, and the read-only add <source> --list browse still emit their result on stdout (clig.dev: --quiet never swallows the data you asked for). Mutating commands (add, init, update, sync, …) are silent on success. On failure the rendered output is written to stderr with a non-zero exit code, so failures are never silent. --json output is never suppressed. |
| --verbose | — | Print extra sub-steps as the command runs |
| --debug | -d | Everything --verbose shows, plus the full error stack trace to stderr on failure (also via DEBUG=forward-nexus:*) |
| --no-color | — | Disable ANSI color |
| --cwd <dir> | -C | Run as if started in <dir> (place after the command, like every flag) |
Mutating commands (add, remove, update, sync, restore, sync-modules, …) additionally accept -y, --yes (assume default answers, run non-interactively) and -n, --dry-run (preview what would change without writing; alias --plan).
[!NOTE] Scope Differences for
--global/-g:
- In configuration commands (
config),--global/-gtargets user-wide configuration (e.g.,~/.config/forward-nexus/config.json), and--localtargets project-scoped configuration (e.g.,./.forward-nexus.json).- In skill/customization commands (
add,remove,list,update,outdated),--global/-gtargets globally installed skills (e.g.,~/.agents/skills/), while--project(or the default) targets project-scoped skills (e.g.,./.agents/skills/). Customizations (instructions and custom agents) are always project-scoped.
# Run update quietly (errors only) from another directory
npx forward-nexus update --quiet -C /path/to/project
# Show verbose output
npx forward-nexus sync --verboseCommon add Options
| Option | Use it when |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| -s, --skill <skill> | You want specific skills instead of an interactive selection (repeat or comma-separate for multiple: --skill a --skill b or --skill a,b) |
| --instruction <file> | You want standalone repository instruction files (repeat or comma-separate for multiple) |
| --custom-agent <file> | You want standalone repository custom agent files (repeat or comma-separate for multiple) |
| -a, --agent <agent> | Target specific agents (e.g., claude-code, codex). See Available Agents (repeat or comma-separate for multiple: --agent a --agent b or --agent a,b) |
| -g, --global | You want skills available across projects instead of only in the current repo |
| -y, --yes | You are running non-interactively (assume default answers). Pair with --all or --skill/--instruction/--custom-agent to choose what installs |
| --all | You want every item the repo offers, no prompts — every skill, instruction, and custom agent (skills only when combined with --global). Installs to every agent unless you also pass --agent to target specific ones |
| -f, --force | You need to overwrite untracked files already sitting at an install path |
| --version-policy <exact\|patch\|minor> | You want to pin how future updates bump this item (default minor; also settable as a persistent default via config) |
| --copy | You want independent copies in each agent directory instead of symlinks from the canonical store. Symlinking is the default only when an install spans multiple agent directories; a single target directory is always copied (there is nothing to share) |
| --include-prerelease | You want update to consider prerelease tags for this item, not just stable releases |
| --full-depth | The source nests more skills beneath a root SKILL.md; search every subdirectory instead of stopping at the root skill |
--instruction and --custom-agent can install linked dependencies alongside the item you selected. See the Customizations guide when you want the exact frontmatter rules.
Automation and Planning
Forward Nexus now supports machine-readable output and plan mode across the main mutating workflows.
--json implies non-interactive: every command that supports it accepts --json with no -y and
never prompts, in any shell. The one exception is opening a pull request — sync --push --json and
sync --both --json still require -y to confirm, and exit 2 without it, so a PR is never opened
unattended. Every --json command emits the same envelope —
{ schemaVersion, command, ok, exitCode, errorCode, stdout, stderr, data } — with the
command-specific result under data and errorCode naming the failure kind (null on success, e.g.
auth/network/usage/conflict on failure) so automation can branch without scraping stderr.
See docs/commands.md for the full contract.
AI agents: prefer --toon. Every command that accepts --json also accepts --toon, which
emits the identical envelope serialized in TOON — a lossless
re-encoding at roughly 40% fewer tokens. --toon is the recommended machine format for agents;
--json remains the compatibility fallback. The two are mutually exclusive (passing both exits 2),
and --toon flips non-interactive mode just like --json. See
docs/commands.md
for the TOON contract.
# Preview an install without writing files
npx forward-nexus add vercel-labs/agent-skills --skill deploy-to-vercel -y --dry-run
npx forward-nexus add vercel-labs/agent-skills --skill deploy-to-vercel -y -n # -n is short for --dry-run
# Get JSON output for automation-friendly installs (no -y needed)
npx forward-nexus add vercel-labs/agent-skills --skill deploy-to-vercel --json
# Agents: the same envelope in TOON — ~40% fewer tokens (preferred)
npx forward-nexus add vercel-labs/agent-skills --skill deploy-to-vercel --toon
# Preview tracked updates before applying them
npx forward-nexus update -p -y --dry-run
# Preview project sync pulls and pushes before mutating files or GitHub
npx forward-nexus sync --both --dry-runCurrent automation-facing commands with --json and --dry-run / --plan / -n support:
add(also:a,install,i)remove(also:rm,r)outdated(also:check) — read-only, exits 0 alwaysupdate(also:upgrade,up)syncrestore(compatibility alias:experimental_install)sync-modules(also:generate-ide; compatibility alias:experimental_sync)migrateinit
outdated --json, find --json (requires a query), info --json, sync --json, list --json, doctor --json, and agents --json are read-only. As with every --json command, none requires -y.
Exit codes:
0success (also returned when an interactive prompt is dismissed with Escape or declined)1command failure — a well-formed request that matched nothing (every named item is unknown), an authentication failure, a safety refusal, or a runtime error. For the all-unknown case,add/remove/updatelist the unmatched names undernotFoundin--json(the same field the partial case5uses)2usage error — unknown command or flag, invalid option value, missing required argument4conflict — an install collision blocked completion (e.g. an untracked file already occupies the target path; re-run with--forceto overwrite)5partial success — a multi-item operation where some named items matched and others did not (e.g.add --skill real,ghost,remove real ghost,update real ghost); the matches are applied, the misses are reported (and listed undernotFoundin--json).outdatedis read-only and always exits0, reporting misses as a warning instead130aborted — an interactive prompt aborted with Ctrl+C (128+SIGINT, the shell convention), so&&-chains stop after an abort; Escape and declined confirmations stay0
There is no dedicated auth exit code (3 is intentionally unused): a credential failure surfaces as 1 with actionable re-auth guidance in the error message, because git and the registry return the same response for a private repo you can't access as for a missing one.
Scripts that only branch on success vs failure can treat any non-zero code as a failure; the distinct codes let automation tell a usage mistake and a conflict apart.
Learn More
- Docs index
- Getting started
- Tutorials
- Glossary
- Full command reference
- Sync guide
- Customizations and skill authoring
- Troubleshooting
Contributing
Setup, the day-to-day commands, test conventions, the changeset policy, and the review process are documented in CONTRIBUTING.md.
Available Agents
Run npx forward-nexus agents to print this list from the CLI (add --json for machine-readable output) without leaving your terminal.
| Agent | --agent | Project Path | Global Path |
|-------|-----------|--------------|-------------|
| Amp, Kimi Code CLI, Replit, Universal | amp, kimi-cli, replit, universal | .agents/skills/ | ~/.config/agents/skills/ |
| Antigravity | antigravity | .agents/skills/ | ~/.gemini/antigravity/skills/ |
| Augment | augment | .agents/skills/ | ~/.augment/skills/ |
| IBM Bob | bob | .bob/skills/ | ~/.bob/skills/ |
| Claude Code | claude-code | .claude/skills/ | ~/.claude/skills/ |
| OpenClaw | openclaw | .agents/skills/ | ~/.openclaw/skills/ |
| Cline, Warp | cline, warp | .agents/skills/ | ~/.agents/skills/ |
| CodeBuddy | codebuddy | .codebuddy/skills/ | ~/.codebuddy/skills/ |
| Codex | codex | .agents/skills/ | ~/.codex/skills/ |
| Command Code | command-code | .agents/skills/ | ~/.commandcode/skills/ |
| Continue | continue | .continue/skills/ | ~/.continue/skills/ |
| Cortex Code | cortex | .cortex/skills/ | ~/.snowflake/cortex/skills/ |
| Crush | crush | .agents/skills/ | ~/.config/crush/skills/ |
| Cursor | cursor | .agents/skills/ | ~/.cursor/skills/ |
| Deep Agents | deepagents | .agents/skills/ | ~/.deepagents/agent/skills/ |
| Droid | droid | .factory/skills/ | ~/.factory/skills/ |
| Firebender | firebender | .agents/skills/ | ~/.firebender/skills/ |
| Gemini CLI | gemini-cli | .agents/skills/ | ~/.gemini/skills/ |
| GitHub Copilot | github-copilot | .agents/skills/ | ~/.copilot/skills/ |
| Goose | goose | .agents/skills/ | ~/.config/goose/skills/ |
| Junie | junie | .junie/skills/ | ~/.junie/skills/ |
| iFlow CLI | iflow-cli | .iflow/skills/ | ~/.iflow/skills/ |
| Kilo Code | kilo | .agents/skills/ | ~/.kilocode/skills/ |
| Kiro CLI | kiro-cli | .kiro/skills/ | ~/.kiro/skills/ |
| Kode | kode | .kode/skills/ | ~/.kode/skills/ |
| MCPJam | mcpjam | .agents/skills/ | ~/.mcpjam/skills/ |
| Mistral Vibe | mistral-vibe | .agents/skills/ | ~/.vibe/skills/ |
| Mux | mux | .agents/skills/ | ~/.mux/skills/ |
| OpenCode | opencode | .agents/skills/ | ~/.config/opencode/skills/ |
| OpenHands | openhands | .agents/skills/ | ~/.openhands/skills/ |
| Pi | pi | .agents/skills/ | ~/.pi/agent/skills/ |
| Qoder | qoder | .qoder/skills/ | ~/.qoder/skills/ |
| Qwen Code | qwen-code | .qwen/skills/ | ~/.qwen/skills/ |
| Roo Code | roo | .agents/skills/ | ~/.roo/skills/ |
| Trae | trae | .trae/skills/ | ~/.trae/skills/ |
| Trae CN | trae-cn | .trae/skills/ | ~/.trae-cn/skills/ |
| Windsurf | windsurf | .agents/skills/ | ~/.codeium/windsurf/skills/ |
| Zencoder | zencoder | .agents/skills/ | ~/.zencoder/skills/ |
| Neovate | neovate | .neovate/skills/ | ~/.neovate/skills/ |
| Pochi | pochi | .agents/skills/ | ~/.pochi/skills/ |
| AdaL | adal | .adal/skills/ | ~/.adal/skills/ |
[!NOTE] Kiro CLI users: After installing skills, manually add them to your custom agent's
resourcesin.kiro/agents/<agent>.json:{ "resources": ["skill://.kiro/skills/**/SKILL.md"] }
Discovery Paths Reference
- Root directory (if it contains
SKILL.md) skills/skills/.curated/skills/.experimental/skills/.system/.agents/skills/.claude/skills/.cline/skills/.codebuddy/skills/.codex/skills/.commandcode/skills/.continue/skills/.github/skills/.goose/skills/.iflow/skills/.junie/skills/.kilocode/skills/.kiro/skills/.mux/skills/.neovate/skills/.opencode/skills/.openhands/skills/.pi/skills/.qoder/skills/.roo/skills/.trae/skills/.windsurf/skills/.zencoder/skills/