Claude Project settings.json: Scope and Common Settings

When people search for "Claude project settings json," they are usually asking about one of two things: the .claude/settings.json file that Claude Code reads in a project folder, or the configuration behind a claude.ai Project. These are different systems with different purposes. Tools like fenbs keep the human decisions behind the selected settings recorded and readable by the next session, so the reasons behind a configuration do not disappear with the chat.

Getting the scope right matters. A setting in the wrong place either does not apply when you expect it to, or applies when you did not intend it to.

Two kinds of Claude project settings

Claude Code (the terminal-based coding assistant) stores project configuration in .claude/settings.json inside your project folder. This file controls tool permissions, hooks, environment variables, and other runtime behavior for that specific directory. It applies whenever Claude Code opens that folder.

Claude.ai Projects (the organizational feature in the claude.ai web app) use Project instructions—a text field you fill in from the Project settings page. Those instructions appear at the start of every conversation inside the Project. There is no JSON file involved; the settings live in Anthropic's cloud, tied to your account.

If you are looking for how to configure claude.ai Projects, open the Project settings page on claude.ai. This article covers Claude Code's .claude/settings.json.

The .claude/settings.json file

Claude Code looks for settings in two places: a user-level file at ~/.claude/settings.json that applies to all projects, and a project-level file at .claude/settings.json inside the current working directory. Project-level settings override user-level ones for the same key.

A minimal project settings file might look like this:

{
  "permissions": {
    "allow": [
      "Bash(npm run test)",
      "Bash(npm run build)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  }
}

Check Anthropic's Claude Code documentation↗ (opens in a new tab) for the current schema. The exact keys and values change between releases, so rely on the official reference rather than examples that may be outdated.

Common settings and what they do

The most commonly used settings categories are:

• permissions.allow and permissions.deny: which Bash commands and tools Claude Code may use without asking for approval. Use allow for commands that are safe to run automatically; use deny for commands that should never run without explicit instruction.
• hooks: shell commands that run at lifecycle events (PreToolUse, PostToolUse, Stop). Useful for saving context, enforcing a linting step, or logging tool use.
• env: environment variables to set for the Claude Code session in this project.
• model: override the default model for this project if you have access to multiple.

Start with permissions. Decide which npm run or gradle commands are safe to run automatically and add those to allow. Add anything destructive—rm -rf, git push --force, DROP TABLE—to deny explicitly.

Scope and inheritance

A project-level settings file applies only when Claude Code opens that folder or a subfolder within it. If you open a parent directory, the project-level settings do not apply—only the user-level file does. This matters for monorepos: settings in apps/web/.claude/settings.json apply when Claude Code opens apps/web, but not when it opens the repo root.

For a monorepo with multiple packages that each need different settings, create a .claude/settings.json in each package directory. For settings that should apply across the whole repo, put them in the root .claude/settings.json and add package-specific overrides where needed.

Verify scope by asking Claude Code: "Which settings file are you reading?" Claude Code will show you the paths it found and which one it is using. Do this whenever you are unsure whether a project-level setting is actually active.

Checking which settings are active

Claude Code can tell you which settings are loaded in the current session. Ask it directly, or check the .claude/ directory for the files it would read. If a setting is not taking effect, the most common cause is the file is in the wrong directory, the key name has changed in a newer version, or a user-level setting is overriding the project-level one.

After any significant settings change, confirm with a simple test: if you added a command to allow, ask Claude Code to run it and confirm it runs without prompting for permission. If it still prompts, the setting is not loaded.

How to do this with fenbs

Connect Claude Code to fenbs and record the decisions behind each project's settings.

1. Create a free account and add a project in fenbs for the codebase.
2. Connect Claude Code from Integrations and follow the MCP setup guide.
3. Add a Decision for each significant settings choice: why a command is allowed, what a hook does, who approved the configuration, and when it was last reviewed.
4. When the settings change—a new command added to the allow list, a hook updated—record the new decision in fenbs so the history of changes is visible.
5. Add a context note with the confirmed settings file locations: which directory holds the project-level file and which keys are set at user level. Mark it as verified so future sessions know it was checked.

fenbs does not read or write .claude/settings.json directly. It keeps the human decisions that explain the configuration—what was chosen, why it was chosen, and when it last changed—so the next session understands the reasoning, not just the current values in the file.