Documentation error: settings.json location

[MattMagg]

The Claude Code documentation at https://docs.anthropic.com/en/docs/claude-code/settings states that settings should be in ~/.claude/settings.json, but this file doesn't exist. Settings are only accessible via the claude config list command and cannot be edited directly. This appears to be a discrepancy between the documentation and the actual implementation.

[pm4r]

Looks like the file is ~/.claude.json

[cchanley2003]

Here is the behavior I see:

claude config set -g env '{"NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/ca-certificates.crt"}'

This does update the ~/.claude/settings.json

 cat ~/.claude/settings.json
{
  "env": {
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/ca-certificates.crt"
  }
}

But the setting is not reflected. If I run claude config list -g the env is empty.

[bjdean]

Looks like the file is ~/.claude.json

Just confirming that's where I'm seeing "User Settings" configuration stored (running claude code version 1.0.29).

[stevenrouk]

Setting allowedTools in ~/.claude/settings.json does cause those allowed tools to be reflected the next time I run claude.

It looks like the allowedTools rules I set in ~/.claude/settings.json are combined with the existing allowedTools permissions found in my project_dir/.claude/settings.local.json file that were already set.

After creating ~/.claude/settings.json (manually) and confirming that it is loaded the next time I ran claude, running claude config list still does not pull from there—allowedTools still showing as blank. The documentation does say that claude config in in the process of being deprecated in place of settings.json.

[benjaminwood]

Same situation here. I have ~/.claude.json but no ~/.claude/settings.json.

It'd be great if somebody from anthropic could clarify what's going on here. The docs appear to be incorrect?

Please & thank you! 😄

[ykka]

I think there is a stark difference in what claude config list and claude config list --global do.

One seems to seek and print the local project settings

{
  "allowedTools": [],
  "hasTrustDialogAccepted": false
}

And claude config list --global seems to read your globally set user settings, weirdly located in ~/claude.json (why isn't this file inside your ~/.claude/ directory, co-located with other CC-related things)?

Plus, this command doesn't print any of the allowedTools from my globally set ~/.claude/settings.json.

{
  "installMethod": "local",
  "autoUpdates": true,
  "theme": "dark",
  "verbose": false,
  "preferredNotifChannel": "terminal_bell",
  "editorMode": "vim",
  "autoCompactEnabled": true,
  "diffTool": "auto",
  "env": {},
  "tipsHistory": {
    "new-user-warmup": 7,
    "memory-command": 11,
    "theme-command": 54,
    "prompt-queue": 14,
    "enter-to-steer-in-relatime": 56,
    "todo-list": 61,
    "# for memory": 59,
    "install-github-app": 60,
    "permissions": 61,
    "drag-and-drop-images": 62,
    "double-esc": 63,
    "continue": 66,
    "custom-commands": 55,
    "shift-tab": 67
  },
  "parallelTasksCount": "1",
  "todoFeatureEnabled": true,
  "messageIdleNotifThresholdMs": 60000,
  "autoConnectIde": false
}

---

I reckon that Anthropic is in the middle of migrating settings and cleaning this up. There might be something in the pipeline that got stuck or got some internal pushback for a better option, that's why there's little update on our end what's going on.

But this is a mess, but somewhat a normal mess for a very young product.

[ykka]

One more thing to note is that the ~/.claude.json file is difficult to use since it mixes global settings with all your project settings (mcps configs) with content (history of your prompts) and statistics. In my case it's almost 1700 lines long.

[tonglil]

Is the documentation still outdated after 2 months, or is it just not working? Would've expected claude to corrected itself already..

[idominikosgr]

looks like it is using ~/.claude.json indeed - I was experimenting and changing stuff through vscode and it changed in real time. I'm now transferring settings from ~/.claude/settings.json (mainly env) to check what works.

claude.code.mp4

[bugproof]

Bump. This is very misleading and we don't know what to do to configure settings.