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.

https://github.com/user-attachments/assets/995aae83-d000-4aa5-9c39-a3f856fcb5db

[bugproof]

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

[matbeedotcom]

Where are the config files on windows?

[dejoma]

My project settings don't work properly: ~/dejoma/project/.claude/settings.json I have Bash(ls:*) allowed

Then somehow it still creates a ~/dejoma/project/.claude/settings.local.json where sporadically it asks me permission for a "new" command. I still had to accept Bash(ls:*) -- this is now also inside the local settings.

But then yesterday I have a not_allowed command which is bun db:migrate and it mentioned "tool not allowed" so it is working for this?

1. How is it possible it added the Bash(ls:*) to my local project settings if it is in the 'committed/shared project settings' ?
2. When you are in a session, and something gets asked about permissions, this will always be added to local project settings?

[kmizzi]

following

[tdi]

What is the good file? ~/.claude.json or files in ~/.claude/ ? I had my MCPs configured globally - now they are gone but I can see them in ~/.claude.json

[lentil32]

check if settings.json is well formatted

[baelter]

Which one is it?