Installation

System Requirements

• Node.js: 18.0.0 or higher
• npm: 7.0.0 or higher (comes with Node.js)
• Git: 2.0.0 or higher (recommended for versioned docs)

Check your versions:

node --version  # Should be v18.0.0 or higher
npm --version   # Should be 7.0.0 or higher
git --version   # Should be 2.0.0 or higher

Installation Methods

npm

Install globally to use across all projects:

npm install -g cortex-tms@latest

Verify installation:

cortex-tms --version
# Output: 4.x.x (current version)

Usage:

cd your-project
cortex-tms init

Pros: Use cortex-tms command anywhere, fastest execution (no download on each run)

Cons: Requires global install permissions, may conflict with other versions

npx

Run without installing globally:

npx cortex-tms@latest init

Verify (will download and run):

npx cortex-tms@latest --version
# Output: 4.x.x (current version)

Pros: No global installation required, always run specific version, no permission issues

Cons: Slower (downloads on first run per session), must specify version each time

Create an Alias

Add to ~/.bashrc or ~/.zshrc:

alias cortex="npx cortex-tms@latest"

Then use: cortex init

pnpm

Install with pnpm as your package manager:

pnpm add -g cortex-tms@latest

Usage:

cortex-tms init

Pros: Faster installs with pnpm’s symlink strategy, disk space efficient, monorepo-friendly

Yarn

Install with Yarn as your package manager:

yarn global add cortex-tms@latest

Usage:

cortex-tms init

Caution

Ensure Yarn’s global bin is in your PATH:

export PATH="$(yarn global bin):$PATH"

Verifying Installation

After installation, verify Cortex TMS is working:

# Check version
cortex-tms --version

# View help
cortex-tms --help

# Test initialization (in a test directory)
mkdir test-project && cd test-project
cortex-tms init

You should see:

🤖 Cortex TMS - AI-Powered Project Scaffolding
? Select project type: (Use arrow keys)
❯ Basic - Essential docs only
  Full - Complete scaffolding
  Custom - Choose features

Troubleshooting Installation

Command not found: cortex-tms

Cause: npm’s global bin directory is not in your PATH.

Solution:

1. Find npm’s global bin path:

   npm config get prefix

2. Add it to your PATH (Linux/macOS):

   echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc

3. For Windows PowerShell:

   $env:Path += ";$(npm config get prefix)"

Permission denied when installing globally

Cause: npm lacks permissions to install global packages.

Solution 1: Use npx instead:

npx cortex-tms@latest init

Solution 2: Configure npm to use a user directory:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Now install globally
npm install -g cortex-tms@latest

Version mismatch or outdated version

Cause: Cached old version or multiple installations.

Solution:

1. Uninstall all versions:

   npm uninstall -g cortex-tms

2. Clear npm cache:

   npm cache clean --force

3. Reinstall specific version:

   npm install -g cortex-tms@latest

Windows-specific issues

Issue: Scripts disabled in PowerShell.

Solution: Enable script execution:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Updating Cortex TMS

To update to the latest version:

# Check current version
cortex-tms --version

# Update to latest
npm update -g cortex-tms

# Or install specific version
npm install -g cortex-tms@latest

Uninstalling

To remove Cortex TMS:

npm uninstall -g cortex-tms

Your project files created by Cortex TMS (like CLAUDE.md, NEXT-TASKS.md) will remain untouched.

Next Steps

Now that Cortex TMS is installed:

1. Initialize a project: Follow the Quick Start guide
2. Customize templates: (Coming soon)
3. Integrate with CI/CD: (Coming soon)

Getting Help

• Documentation: You’re reading it!
• GitHub Issues: Report bugs
• Discussions: Ask questions