Skip to content

INSTALLATION.md

Latest commit

 

History

History
376 lines (269 loc) · 9.08 KB

INSTALLATION.md

File metadata and controls

376 lines (269 loc) · 9.08 KB

Installation Guide

One codebase works across five platforms - Claude Code, OpenCode, Codex CLI, Cursor, and Kiro. Install once, get the same workflows everywhere. State files adapt automatically to each platform's conventions.

Quick Navigation

Section Jump to
Claude Code Marketplace install (easiest)
npm Install Works for all platforms
Alternative Methods Local dev, manual
Verify Installation Check it worked
Prerequisites What you need first
Troubleshooting Common issues

Claude Code (Recommended)

Add the marketplace and install plugins directly in Claude Code:

/plugin marketplace add agent-sh/agentsys
/plugin install next-task@agentsys
/plugin install ship@agentsys
/plugin install deslop@agentsys
/plugin install audit-project@agentsys
/plugin install drift-detect@agentsys
/plugin install repo-intel@agentsys
/plugin install enhance@agentsys
/plugin install perf@agentsys
/plugin install sync-docs@agentsys
/plugin install learn@agentsys
/plugin install consult@agentsys
/plugin install debate@agentsys

Scopes (optional):

# User scope (default) - available in all projects
/plugin install next-task@agentsys

# Project scope - shared with team
/plugin install next-task@agentsys --scope project

All Platforms (npm Global Install)

Interactive installer for Claude Code, OpenCode, Codex CLI, Cursor, and Kiro:

npm install -g agentsys@latest
agentsys

Select one or more platforms when prompted:

Which platforms do you want to install for?

  1) Claude Code
  2) OpenCode
  3) Codex CLI

Your selection: 1 2

Non-Interactive Installation

Use flags for CI/scripts or when you know what you want:

# Single tool
agentsys --tool claude
agentsys --tool opencode
agentsys --tool codex

# Multiple tools
agentsys --tools "claude,opencode"
agentsys --tools claude,opencode,codex

CLI Flags

Flag Description
--tool <name> Install for single tool (claude, opencode, codex, cursor, kiro)
--tools <list> Install for multiple tools (comma-separated)
--development, --dev Development mode: install directly to ~/.claude/plugins
--no-strip, -ns Include model specifications (stripped by default)
--remove Remove local installation
--version, -v Show version
--help, -h Show help

Model Stripping

By default, model specifications (sonnet/opus/haiku) are stripped from agents when installing for OpenCode. This prevents errors when the target platform doesn't have the same model mappings configured.

Use --no-strip or -ns to include models if your OpenCode setup has proper model aliases.

Commands:

npm update -g agentsys       # Update
npm uninstall -g agentsys    # Remove npm package
agentsys --remove            # Clean up configs

Alternative Installation Methods

Development Mode (Claude Code)

For testing RC versions or local changes, use development mode:

agentsys --development

This bypasses the marketplace and installs plugins directly to ~/.claude/plugins/. To revert to the marketplace version:

rm -rf ~/.claude/plugins/*@agentsys
agentsys --tool claude

Local Development (Plugin Directory)

Plugins now live in standalone repos. To load a plugin locally, clone its repo:

git clone https://github.com/agent-sh/next-task.git
claude --plugin-dir ./next-task

Quick Dev Install (Contributors)

For contributors: install to all tools at once from local source:

node scripts/dev-install.js           # Install to all tools
node scripts/dev-install.js claude    # Install to Claude only
node scripts/dev-install.js --clean   # Remove all installations

This script uses local source files (not npm package), installs Claude in development mode, and strips models from OpenCode agents.

OpenCode / Codex CLI

Use the npm installer (recommended):

npm install -g agentsys@latest
agentsys

Select your platform when prompted. The installer configures:

Platform Config Location State Directory
Claude Code Marketplace .claude/
OpenCode ~/.config/opencode/ .opencode/
Codex CLI ~/.codex/ .codex/
Kiro .kiro/ (project-scoped) .kiro/

Note: Codex uses $ prefix for skills (e.g., $next-task instead of /next-task).

Verify Installation

Claude Code

/help

You should see commands:

  • /next-task - Master workflow orchestrator
  • /ship - Complete PR workflow
  • /deslop - AI slop cleanup
  • /audit-project - Multi-agent code review
  • /drift-detect - Plan drift detection
  • /repo-intel - Unified static analysis
  • /enhance - Enhancement analyzer suite
  • /perf - Performance investigation workflow
  • /sync-docs - Documentation sync
  • /learn - Topic research and learning guides
  • /consult - Cross-tool AI consultation
  • /debate - Structured AI dialectic with verdict
  • /web-ctl - Browser automation and web interaction
  • /skillers - Workflow pattern learning and automation suggestions
  • /onboard - Codebase onboarding
  • /can-i-help - Contributor guidance
  • /release - Versioned release with ecosystem detection
  • /agnix - Linter for AI agent configs
  • /prepare-delivery - Pre-ship validation checks
  • /gate-and-ship - Gated shipping workflow

OpenCode / Codex

Type the command name and it should be recognized:

  • /next-task (OpenCode) or $next-task (Codex)

Local Repo Diagnostics (optional)

If you're running from the repo, you can verify platform detection and tool availability:

npm run detect   # Platform detection (CI, deploy, project type)
npm run verify   # Tool availability + versions

Prerequisites

Required

  • Git - Version control

    git --version

  • Node.js 18+ - For library functions

Recommended (Repo Intel)

  • agent-analyzer - Used by /repo-intel for static analysis. Installed automatically via npm.

Required for GitHub Workflows

  • GitHub CLI (gh) - For PR operations and issue discovery 
    # Install
brew install gh        # macOS
winget install GitHub.cli  # Windows

# Authenticate
gh auth login

# Verify
gh auth status

Optional (Auto-Detected)

These tools are detected automatically if present:

  • Railway CLI, Vercel CLI, Netlify CLI (for deployments)
  • GitLab CLI (glab) for GitLab workflows

Managing Plugins

Update Marketplace

/plugin marketplace update agentsys

Update Plugins

/plugin update next-task@agentsys

Disable/Enable

/plugin disable next-task@agentsys
/plugin enable next-task@agentsys

Uninstall

/plugin uninstall next-task@agentsys

# Or remove marketplace entirely
/plugin marketplace remove agentsys

Local Installation Update

cd path/to/agentsys
git pull origin main

Troubleshooting

Commands Don't Appear

  1. Check marketplace is added:

    /plugin marketplace list

  2. Check plugin is installed:

    /plugin list

  3. Restart Claude Code after installation

"Marketplace not found"

The repository must be public or you need authentication:

# For private repos, ensure gh is authenticated
gh auth status

Plugin Install Fails

Try adding the full GitHub URL:

/plugin marketplace add https://github.com/agent-sh/agentsys.git

"GitHub CLI not found"

Required for /ship and GitHub-based workflows:

brew install gh  # macOS
winget install GitHub.cli  # Windows

gh auth login

Platform-Specific Notes

Claude Code

  • Plugins installed via marketplace are cached locally
  • Use --scope project to share plugins with your team
  • State stored in .claude/

OpenCode

  • MCP server provides workflow tools
  • Slash commands defined in ~/.config/opencode/commands/
  • State stored in .opencode/

Codex CLI

  • Uses $ prefix instead of / for commands
  • Skills defined in ~/.codex/skills/
  • State stored in .codex/

Kiro

  • Project-scoped: installs to .kiro/ in your project root
  • Commands become steering files in .kiro/steering/ with inclusion: manual
  • Skills use standard SKILL.md format in .kiro/skills/
  • Agents converted to JSON in .kiro/agents/
  • Reads AGENTS.md and .kiro/steering/*.md for instructions
  • Note: Kiro's subagent spawning is experimental (max 4). Workflows with parallel Task() calls (e.g., next-task Phase 9 with 4-10 reviewers) automatically fall back to 2 sequential combined reviewers (reviewer-quality-security, reviewer-perf-test)

Getting Help

gh issue create --repo agent-sh/agentsys \
  --title "Installation: [description]" \
  --body "Environment: [Claude Code/OpenCode/Codex], OS: [...]"