Global Agents

Global agents are AI specialists that you can execute from anywhere on your system, just like any other terminal command. Instead of navigating to a project directory to use an agent, you can invoke it from any location.

What are Global Agents?

Global agents transform Claude Code agents into standalone CLI commands:

Regular Agent: Only works in the directory where installed (.claude/agents/)
Global Agent: Works from any directory, like npm, git, or docker

System-Wide Access

Run from any directory without navigating to project

Auto Context Detection

Automatically detects project type and includes relevant files

Standalone Execution

No need for Claude Code to be open

Script Integration

Use in npm scripts, CI/CD, and shell scripts

How Global Agents Work

Installation Process

Download agent from GitHub

Store in ~/.claude-code-templates/agents/

Generate executable wrapper script

Install to system bin directory (/usr/local/bin or ~/.claude-code-templates/bin)

Add to PATH (if needed)

Execution Flow

You run: security-auditor "check this code"

Wrapper script:

Loads agent system prompt from ~/.claude-code-templates/agents/security-auditor.md
Detects project context (language, framework)
Auto-includes relevant files
Calls Claude CLI with agent context

Claude executes with agent persona and project awareness

Creating Global Agents

Basic Creation

npx claude-code-templates@latest --create-agent security-auditor

Output:

🤖 Creating global agent: security-auditor
🌍 Installing to system directory (immediately available)
📥 Downloading agent from GitHub...
✅ Agent downloaded successfully
✅ Global agent 'security-auditor' created successfully!

📦 Usage:
  security-auditor "your prompt here"

🎉 Ready to use immediately! No setup required.
💡 Works in scripts, npm tasks, CI/CD, etc.

Now you can run from anywhere:

cd ~/projects/my-app
security-auditor "audit this codebase for vulnerabilities"

With Category Path

If the agent name is ambiguous, use the full category path:

npx claude-code-templates@latest --create-agent development-team/frontend-developer

Creating Multiple Global Agents

Create several agents at once:

# Create security suite
npx claude-code-templates@latest --create-agent security-auditor
npx claude-code-templates@latest --create-agent penetration-tester
npx claude-code-templates@latest --create-agent code-reviewer

Using Global Agents

Basic Usage

<agent-name> "your prompt"

Examples:

security-auditor "check this file for SQL injection vulnerabilities"

Auto-Context Detection

Global agents automatically detect your project type and include relevant files:

cd ~/projects/my-react-app
frontend-developer "add error boundary to this component"

The agent automatically:

Detects React project (from package.json)
Includes src/, components/, pages/ directories
Understands React patterns and conventions
Can read files using the Read tool

Supported Project Types:

JavaScript/Node: Detects from package.json, includes src/, lib/, components/
Python: Detects from requirements.txt or pyproject.toml, includes *.py files
Go: Detects from go.mod, includes *.go, cmd/, internal/, pkg/
Rust: Detects from Cargo.toml, includes src/, Cargo.toml
React/Vue/Next.js: Framework detection from dependencies

Explicit File Selection

Override auto-detection by specifying files:

security-auditor --file auth.js --file database.js "check these files"

Directory Targeting

code-reviewer --dir src/components "review all components"

Disable Auto-Detection

For general advice without project context:

security-auditor --no-auto "explain OAuth 2.0 best practices"

Verbose Mode

See what the agent is doing:

security-auditor --verbose "audit this code"

Outputs:

🔍 DEBUG MODE - Command Details:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📝 User Input: audit this code
📁 Project Context: Auto-detected
🎯 Final Prompt Length: 234 characters
🤖 System Prompt Preview: You are a security auditor...
⚡ Claude Command: claude -p "audit this code..." --system-prompt "..."
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Managing Global Agents

List Installed Agents

npx claude-code-templates@latest --list-agents

Output:

📋 Installed Global Agents:

✅ Found 3 global agent(s):

  ✅ security-auditor (🌍 system)
      Usage: security-auditor "your prompt"
      Created: 2/28/2026

  ✅ frontend-developer (👤 user)
      Usage: frontend-developer "your prompt"
      Created: 2/27/2026

  ✅ code-reviewer (🌍 system)
      Usage: code-reviewer "your prompt"
      Created: 2/26/2026

🌟 Global Usage:
  • Run from any directory: <agent-name> "prompt"
  • List agents: npx claude-code-templates@latest --list-agents
  • Remove agent: npx claude-code-templates@latest --remove-agent <name>

Remove an Agent

npx claude-code-templates@latest --remove-agent security-auditor

Output:

🗑️ Removing global agent: security-auditor
✅ Removed system executable: security-auditor
✅ Removed agent file: security-auditor.md
🎉 Global agent 'security-auditor' removed successfully!

Update an Agent

Fetch the latest version from GitHub:

npx claude-code-templates@latest --update-agent security-auditor

Output:

🔄 Updating global agent: security-auditor
🔄 Re-downloading latest version...
🌍 Installing to system directory (immediately available)
📥 Downloading agent from GitHub...
✅ Agent downloaded successfully
✅ Global agent 'security-auditor' created successfully!

Installation Locations

System Directory (Recommended)

If you have write access to /usr/local/bin, agents are installed there:

/usr/local/bin/security-auditor
~/.claude-code-templates/agents/security-auditor.md

✅ Advantages:

Immediately available in PATH
No shell configuration needed
Works in all terminals and IDEs

User Directory (Fallback)

If system directory is not writable, uses user directory:

~/.claude-code-templates/bin/security-auditor
~/.claude-code-templates/agents/security-auditor.md

⚠️ Requires PATH Setup: The CLI automatically adds to your shell config:

~/.bashrc or ~/.zshrc

# Claude Code Templates - Global Agents
export PATH="$HOME/.claude-code-templates/bin:$PATH"

Restart your terminal or run:

source ~/.bashrc  # or ~/.zshrc

Advanced Usage

In npm Scripts

Add global agents to package.json:

package.json

{
  "scripts": {
    "audit": "security-auditor 'audit for vulnerabilities'",
    "review": "code-reviewer 'review src/ for improvements'",
    "optimize": "performance-optimizer 'analyze bundle size'"
  }
}

npm run audit
npm run review
npm run optimize

In Shell Scripts

Create automation scripts:

pre-commit.sh

#!/bin/bash

# Run code review before commit
code-reviewer "review staged changes" || exit 1

# Check for security issues
security-auditor "scan staged files for vulnerabilities" || exit 1

echo "✅ Pre-commit checks passed"

chmod +x pre-commit.sh
./pre-commit.sh

In CI/CD Pipelines

name: Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Global Agent
        run: |
          npx claude-code-templates@latest --create-agent code-reviewer
          echo "$HOME/.claude-code-templates/bin" >> $GITHUB_PATH
      
      - name: Run Code Review
        run: code-reviewer "review all changes in this PR"

In Docker Containers

FROM node:20-alpine

WORKDIR /app

# Install global agent
RUN npx claude-code-templates@latest --create-agent security-auditor

ENV PATH="$HOME/.claude-code-templates/bin:$PATH"

COPY . .

# Use agent in container
RUN security-auditor "audit codebase"

CMD ["npm", "start"]

Custom Global Agents

You can create custom global agents by:

Creating a custom agent in .claude/agents/
Publishing to GitHub
Installing as global agent

Create Custom Agent

---
name: my-custom-agent
description: Custom agent for my specific needs
tools: Read, Write, Bash
model: sonnet
---

You are a custom agent that specializes in...

[Agent instructions here]

Publish to GitHub

# Push to your repo
git add .claude/agents/my-custom-agent.md
git commit -m "Add custom agent"
git push

Install as Global

Currently, global agents must be in the official repository. For custom agents:

Workaround: Manually create global wrapper:

# 1. Copy agent to global location
mkdir -p ~/.claude-code-templates/agents
cp .claude/agents/my-custom-agent.md ~/.claude-code-templates/agents/

# 2. Create wrapper script
cat > ~/.claude-code-templates/bin/my-custom-agent << 'EOF'
#!/usr/bin/env node

const { execSync } = require('child_process');
const fs = require('fs');
const os = require('os');
const path = require('path');

const agentPath = path.join(os.homedir(), '.claude-code-templates/agents/my-custom-agent.md');
const systemPrompt = fs.readFileSync(agentPath, 'utf8').replace(/^---[\s\S]*?---\n/, '').trim();
const userInput = process.argv.slice(2).join(' ');

if (!userInput) {
  console.error('Usage: my-custom-agent "your prompt"');
  process.exit(1);
}

const cmd = `claude -p "${userInput}" --system-prompt "${systemPrompt}"`;
execSync(cmd, { stdio: 'inherit' });
EOF

# 3. Make executable
chmod +x ~/.claude-code-templates/bin/my-custom-agent

# 4. Use it
my-custom-agent "your prompt"

Troubleshooting

Command Not Found

If you get command not found after creating a global agent:

$ security-auditor "test"
bash: security-auditor: command not found

Solutions:

Check PATH:

echo $PATH | grep -q ".claude-code-templates" && echo "PATH OK" || echo "PATH missing"

Add to PATH manually:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.claude-code-templates/bin:$PATH"

# Reload shell config
source ~/.bashrc  # or source ~/.zshrc

Use absolute path:

~/.claude-code-templates/bin/security-auditor "test"

Permission Denied

$ security-auditor "test"
bash: /usr/local/bin/security-auditor: Permission denied

Solution: Make executable:

sudo chmod +x /usr/local/bin/security-auditor

Claude CLI Not Found

Global agents require Claude CLI:

❌ Claude CLI not found in PATH
💡 Install Claude CLI: https://claude.ai/code
💡 Or install via npm: npm install -g @anthropic-ai/claude-code

Solution: Install Claude CLI:

npm install -g @anthropic-ai/claude-code

# Verify
claude --version

Agent File Not Found

❌ Agent file not found: ~/.claude-code-templates/agents/security-auditor.md

Solution: Recreate the global agent:

npx claude-code-templates@latest --create-agent security-auditor

Context Detection Not Working

If the agent doesn’t detect your project:

security-auditor --verbose "test"
# Check if "Project type: unknown" in debug output

Solution: Manually specify files:

security-auditor --file auth.js --file api.js "audit these files"

Best Practices

1. Name Agents Descriptively

✅ Good:

security-auditor
frontend-developer
api-documentation-writer

❌ Bad:

sa
dev
docs

2. Use for Specialized Tasks

Global agents work best for:

Security audits
Code reviews
Documentation generation
Performance analysis
Compliance checks

Not ideal for:

General chatting
Multi-step projects
Interactive sessions

3. Combine with Shell Aliases

~/.bashrc

alias audit="security-auditor"
alias review="code-reviewer"
alias docs="documentation-writer"

audit "check auth.js"
review "analyze src/"
docs "generate API docs"

4. Create Agent Sets

Install related agents together:

# Security suite
npx claude-code-templates@latest --create-agent security-auditor
npx claude-code-templates@latest --create-agent penetration-tester
npx claude-code-templates@latest --create-agent compliance-checker

# Development suite
npx claude-code-templates@latest --create-agent frontend-developer
npx claude-code-templates@latest --create-agent backend-developer
npx claude-code-templates@latest --create-agent devops-engineer

5. Document in Team README

README.md

## Global Agents

This project uses global Claude Code agents:

\`\`\`bash
# Setup (one-time)
npx claude-code-templates@latest --create-agent security-auditor
npx claude-code-templates@latest --create-agent code-reviewer

# Usage
security-auditor "audit for vulnerabilities"
code-reviewer "review my changes"
\`\`\`

Next Steps

Installing Components

Learn about regular component installation

Batch Installation

Install multiple components at once

Workflows

Create reusable installation workflows

Component Browser

Browse all available agents

Get Started

Core Concepts

Guides

Tools

Advanced

Documentation Index

​Global Agents

​What are Global Agents?

System-Wide Access

Auto Context Detection

Standalone Execution

Script Integration

​How Global Agents Work

​Creating Global Agents

​Basic Creation

​With Category Path

​Creating Multiple Global Agents

​Using Global Agents

​Basic Usage

​Auto-Context Detection

​Explicit File Selection

​Directory Targeting

​Disable Auto-Detection

​Verbose Mode

​Managing Global Agents

​List Installed Agents

​Remove an Agent

​Update an Agent

​Installation Locations

​System Directory (Recommended)

​User Directory (Fallback)

​Advanced Usage

​In npm Scripts

​In Shell Scripts

​In CI/CD Pipelines

​In Docker Containers

​Custom Global Agents

​Troubleshooting

​Command Not Found

​Permission Denied

​Claude CLI Not Found

​Agent File Not Found

​Context Detection Not Working

​Best Practices

​1. Name Agents Descriptively

​2. Use for Specialized Tasks

​3. Combine with Shell Aliases

​4. Create Agent Sets

​5. Document in Team README

​Next Steps

Installing Components

Batch Installation

Workflows

Component Browser

Global Agents

What are Global Agents?

How Global Agents Work

Creating Global Agents

Basic Creation

With Category Path

Creating Multiple Global Agents

Using Global Agents

Basic Usage

Auto-Context Detection

Explicit File Selection

Directory Targeting

Disable Auto-Detection

Verbose Mode

Managing Global Agents

List Installed Agents

Remove an Agent

Update an Agent

Installation Locations

System Directory (Recommended)

User Directory (Fallback)

Advanced Usage

In npm Scripts

In Shell Scripts

In CI/CD Pipelines

In Docker Containers

Custom Global Agents

Troubleshooting

Command Not Found

Permission Denied

Claude CLI Not Found

Agent File Not Found

Context Detection Not Working

Best Practices

1. Name Agents Descriptively

2. Use for Specialized Tasks

3. Combine with Shell Aliases

4. Create Agent Sets

5. Document in Team README

Next Steps