A dynamic package manager for OpenCode skills, tools, commands, and agents. Neo lets you discover, load, install, and share packages from git-based registries -- like npm/npx for your AI coding agent.
Skills -- Instructions loaded into the agent's context (dynamically loadable)
Tools -- TypeScript functions the agent can call (security-scanned before install/execute)
Commands -- Prompt templates accessible via /neo <name> (dynamically loadable)
Agents -- Custom agent definitions with system prompts and permissions
Neo injects a system prompt section into the agent's context so it knows about the neo_* tools and will use them for package-related requests. It also auto-discovers project-local registries at .opencode/neo/registry.json -- any project can ship its own packages without requiring configuration.
Install
npm install opencode-neonpm run setup -w opencode-neo
The setup script adds "opencode-neo" to your opencode.json plugin list and copies the /neo bootstrap command to ~/.config/opencode/commands/. Restart OpenCode to activate.
npm run setup:check -w opencode-neo # verify installationnpm run setup:uninstall -w opencode-neo # remove
See TUTORIAL.md for a full walkthrough of using Neo inside an OpenCode session, with example prompts covering setup, discovery, dynamic loading, installation, profiles, authoring, team sync, and updates.
Tools reference
Neo registers 15 tools with OpenCode (plus the /neo bootstrap command):
Discovery
Tool
Description
neo_search
Search registries by keyword, name, or tag. Filter by type.
neo_suggest
Analyze the current project and suggest relevant packages based on detected languages, frameworks, and tools.
Dynamic loading
Tool
Description
neo_load
Load a skill or command into the current session without installing. Skills inject instructions into conversation context. Commands return templates to follow.
neo_exec
Execute a tool from a registry without installing. The source is security-scanned and the user is prompted for permission before execution.
/neo <command> [args]
Bootstrap command. Run any registry command dynamically, like npx.
Package management
Tool
Description
neo_install
Install a package or bundle persistently. Supports scope: "global" or "project", bundle: true for bundles, lock: true to pin versions. Tools are security-scanned before install.
neo_remove
Uninstall a package and remove its files.
neo_update
Update installed packages. Supports preview: true to diff before applying, force: true to override version locks.
neo_list
List installed, available, or updatable packages. Filter by type.
Registry management
Tool
Description
neo_registries
Add, remove, list, refresh registries, or discover linked registries via federation.
Authoring
Tool
Description
neo_create
Scaffold a new registry or add a package (skill/tool/command/agent) to an existing one.
neo_publish
Import a local skill, tool, command, or agent into a registry directory. The reverse of neo_install.
neo_validate
Validate a registry directory: checks registry.json, verifies all packages exist and pass validation, reports orphaned files.
Configuration
Tool
Description
neo_setup
Export or import a Neo setup file for team onboarding. Includes registries, packages, and profiles.
neo_profile
Manage named profiles -- sets of packages that activate together. Create, delete, activate, or list profiles.
neo_config
View the merged config, initialize project-level config, or show config file paths.
Tools involve executing code. Neo handles this with:
Static security scanning -- Pattern-based analysis before install or execute. Detects eval, child_process, filesystem access, network calls, env access, obfuscation, and more. Findings are surfaced to the agent and user.
Permission gates -- neo_exec, neo_install, neo_remove, and neo_update all use OpenCode's built-in permission system (context.ask()). The user approves before anything runs.
Path validation -- All package names and registry names are validated against a safe pattern. Path traversal attacks from malicious registries are blocked.
TOCTOU protection -- Tool source is read once and passed through the scan-then-execute pipeline. The scanned code is the executed code.
The samples/registry/ directory contains a complete example registry with one of each package type, a bundle, and a federation link. Use it as a template:
cp -r samples/registry ./my-registry
CLI
Neo includes a command-line tool for operations outside of OpenCode sessions -- managing registries, validating packages, scaffolding, and more. After installation, the opencode-neo command is available:
opencode-neo --help
Quick reference
# Setupopencode-neo setup # Install plugin + /neo commandopencode-neo setup --check # Verify installationopencode-neo setup --uninstall # Remove# Registriesopencode-neo registries list # List configured registriesopencode-neo registries add acme https://github.com/acme/packagesopencode-neo registries add local-reg ./path --localopencode-neo registries remove acmeopencode-neo registries refresh # Fetch latest from git registriesopencode-neo registries links # Discover federated registries# Packagesopencode-neo search terraform # Search by keywordopencode-neo search react --type skill # Filter by typeopencode-neo list # Installed packagesopencode-neo list --available # All available across registriesopencode-neo list --updates # Packages with newer versionsopencode-neo install k8s-debugging # Install a packageopencode-neo install k8s-toolkit --bundle # Install a bundleopencode-neo install critical-tool --lock # Install and pin versionopencode-neo install team-skill --project # Install to project scopeopencode-neo remove k8s-debugging # Uninstallopencode-neo update # Update all packagesopencode-neo update k8s-lint --preview # Preview changes before updatingopencode-neo update k8s-lint --force --lock # Force update locked, re-lock# Authoringopencode-neo create registry my-team ./my-team-registry [--no-git]opencode-neo create skill code-style ./my-team-registry --description "Coding conventions"opencode-neo create agent reviewer ./my-team-registry --description "Code reviewer"opencode-neo validate ./my-team-registry # Validate a registryopencode-neo publish ./skills/my-skill ./my-team-registry# Configurationopencode-neo config show # View merged configopencode-neo config init # Create .opencode/neo.jsonopencode-neo config paths # Show config file locationsopencode-neo suggest # Suggest packages for current projectopencode-neo suggest /path/to/project # Suggest for a specific project# Profilesopencode-neo profile listopencode-neo profile create frontend react-patterns,css-debug,component-gen [--description <d>]opencode-neo profile delete frontendopencode-neo profile show frontend# Team syncopencode-neo export # Export to neo-setup.jsonopencode-neo export my-team-setup.json # Export to custom pathopencode-neo import neo-setup.json # Import registries + packages
npm installnpm test # Run tests (vitest)npm run test:watch # Run tests in watch modenpm run lint # Run ESLintnpm run lint:fix # Auto-fix lint issuesnpx tsc --noEmit # Type checknpm run setup # Install into your local OpenCodenpm run setup:check # Verify installationnpm run setup:uninstall # Remove from OpenCode
Local development workflow
No build step is needed -- package.json points main at src/index.ts and OpenCode's Bun runtime loads TypeScript directly.