wingman.config.json

The global config lives at .wingman/wingman.config.json. It controls logging, providers, gateway settings, search, voice, and agent bindings.

JSON Schema

Published schema URL:

https://getwingmanai.com/schemas/wingman.config.schema.json

Add this to your config file for editor validation/autocomplete:

{
  "$schema": "https://getwingmanai.com/schemas/wingman.config.schema.json"
}

Example

{
  "logLevel": "info",
  "defaultAgent": "wingman",
  "recursionLimit": 5000,
  "modelRetry": {
    "enabled": true,
    "maxRetries": 2,
    "backoffFactor": 2,
    "initialDelayMs": 1000,
    "maxDelayMs": 60000,
    "jitter": true,
    "onFailure": "continue"
  },
  "toolRetry": {
    "enabled": false,
    "maxRetries": 2,
    "backoffFactor": 2,
    "initialDelayMs": 1000,
    "maxDelayMs": 60000,
    "jitter": true,
    "onFailure": "continue",
    "tools": ["internet_search", "web_crawler"]
  },
  "humanInTheLoop": {
    "enabled": false,
    "interruptOn": {
      "command_execute": {
        "allowedDecisions": ["approve", "reject"],
        "description": "Command execution requires approval"
      },
      "internet_search": false
    }
  },
  "search": {
    "provider": "duckduckgo",
    "maxResults": 5
  },
  "voice": {
    "provider": "web_speech",
    "defaultPolicy": "off",
    "webSpeech": {
      "voiceName": "Samantha",
      "lang": "en-US",
      "rate": 1
    },
    "elevenlabs": {
      "voiceId": "voice_123",
      "modelId": "eleven_turbo_v2",
      "stability": 0.45,
      "similarityBoost": 0.7
    }
  },
  "cli": {
    "theme": "default",
    "outputMode": "auto"
  },
  "skills": {
    "provider": "hybrid",
    "repositories": [
      { "owner": "RussellCanfield", "name": "wingman-ai" },
      { "owner": "your-org", "name": "your-skills-repo" }
    ],
    "repositoryOwner": "legacy-owner",
    "repositoryName": "legacy-repo",
    "skillsDirectory": "skills"
  },
  "browser": {
    "profilesDir": ".wingman/browser-profiles",
    "extensionsDir": ".wingman/browser-extensions",
    "defaultProfile": "trading",
    "transport": "auto",
    "defaultExtensions": ["wingman"],
    "profiles": {
      "trading": ".wingman/browser-profiles/trading"
    },
    "extensions": {
      "wingman": ".wingman/browser-extensions/wingman"
    }
  },
  "gateway": {
    "host": "127.0.0.1",
    "port": 18789,
    "fsRoots": ["."],
    "auth": {
      "mode": "token",
      "token": "optional-token",
      "allowTailscale": false
    },
    "controlUi": {
      "enabled": true,
      "port": 18790,
      "pairingRequired": true,
      "allowInsecureAuth": false
    },
    "dynamicUiEnabled": true,
    "adapters": {
      "discord": {
        "enabled": true,
        "token": "DISCORD_BOT_TOKEN",
        "mentionOnly": true,
        "allowedGuilds": ["123"],
        "allowedChannels": ["456"],
        "sessionCommand": "!session",
        "responseChunkSize": 1900
      }
    }
  },
  "agents": {
    "list": [
      {
        "id": "wingman",
        "name": "Wingman",
        "default": true,
        "workspace": ".",
        "agentDir": ".wingman/agents/wingman",
        "model": "anthropic:claude-sonnet-4-5"
      }
    ],
    "bindings": [
      {
        "agentId": "wingman",
        "match": {
          "channel": "discord",
          "guildId": "123",
          "peer": { "kind": "channel", "id": "456" }
        }
      }
    ]
  },
  "mcp": {
    "servers": [
      {
        "name": "local-tools",
        "transport": "stdio",
        "command": "node",
        "args": ["/path/to/server.js"]
      }
    ]
  }
}

Agents list vs filesystem discovery

Agent definitions are discovered from the filesystem under .wingman/agents/<agent-id>/ (via agent.json or agent.md). The agents block in wingman.config.json is optional, but it is the gateway’s source of truth for routing and metadata.

Why you would use agents.list:

Set a default agent for routing when no binding matches.
Provide friendly display names in the Control UI / HTTP API.
Assign a per‑agent workspace so an agent can run against a different repo.

Why you would use agents.bindings:

Route inbound messages (Discord, Teams, web UI, webhooks) to a specific agent by channel/peer metadata.

Minimal example:

{
  "agents": {
    "list": [
      { "id": "wingman", "name": "Wingman", "default": true, "workspace": "." },
      { "id": "researcher", "name": "Researcher", "workspace": "../notes" }
    ],
    "bindings": [
      {
        "agentId": "researcher",
        "match": { "channel": "discord", "peer": { "kind": "dm", "id": "123" } }
      }
    ]
  }
}

Key sections

logLevel: debug | info | warn | error | silent
defaultAgent: agent name used when --agent is omitted
recursionLimit: maximum reasoning steps for agents (default 5000)
summarization: conversation-history compression settings
modelRetry: retry failed model calls with backoff
toolRetry: retry failed tool calls (optionally scoped to named tools)
humanInTheLoop: per-tool approval/interrupt policies
search: provider and max results for the internet_search tool
voice: global voice settings; can be overridden per-agent
cli: CLI theme and output mode (auto | interactive | json)
skills: skill sources (hybrid, clawhub, or github), ordered GitHub repos, optional legacy GitHub repo fallback, and local install directory
browser: named persistent profile + extension settings for browser_control
gateway: host, port, auth, control UI, adapters
agents: optional list/bindings used by the gateway for routing
mcp: global MCP server definitions

For adapter-specific fields and setup:

Browser settings

browser keys in wingman.config.json control profile and extension mappings for browser_control:

profilesDir, profiles, defaultProfile, transport
extensionsDir, extensions, defaultExtensions
relay.enabled, relay.host, relay.port, relay.requireAuth, relay.authToken, relay.maxMessageBytes

For full setup steps, login bootstrap, command examples, and troubleshooting, see: Browser Automation, Playwright Setup, and Relay Setup.

Summarization settings

Wingman uses DeepAgents' built-in conversation summarization middleware so long-running threads are compressed instead of continuously expanding context.

Omit summarization entirely to use DeepAgents' out-of-the-box defaults.
summarization.enabled: explicitly turn conversation compression on/off.
summarization.maxTokensBeforeSummary: optional Wingman override for the summarization trigger threshold.
summarization.messagesToKeep: optional Wingman override for how many recent messages stay verbatim after summarization.

Retry middleware settings

Wingman can apply LangChain retry middleware for model and tool failures.

modelRetry.enabled (default true): enables modelRetryMiddleware.
toolRetry.enabled: enables toolRetryMiddleware.
Shared retry controls:
- maxRetries
- backoffFactor
- initialDelayMs
- maxDelayMs
- jitter
- onFailure (continue or error)
toolRetry.tools: optional list of tool names to restrict retries to.

Human-in-the-loop settings

Use humanInTheLoop.interruptOn to configure tool-specific approval:

true: require approval with default decisions.
false: auto-approve this tool.
object:
- allowedDecisions: any of approve, edit, reject
- description: optional custom approval prompt
- argsSchema: optional argument schema for edit flows

HITL is active only when:

humanInTheLoop.enabled is true, and
interruptOn contains at least one tool entry.

If interruptOn is empty, no runtime interruptions are applied.

Example:

{
  "humanInTheLoop": {
    "enabled": true,
    "interruptOn": {
      "command_execute": {
        "allowedDecisions": ["approve", "edit", "reject"],
        "description": "Review shell commands before running them.",
        "argsSchema": {
          "command": {
            "type": "string",
            "description": "Updated command to execute"
          }
        }
      },
      "background_terminal": {
        "allowedDecisions": ["approve", "reject"],
        "description": "Require approval before starting terminal sessions."
      },
      "internet_search": false
    }
  }
}

Practical pattern:

Gate high-impact tools (command_execute, background_terminal, node_run).
Keep low-risk read tools unblocked unless your environment requires review.
Use description to explain why approval is required for each tool.

For agent-specific configuration, see the Agents guide.

#wingman.config.json

#JSON Schema

#Example

#Agents list vs filesystem discovery

#Key sections

#Browser settings

#Summarization settings

#Retry middleware settings

#Human-in-the-loop settings