Your settings file "${settingsValue}" will be ignored.

Error message

   Your settings file "${settingsValue}" will be ignored.

What it means

Second line of the --settings interception warning: it echoes the value following --settings (the settings file path the user passed) and states that this file will be ignored, because happy strips the flag/value before spawning Claude.

Source

Thrown at packages/happy-cli/src/index.ts:684

          const key = envArg.substring(0, eqIndex)
          const value = envArg.substring(eqIndex + 1)
          options.claudeEnvVars = options.claudeEnvVars || {}
          options.claudeEnvVars[key] = value
        } else {
          console.error(chalk.red(`Invalid --claude-env format: ${envArg}. Expected KEY=VALUE`))
          process.exit(1)
        }
      } else if (arg === '--chrome') {
        chromeOverride = true
        // We'll add --chrome to claudeArgs after resolving settings default
      } else if (arg === '--no-chrome') {
        chromeOverride = false
        // Happy-specific flag to disable chrome even if default is on
      } else if (arg === '--settings') {
        // Intercept --settings flag - Happy uses this internally for session hooks
        const settingsValue = args[++i] // consume the value
        console.warn(chalk.yellow(`⚠️  Warning: --settings is used internally by Happy for session tracking.`))
        console.warn(chalk.yellow(`   Your settings file "${settingsValue}" will be ignored.`))
        console.warn(chalk.yellow(`   To configure Claude, edit ~/.claude/settings.json instead.`))
        // Don't pass through to claudeArgs
      } else {
        // Pass unknown arguments through to claude
        unknownArgs.push(arg)
        // Check if this arg expects a value (simplified check for common patterns)
        if (i + 1 < args.length && !args[i + 1].startsWith('-')) {
          unknownArgs.push(args[++i])
        }
      }
    }

    // Add unknown args to claudeArgs
    if (unknownArgs.length > 0) {
      options.claudeArgs = [...(options.claudeArgs || []), ...unknownArgs]
    }

    // Resolve Chrome mode: explicit flag > settings > false

View on GitHub (pinned to b824cd0a46)

Solutions

Merge the contents of the named settings file into ~/.claude/settings.json so Claude picks it up.
Remove --settings and its value from the command line.
Verify effective Claude config afterwards via `claude /status` or by inspecting ~/.claude/settings.json.

Example fix

// before
happy claude --settings ./team.json
// after
cat ./team.json >> ~/.claude/settings.json && happy claude

Defensive patterns

Strategy: validation

Validate before calling

// ensure the settings you would have passed are merged into the global Claude settings
const wanted = JSON.parse(fs.readFileSync('team.json', 'utf8'));
const globalPath = require('os').homedir() + '/.claude/settings.json';
const global_ = JSON.parse(fs.readFileSync(globalPath, 'utf8'));
const missing = Object.keys(wanted).filter(k => !(k in global_));
if (missing.length) console.warn('Keys from team.json missing in ~/.claude/settings.json:', missing);

Prevention

Merge team/project Claude settings into ~/.claude/settings.json ahead of time.
Remove --settings (and its value) from happy invocations and scripts.
Verify effective Claude config with `claude /status` after changes.
Document in team onboarding that happy ignores --settings.

When it happens

Trigger: Same as the --settings warning: `happy claude --settings <path>` — settingsValue is args[++i] after the flag.

Common situations: User expects their custom Claude settings JSON to apply to the happy-wrapped session; it silently doesn't, and this line tells them which file was dropped.

Related errors

AI-assisted analysis of slopus/happy@b824cd0a46 (2026-08-31). Data as JSON: /api/errors/ab7fd33e55d9da51. Report an issue: GitHub.