Configuration

Configuration

Complete configuration guide for customizing Agentwise to your needs.

Overview

Agentwise provides extensive configuration options to customize agent behavior, performance settings, and integrations. This guide covers all available configuration parameters and best practices.

Configuration Structure

Agentwise uses a hierarchical configuration system with the following order of precedence:

1. Environment Variables (highest priority)
2. Command Line Arguments
3. Configuration Files (.claude/config.json)
4. Default Settings (lowest priority)

Core Configuration

Basic Settings

Create .claude/config.json in your project root:

{
  "version": "1.0.0",
  "project": {
    "name": "my-project",
    "type": "web-application",
    "description": "Full-stack web application"
  },
  "agents": {
    "maxConcurrent": 3,
    "timeout": 300,
    "retryAttempts": 2
  },
  "tokens": {
    "budget": 100000,
    "optimization": true,
    "compression": "adaptive"
  }
}

Environment Variables

# Core settings
export AGENTWISE_API_KEY="your-api-key"
export AGENTWISE_PROJECT_PATH="/path/to/project"
export AGENTWISE_LOG_LEVEL="info"

# Agent configuration
export AGENTWISE_MAX_AGENTS=3
export AGENTWISE_AGENT_TIMEOUT=300
export AGENTWISE_RETRY_ATTEMPTS=2

# Token optimization
export AGENTWISE_TOKEN_BUDGET=100000
export AGENTWISE_OPTIMIZE_TOKENS=true
export AGENTWISE_COMPRESSION_MODE="adaptive"

# MCP integration
export AGENTWISE_MCP_SERVERS_PATH=".claude/mcp_servers"
export AGENTWISE_MCP_AUTO_INSTALL=true

Agent Configuration

Agent Pool Settings

{
  "agents": {
    "pool": {
      "frontend": {
        "enabled": true,
        "maxInstances": 2,
        "priority": "high",
        "specializations": ["react", "vue", "angular"]
      },
      "backend": {
        "enabled": true,
        "maxInstances": 2,
        "priority": "high",
        "specializations": ["nodejs", "python", "go"]
      },
      "database": {
        "enabled": true,
        "maxInstances": 1,
        "priority": "medium",
        "specializations": ["postgresql", "mongodb", "redis"]
      },
      "devops": {
        "enabled": true,
        "maxInstances": 1,
        "priority": "low",
        "specializations": ["docker", "kubernetes", "aws"]
      },
      "testing": {
        "enabled": true,
        "maxInstances": 1,
        "priority": "medium",
        "specializations": ["jest", "cypress", "playwright"]
      }
    }
  }
}

Custom Agent Registration

Create custom agent definitions in .claude/agents/:

// .claude/agents/mobile-specialist.json
{
  "name": "mobile-specialist",
  "description": "Mobile application development expert",
  "capabilities": [
    "React Native development",
    "Flutter development",
    "iOS/Android platform specifics",
    "Mobile UI/UX patterns"
  ],
  "tools": [
    "react-native-cli",
    "flutter",
    "xcode",
    "android-studio"
  ],
  "priority": "medium",
  "maxInstances": 1
}

Token Optimization

Optimization Strategies

{
  "tokens": {
    "budget": 100000,
    "optimization": {
      "enabled": true,
      "strategy": "adaptive",
      "compression": {
        "level": "medium",
        "preserveQuality": true
      },
      "caching": {
        "enabled": true,
        "ttl": 3600,
        "strategy": "lru"
      },
      "contextSharing": {
        "enabled": true,
        "maxSharedSize": 10000
      }
    }
  }
}

Budget Management

{
  "tokens": {
    "budgets": {
      "total": 100000,
      "perAgent": {
        "frontend": 25000,
        "backend": 25000,
        "database": 15000,
        "devops": 15000,
        "testing": 15000,
        "research": 5000
      },
      "reserve": 10000,
      "alerts": {
        "warning": 0.8,
        "critical": 0.95
      }
    }
  }
}

MCP Server Configuration

Auto-Discovery

{
  "mcp": {
    "autoDiscovery": true,
    "serversPath": ".claude/mcp_servers",
    "configPath": ".claude/claude_desktop_config.json",
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
      },
      "sqlite": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./database.sqlite"]
      },
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
}

Manual Server Configuration

{
  "mcp": {
    "servers": {
      "custom-api": {
        "command": "python",
        "args": ["-m", "custom_mcp_server"],
        "env": {
          "API_KEY": "${CUSTOM_API_KEY}",
          "BASE_URL": "https://api.example.com"
        },
        "cwd": "/path/to/server"
      }
    }
  }
}

Performance Configuration

Execution Settings

{
  "performance": {
    "parallel": {
      "enabled": true,
      "maxConcurrentTasks": 5,
      "loadBalancing": "round-robin"
    },
    "caching": {
      "enabled": true,
      "strategy": "memory",
      "maxSize": "100MB",
      "ttl": 3600
    },
    "optimization": {
      "lazy": true,
      "preload": ["common", "templates"],
      "compression": true
    }
  }
}

Resource Limits

{
  "resources": {
    "memory": {
      "max": "2GB",
      "warning": "1.5GB"
    },
    "cpu": {
      "maxUsage": 80,
      "throttle": true
    },
    "disk": {
      "maxTempSize": "1GB",
      "cleanup": true
    }
  }
}

Logging and Monitoring

Log Configuration

{
  "logging": {
    "level": "info",
    "format": "json",
    "output": {
      "console": true,
      "file": {
        "enabled": true,
        "path": ".claude/logs/agentwise.log",
        "maxSize": "10MB",
        "rotation": "daily"
      }
    },
    "categories": {
      "agents": "debug",
      "tokens": "info",
      "performance": "warn",
      "errors": "error"
    }
  }
}

Monitoring Settings

{
  "monitoring": {
    "enabled": true,
    "dashboard": {
      "port": 3001,
      "host": "localhost",
      "auth": false
    },
    "metrics": {
      "collection": true,
      "interval": 30,
      "retention": "24h"
    },
    "alerts": {
      "webhook": "https://hooks.slack.com/...",
      "conditions": {
        "highTokenUsage": 0.9,
        "agentTimeout": 600,
        "errorRate": 0.1
      }
    }
  }
}

Security Configuration

Access Control

{
  "security": {
    "apiKeys": {
      "required": true,
      "rotation": "30d"
    },
    "fileAccess": {
      "allowedPaths": [
        "./src",
        "./public",
        "./config"
      ],
      "deniedPaths": [
        ".env",
        "secrets/",
        "*.key"
      ]
    },
    "network": {
      "allowedDomains": [
        "api.anthropic.com",
        "github.com",
        "npm.js.org"
      ],
      "proxy": {
        "enabled": false,
        "url": "http://proxy.company.com:8080"
      }
    }
  }
}

Project Templates

Template Configuration

{
  "templates": {
    "path": ".claude/templates",
    "default": "web-application",
    "available": {
      "web-application": {
        "description": "Full-stack web application",
        "agents": ["frontend", "backend", "database", "testing"],
        "structure": "templates/web-app.json"
      },
      "api-service": {
        "description": "REST API service",
        "agents": ["backend", "database", "testing"],
        "structure": "templates/api-service.json"
      },
      "mobile-app": {
        "description": "Mobile application",
        "agents": ["mobile", "backend", "testing"],
        "structure": "templates/mobile-app.json"
      }
    }
  }
}

CLI Configuration

Command Defaults

{
  "cli": {
    "defaults": {
      "verbose": false,
      "dry-run": false,
      "auto-confirm": false
    },
    "aliases": {
      "dev": "start --mode development",
      "prod": "start --mode production",
      "test": "run test --watch"
    },
    "hooks": {
      "pre-start": "npm install",
      "post-build": "npm run test"
    }
  }
}

Configuration Validation

Schema Validation

Agentwise validates configuration against JSON schemas:

# Validate configuration
npm run config:validate

# Generate configuration template
npm run config:init

# Update configuration
npm run config:update

Common Validation Errors

1. Invalid Agent Names: Use lowercase with hyphens
2. Token Budget: Must be positive integer
3. File Paths: Must be absolute or relative to project root
4. MCP Servers: Commands must be executable

Environment-Specific Configuration

Development

{
  "environment": "development",
  "debug": true,
  "agents": {
    "maxConcurrent": 2
  },
  "tokens": {
    "budget": 50000
  },
  "logging": {
    "level": "debug"
  }
}

Production

{
  "environment": "production",
  "debug": false,
  "agents": {
    "maxConcurrent": 5
  },
  "tokens": {
    "budget": 200000
  },
  "logging": {
    "level": "warn"
  },
  "monitoring": {
    "enabled": true
  }
}

Configuration Best Practices

Performance Optimization

1. Agent Pool Sizing: Start with 3 concurrent agents
2. Token Budget: Set realistic limits based on project size
3. Caching: Enable for repetitive tasks
4. Monitoring: Always enable in production

Security Considerations

1. API Keys: Use environment variables, never commit to code
2. File Access: Restrict to necessary directories
3. Network Access: Whitelist allowed domains
4. Logging: Avoid logging sensitive data

Maintenance

1. Regular Updates: Update agent definitions as needed
2. Performance Monitoring: Review metrics regularly
3. Configuration Backup: Version control your config
4. Documentation: Keep custom configurations documented

Troubleshooting Configuration

Common Issues

# Check configuration validity
npm run config:check

# View effective configuration
npm run config:show

# Reset to defaults
npm run config:reset

# Merge configurations
npm run config:merge development.json

Configuration Debugging

# Enable debug logging
export AGENTWISE_LOG_LEVEL=debug

# Validate MCP servers
npm run mcp:validate

# Test agent connectivity
npm run agents:test

---

For more information, see Installation, Agent System, or Troubleshooting.