Configuration Reference

Every knob, dial, and secret lever. Configure the framework to match your chaos.

Configuration Files

Loaded Vibes uses several configuration files, each with a specific purpose:

File	Purpose
loaded-vibes.config.json	Main framework configuration
.vscode/settings.json	VS Code workspace settings
.vscode/mcp.json	MCP server configuration
.env.local	Environment variables

loaded-vibes.config.json

The main configuration file with all framework options:

loaded-vibes.config.jsonjson

{
  "$schema": "https://loaded-vibes.dev/schemas/config.json",
  "version": "1.0.0",
  "stack": "fullstack",
  
  "features": {
    "ai": {
      "enabled": true,
      "provider": "copilot",
      "model": "gpt-4o",
      "contextWindow": 128000
    },
    "telemetry": {
      "enabled": true,
      "anonymous": true,
      "endpoint": null
    },
    "upgrades": {
      "strategy": "merge",
      "autoBackup": true,
      "checkFrequency": "weekly"
    },
    "checkpoints": {
      "enabled": true,
      "maxCount": 50,
      "pruneAfterDays": 30
    }
  },
  
  "devcycles": {
    "active": [
      "init", "scaffold", "config", "verify",
      "data", "auth", "test", "validate",
      "features", "debug", "security", "perf",
      "observe", "review", "docs",
      "cicd", "deploy", "updates"
    ],
    "custom": [],
    "defaults": {
      "skipCheckpoints": false,
      "requireApproval": ["deploy", "security"],
      "parallelExecution": false
    }
  },
  
  "paths": {
    "src": "src",
    "tests": "tests",
    "docs": "docs",
    "artifacts": ".github",
    "state": ".loaded-vibes"
  },
  
  "git": {
    "conventionalCommits": true,
    "signCommits": false,
    "protectedBranches": ["main", "production"],
    "defaultBranch": "main"
  },
  
  "security": {
    "firewall": {
      "enabled": true,
      "blockPatterns": [
        "rm -rf",
        "DROP TABLE",
        "DELETE FROM * WHERE 1=1"
      ],
      "requireApproval": ["destructive", "external"]
    },
    "secrets": {
      "scanEnabled": true,
      "blockOnDetection": true
    }
  },
  
  "logging": {
    "level": "info",
    "format": "ndjson",
    "retention": "30d",
    "destinations": ["file", "console"]
  }
}

Section Reference

features.ai

Property	Type	Default	Description
enabled	boolean	true	Enable AI features
provider	string	"copilot"	AI provider: copilot, openai, anthropic
model	string	"gpt-4o"	Model to use
contextWindow	number	128000	Context window size

features.upgrades

Property	Type	Default	Description
strategy	string	"merge"	mirror, merge, or sandbox
autoBackup	boolean	true	Create backup before upgrade
checkFrequency	string	"weekly"	never, daily, weekly, monthly

VS Code Settings

Workspace settings that integrate with GitHub Copilot and the editor:

.vscode/settings.jsonjson

{
  // Copilot Integration
  "github.copilot.chat.codeGeneration.instructions": [
    { "file": ".github/copilot-instructions.md" }
  ],
  "github.copilot.chat.testGeneration.instructions": [
    { "file": ".github/instructions/testing.instructions.md" }
  ],
  "github.copilot.chat.reviewSelection.instructions": [
    { "file": ".github/instructions/review.instructions.md" }
  ],
  
  // Editor Settings
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit",
    "source.organizeImports": "explicit"
  },
  
  // TypeScript
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.updateImportsOnFileMove.enabled": "always",
  
  // Files
  "files.exclude": {
    "node_modules": true,
    ".next": true,
    ".loaded-vibes/cache": true
  },
  
  // Search
  "search.exclude": {
    "**/node_modules": true,
    "**/.loaded-vibes/logs": true
  }
}

MCP Configuration

Model Context Protocol server configuration for AI tool access:

.vscode/mcp.jsonjson

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-filesystem"],
      "env": {
        "ALLOWED_PATHS": "./src,./tests,./docs"
      }
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-git"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-memory"],
      "env": {
        "MEMORY_PATH": "./.loaded-vibes/memory"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-github"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-postgres"],
      "env": {
        "DATABASE_URL": "${env:DATABASE_URL}"
      }
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-fetch"]
    },
    "sequentialthinking": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-sequentialthinking"]
    }
  }
}

⚠️

Environment variables

MCP servers use environment variable substitution with ${env:VAR_NAME} syntax. Ensure sensitive values are stored in .env.local and never committed.

Environment Variables

.env.localbash

# Required
GITHUB_TOKEN=ghp_your_token_here

# Database (if using postgres MCP)
DATABASE_URL=postgresql://user:pass@localhost:5432/db

# Optional: Custom endpoints
LV_API_ENDPOINT=https://api.loaded-vibes.dev

# Optional: Logging
LV_LOG_LEVEL=debug
LV_TRACE=true

# Optional: Telemetry override
LV_NO_TELEMETRY=true

Toolset Configuration

Toolsets define available MCP tools and their configuration:

.github/toolsets/default.toolset.jsoncjson

{
  "$schema": "https://loaded-vibes.dev/schemas/toolset.json",
  "name": "default",
  "description": "Default toolset for general development",
  
  "tools": {
    "filesystem": {
      "enabled": true,
      "config": {
        "allowedPaths": ["src/**", "tests/**", "docs/**"],
        "blockedPaths": ["node_modules/**", ".env*", "*.key"],
        "maxFileSize": "10MB"
      }
    },
    "git": {
      "enabled": true,
      "config": {
        "allowCommit": true,
        "allowPush": false,
        "requireConventionalCommits": true,
        "protectedBranches": ["main", "production"]
      }
    },
    "github": {
      "enabled": true,
      "config": {
        "allowPR": true,
        "allowIssues": true,
        "allowReviews": true,
        "requireReviewers": true,
        "minReviewers": 1
      }
    },
    "postgres": {
      "enabled": true,
      "config": {
        "readOnly": false,
        "allowMigrations": false,
        "maxQueryTime": "30s",
        "blockedOperations": ["DROP DATABASE", "TRUNCATE"]
      }
    },
    "memory": {
      "enabled": true,
      "config": {
        "maxEntries": 1000,
        "ttl": "7d"
      }
    },
    "fetch": {
      "enabled": true,
      "config": {
        "allowedDomains": ["*.github.com", "*.npmjs.org"],
        "maxResponseSize": "5MB",
        "timeout": "30s"
      }
    }
  },
  
  "securityPolicy": {
    "requireApproval": ["destructive", "external"],
    "blockPatterns": [
      "rm -rf /",
      "DROP TABLE",
      "DELETE FROM .* WHERE 1=1"
    ],
    "auditAll": true
  }
}

DevCycle Manifest

Custom DevCycle definitions in the config:

loaded-vibes.config.json (custom devcycles)json

{
  "devcycles": {
    "custom": [
      {
        "id": "migrate-legacy",
        "name": "Legacy Migration",
        "description": "Migrate code from legacy systems",
        "instruction": ".github/instructions/migrate.instructions.md",
        "prompt": ".github/prompts/migrate.prompt.md",
        "toolset": ".github/toolsets/migrate.toolset.jsonc",
        "phases": ["analyze", "design", "implement", "validate"],
        "checkpoints": {
          "required": ["design", "validate"],
          "autoCreate": true
        }
      }
    ]
  }
}

Configuration Precedence

Configuration values are resolved in this order (later overrides earlier):

Built-in defaults
Global config (~/.loaded-vibes/config.json)
Project config (loaded-vibes.config.json)
Environment variables
CLI flags

✨

View effective config

Use lv config list --resolved to see the final merged configuration with all overrides applied.

Next Steps

Learn how to customize the framework for your specific needs, or explore Running DevCycles to put your configuration to work.