Warp Terminal Integration Guide

November 15, 2025 · View on GitHub

Complete guide for integrating SWORDSwarm with Warp terminal's AI-powered development environment.

Table of Contents

Overview

Warp is a modern, Rust-based terminal that brings AI-powered capabilities to command-line development. When combined with SWORDSwarm's 88+ specialized agents and hardware acceleration, it creates an unparalleled development environment.

Key Benefits

  • 15x faster command discovery - Natural language → executable commands
  • 7-10x faster execution - NPU hardware acceleration with ShadowGit
  • Context-aware AI - Warp AI knows your SWORDSwarm agents and capabilities
  • Team collaboration - Share workflows via Warp Drive
  • Interactive runbooks - Jupyter-like notebooks in your terminal

Architecture

┌─────────────────────────────────────────────────────┐
│              Warp Terminal (UI Layer)               │
│  • AI Command Suggestions (#)                       │
│  • AI Agent Mode (Ctrl+Shift+I)                     │
│  • Workflows (Ctrl+Shift+R)                         │
│  • Warp Drive (Team Knowledge)                      │
└─────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────┐
│           Warp AI Bridge (Integration Layer)        │
│  • Model Context Protocol (MCP)                     │
│  • Command Suggestions                              │
│  • Context Management                               │
└─────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────┐
│         SWORDSwarm (Agent Orchestration)            │
│  • 88+ Specialized Agents                           │
│  • NPU Hardware Acceleration                        │
│  • Parallel Agent Execution                         │
└─────────────────────────────────────────────────────┘

Installation

Prerequisites

  • Operating System: macOS or Linux
  • Python: 3.11+
  • SWORDSwarm: Installed and configured
  • Warp Terminal: Latest version

Step 1: Install Warp

macOS:

brew install --cask warp

Linux:

# Download from https://www.warp.dev/
# Or use package manager if available

Step 2: Setup SWORDSwarm Integration

cd ~/SWORDSwarm
./scripts/setup_warp.sh

This script will:

  1. ✓ Copy workflows to ~/.warp/workflows/
  2. ✓ Install SWORDSwarm theme to ~/.warp/themes/
  3. ✓ Setup launch configuration
  4. ✓ Initialize Warp AI Bridge
  5. ✓ Create shell aliases
  6. ✓ Configure MCP context

Step 3: Verify Installation

# Open Warp terminal
warp

# List workflows
# Press Ctrl+Shift+R
# You should see 9+ SWORDSwarm workflows

# Test AI Bridge
python3 integrations/warp_ai_bridge.py

# Expected output:
# 🚀 Warp AI + SWORDSwarm Integration Enabled
# 📊 88 agents available
# ...

Configuration

Global Configuration

Edit ~/.warp/warp_config.yaml:

# Warp Global Settings
theme: "swordswarm"
default_shell: "/bin/bash"
ai_model: "mixed"  # Uses best from OpenAI, Anthropic, Google

# SWORDSwarm Integration
swordswarm:
  enabled: true
  ai_bridge_path: "~/SWORDSwarm/integrations/warp_ai_bridge.py"
  auto_detect_hardware: true
  enable_mcp: true

Project Configuration

Create .warp/project_config.yaml in your project:

# Project-Specific Warp Configuration
name: "My Project"
description: "Project with SWORDSwarm integration"

# Environment variables
environment:
  CLAUDE_AGENTS_LOG_LEVEL: "INFO"
  OPENAI_API_KEY: "${OPENAI_API_KEY}"
  PYTHONPATH: "./agents/src/python"

# Startup commands
startup_commands:
  - echo "🗡️ SWORDSwarm Development Environment"
  - python3 integrations/warp_ai_bridge.py

# Preferred agents for this project
preferred_agents:
  - python-internal
  - security
  - testbed
  - deployer

Hardware Acceleration

Enable automatic hardware detection:

# .warp/hardware_config.yaml
hardware:
  auto_detect: true
  prefer_npu: true
  prefer_avx512: true

  # Fallback order
  acceleration_priority:
    - NPU
    - AVX-512
    - AVX2
    - SSE4.2
    - Scalar

Workflows

Workflows are parameterized, reusable commands that you can save and share.

Using Workflows

Access workflows:

  • Press Ctrl+Shift+R in Warp
  • Search for workflow name
  • Fill in parameters
  • Execute

Built-in SWORDSwarm Workflows

1. invoke_agent.yaml

Execute any SWORDSwarm agent with a custom task.

name: "Invoke SWORDSwarm Agent"
arguments:
  - agent_name: "python-internal"
  - task: "analyze code quality"

Example usage:

  1. Ctrl+Shift+R → Search "Invoke"
  2. Select "Invoke SWORDSwarm Agent"
  3. Enter agent name: security
  4. Enter task: audit authentication module
  5. Execute

2. parallel_agents.yaml

Run multiple agents simultaneously for faster results.

name: "Run Parallel Agent Tasks"
arguments:
  - agent1: "architect"
  - task1: "design system"
  - agent2: "security"
  - task2: "analyze security"
  - agent3: "database"
  - task3: "design schema"

3. shadowgit_analyze.yaml

NPU-accelerated git repository analysis (7-10x faster).

name: "ShadowGit NPU-Accelerated Analysis"
arguments:
  - repo_path: "."

Creating Custom Workflows

Create ~/.warp/workflows/my_workflow.yaml:

---
name: "My Custom Workflow"
command: "python3 -c \"from claude_agents import get_agent; agent = get_agent('{{agent}}'); result = agent.execute(task='{{task}}'); print(result)\""
tags: ["custom", "swordswarm"]
description: "Your custom workflow description"
author: "Your Name"
arguments:
  - name: agent
    description: "Agent to invoke"
    default_value: "python-internal"
  - name: task
    description: "Task description"
    default_value: "analyze code"

Best practices:

  • Use clear, descriptive names
  • Add helpful descriptions
  • Provide sensible default values
  • Tag workflows for easy discovery
  • Test workflows before sharing

Sharing Workflows via Warp Drive

# 1. Create workflow in your project
.warp/workflows/team_workflow.yaml

# 2. Commit to version control
git add .warp/workflows/
git commit -m "Add team workflow"
git push

# 3. Team members pull and Warp automatically syncs
git pull
# Warp Drive automatically discovers new workflows

AI Bridge

The Warp AI Bridge provides intelligent, context-aware command suggestions.

How It Works

  1. Context Analysis: Scans SWORDSwarm agents and capabilities
  2. Hardware Detection: Identifies NPU, AVX-512, AVX2 support
  3. MCP Integration: Creates Model Context Protocol file
  4. Command Mapping: Maps natural language to SWORDSwarm commands
  5. Team Knowledge: Shares context via Warp Drive

Model Context Protocol (MCP)

MCP provides context to Warp AI about your development environment.

Location: ~/.warp/mcp_context.json

Content:

{
  "system": "SWORDSwarm",
  "version": "v42.0",
  "agent_count": 88,
  "agents": {
    "python-internal": {
      "available": true,
      "capabilities": ["code_analysis", "optimization", "debugging"]
    },
    "security": {
      "available": true,
      "capabilities": ["vulnerability_scanning", "audit", "compliance"]
    }
  },
  "hardware_acceleration": {
    "npu_available": true,
    "avx512_available": true,
    "acceleration_active": true
  }
}

Using Warp AI with MCP

Type # followed by natural language:

# list available agents
# → python3 -c "from claude_agents import list_agents; ..."

# run security audit on auth module
# → python3 -c "from claude_agents import get_agent; agent = get_agent('security'); ..."

# check if NPU acceleration is working
# → python3 hardware/milspec_hardware_analyzer.py

Warp AI knows:

  • ✓ All 88+ SWORDSwarm agents
  • ✓ Each agent's capabilities
  • ✓ Hardware acceleration status
  • ✓ Common command patterns
  • ✓ Project-specific context

Command Suggestions API

Programmatically get command suggestions:

from integrations.warp_ai_bridge import WarpAIBridge

bridge = WarpAIBridge()
bridge.initialize()

# Get command suggestion
cmd = bridge.suggest_command("run security audit")
print(cmd)
# → python3 -c "from claude_agents import get_agent; ..."

# Get agent context
context = bridge.get_agent_context_for_warp("python-internal")
print(context)
# → {"capabilities": [...], "usage_examples": [...], ...}

Themes

SWORDSwarm Theme

Professional dark theme optimized for AI development.

Features:

  • High contrast for readability
  • Cyan accents for agent activity
  • Green highlights for hardware acceleration
  • Dark background for reduced eye strain
  • Vibrant colors for syntax highlighting

Color Palette:

# Primary
background: "#0a0e14"
foreground: "#e6e1cf"
accent: "#00d4ff"

# Status
success: "#00ff88"
error: "#ff3333"
warning: "#ffcc00"
info: "#00d4ff"

# Syntax
keyword: "#00d4ff"
string: "#00ff88"
number: "#ffcc00"
comment: "#6c7680"

Applying Theme

Method 1: Settings UI

  1. Open Warp
  2. Settings → Appearance → Theme
  3. Select "SWORDSwarm Dark"

Method 2: Configuration File

# ~/.warp/warp_config.yaml
theme: "swordswarm"

Method 3: Command Line

cp .warp/themes/swordswarm.yaml ~/.warp/themes/
warp --theme swordswarm

Creating Custom Themes

Create ~/.warp/themes/my_theme.yaml:

---
name: "My Custom Theme"
accent: "#ff00ff"
background: "#1a1a1a"
foreground: "#ffffff"
details: darker

terminal_colors:
  normal:
    black: "#000000"
    red: "#ff0000"
    green: "#00ff00"
    yellow: "#ffff00"
    blue: "#0000ff"
    magenta: "#ff00ff"
    cyan: "#00ffff"
    white: "#ffffff"

Team Collaboration

Warp Drive

Warp Drive enables team collaboration through shared workflows, environment variables, and knowledge.

Shared Workflows

Setup:

  1. Create .warp/ directory in project repository
  2. Add workflows to .warp/workflows/
  3. Commit and push to version control
  4. Team members automatically get workflows

Example:

# Project structure
my-project/
  .warp/
    workflows/
      deploy_staging.yaml
      run_tests.yaml
      security_scan.yaml
    notebooks/
      onboarding.md
      deployment_guide.md

Environment Variables

Share environment configuration:

# .warp/launch_configurations/production.yaml
name: "Production Environment"
environment:
  ENV: "production"
  LOG_LEVEL: "ERROR"
  DATABASE_URL: "${DATABASE_URL}"
  API_KEY: "${API_KEY}"

Security: Use ${VAR} syntax to reference local environment variables, never commit secrets!

Team Knowledge

Create shared notebooks for:

  • Onboarding new team members
  • Common development workflows
  • Debugging procedures
  • Deployment guides
  • Security protocols

Advanced Topics

Multi-Model AI

Warp uses models from OpenAI, Anthropic, and Google:

# Advanced AI configuration
ai:
  mode: "mixed"  # or "openai", "anthropic", "google"

  # Model selection strategy
  command_suggestions:
    model: "fast"  # GPT-3.5 or Claude Haiku
    max_tokens: 100
    temperature: 0.1

  code_generation:
    model: "powerful"  # GPT-4 or Claude Opus
    max_tokens: 2000
    temperature: 0.2

  context_analysis:
    model: "balanced"  # GPT-4-turbo or Claude Sonnet
    max_tokens: 1000
    temperature: 0.15

Hardware-Aware Workflows

Workflows that adapt based on hardware:

---
name: "Adaptive Git Analysis"
command: |
  if python3 -c "from hooks.shadowgit.python import ShadowGitAVX2; sg = ShadowGitAVX2(); print(sg.hw_caps)" | grep -q "NPU"; then
    echo "Using NPU acceleration (7-10x speedup)"
    python3 -c "from hooks.shadowgit.python import ShadowGitAVX2; sg = ShadowGitAVX2(); sg.analyze_repository('.')"
  else
    echo "Using AVX2 acceleration"
    python3 -c "from hooks.shadowgit.python import ShadowGitAVX2; sg = ShadowGitAVX2(); sg.analyze_repository('.')"
  fi

Integration with CI/CD

Use SWORDSwarm workflows in CI/CD:

# .github/workflows/swordswarm-qa.yml
name: SWORDSwarm QA

on: [push, pull_request]

jobs:
  quality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Setup SWORDSwarm
        run: |
          ./install
          source venv/bin/activate

      - name: Security Audit
        run: |
          python3 -c "from claude_agents import get_agent; \
          agent = get_agent('security'); \
          result = agent.execute(task='audit PR changes'); \
          print(result)"

      - name: Code Quality
        run: |
          python3 -c "from claude_agents import get_agent; \
          agent = get_agent('linter'); \
          result = agent.execute(task='analyze code quality'); \
          print(result)"

      - name: Run Tests
        run: pytest -v --cov=claude_agents

Troubleshooting

Common Issues

1. Warp AI Not Suggesting Commands

Symptoms: Typing # doesn't show SWORDSwarm-specific suggestions

Solutions:

# Re-initialize AI Bridge
python3 integrations/warp_ai_bridge.py

# Check MCP context file
cat ~/.warp/mcp_context.json

# Verify agents are available
python3 -c "from claude_agents import list_agents; print(list_agents())"

# Restart Warp

2. Workflows Not Appearing

Symptoms: Ctrl+Shift+R doesn't show SWORDSwarm workflows

Solutions:

# Check workflow directory
ls ~/.warp/workflows/

# Re-run setup
./scripts/setup_warp.sh

# Manually copy workflows
cp -r .warp/workflows/* ~/.warp/workflows/

# Restart Warp

3. Theme Not Applying

Symptoms: SWORDSwarm theme not available or not applying

Solutions:

# Verify theme file exists
ls ~/.warp/themes/swordswarm.yaml

# Copy theme manually
cp .warp/themes/swordswarm.yaml ~/.warp/themes/

# Apply via settings
# Warp → Settings → Appearance → Theme → SWORDSwarm Dark

# Restart Warp

4. NPU Acceleration Not Detected

Symptoms: Hardware acceleration not working

Solutions:

# Check hardware capabilities
python3 hardware/milspec_hardware_analyzer.py

# Enable NPU turbo mode
bash hardware/enable-npu-turbo.sh

# Verify NPU driver
lspci | grep -i npu

# Check kernel modules
lsmod | grep npu

5. Permission Errors

Symptoms: Cannot access workflows or configuration

Solutions:

# Fix permissions
chmod -R 755 ~/.warp/

# Check ownership
ls -la ~/.warp/

# Re-run setup with proper permissions
./scripts/setup_warp.sh

Debug Mode

Enable debug logging:

# Set debug environment variable
export WARP_DEBUG=1
export CLAUDE_AGENTS_LOG_LEVEL=DEBUG

# Run Warp
warp

# Check logs
tail -f ~/.warp/logs/debug.log

Getting Help

Conclusion

Warp + SWORDSwarm creates a powerful, AI-enhanced development environment that combines:

  • ⚡ 15x faster command discovery with natural language
  • 🚀 7-10x faster execution with NPU acceleration
  • 🎯 Context-aware intelligence with MCP
  • 👥 Seamless team collaboration
  • 🏆 Best-in-class developer experience

Get started:

./scripts/setup_warp.sh
# Then press Ctrl+Shift+R in Warp!

Built with ❤️ for developers. Powered by Warp + SWORDSwarm.