What Is the Purpose of `.claude/settings.json` in the AI‑Job‑Search Repository

.claude/settings.json serves as a security manifest that explicitly whitelists which Claude agent skills and Bash commands the automation framework is authorized to execute.

The MadsLorentzen/ai-job-search repository implements a thin-pointer Claude agent architecture that requires strict operational boundaries. The purpose of .claude/settings.json is to define these boundaries through a centralized permissions system, ensuring the agent only invokes pre-approved tools and scripts when processing job applications or verifying documents.

How .claude/settings.json Controls Agent Permissions

At its core, .claude/settings.json contains a single top-level permissions object with an allow array that enumerates every authorized operation. This design ensures that no Claude-driven workflow can execute arbitrary system commands.

Skill Permissions

Entries prefixed with Skill() grant the agent access to capability definitions stored in the .claude/skills/ directory. For example, Skill(job-application-assistant) permits the agent to load and execute workflows defined in the .claude/skills/job-application-assistant/ folder. Without this explicit entry, the agent cannot invoke the job application logic.

Bash Command Permissions

Entries prefixed with Bash() whitelist specific command-line patterns using wildcard syntax. The asterisk (*) acts as a flexible matcher for command arguments:

• Bash(bun run:*) authorizes any bun script execution with arbitrary arguments
• Bash(python tools/verify_pdf.py:*) permits the PDF verification tool located at tools/verify_pdf.py
• Bash(python3 salary_lookup.py:*) enables Python 3 variants of salary lookup operations
• Bash(pdftotext:*) allows text extraction from PDFs using the poppler utility

Security and Predictability Through Explicit Whitelisting

By restricting the agent to this explicit allow-list, the repository prevents arbitrary code execution while maintaining deterministic automation behavior. The file functions as the single source of truth for what the Claude-driven automation may attempt, effectively blocking dangerous commands like rm -rf / or unauthorized network requests.

Parsing and Validating the Configuration

The settings file follows a strict JSON schema located at .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Skill(job-application-assistant)",
      "Bash(bun run:*)",
      "Bash(python salary_lookup.py:*)",
      "Bash(python3 salary_lookup.py:*)",
      "Bash(python tools/verify_pdf.py:*)",
      "Bash(python3 tools/verify_pdf.py:*)",
      "Bash(pdftotext:*)"
    ]
  }
}

You can programmatically validate commands against this manifest using a simple prefix matcher:

import json
import pathlib

settings_path = pathlib.Path('.claude/settings.json')
allowed = json.loads(settings_path.read_text())['permissions']['allow']

def is_allowed(command: str) -> bool:
    """Check if a command matches the whitelist patterns."""
    base_cmd = command.split(':')[0]
    return any(cmd.startswith(base_cmd) for cmd in allowed)

# Verification examples

assert is_allowed('Bash(bun run:build)')        # ✅ Matches Bun wildcard

assert is_allowed('Bash(python tools/verify_pdf.py:--check)')  # ✅ Permitted

assert not is_allowed('Bash(rm -rf /)')         # ❌ Blocked - not in allow list

Extending the Permissions for New Workflows

To authorize a new tool, append a pattern to the allow array in .claude/settings.json. For instance, to enable a hypothetical tools/parse_resume.py script:

"Bash(python tools/parse_resume.py:*)"

Commit this change before invoking the new tool in agent workflows. The thin-pointer design requires that all capability additions be explicitly declared in this central configuration file.

Summary

• .claude/settings.json acts as the security gatekeeper for the Claude agent framework in MadsLorentzen/ai-job-search.
• The permissions.allow array explicitly lists authorized Skill references and Bash command patterns.
• Wildcard syntax (:*) enables flexible argument passing while maintaining strict command-level control.
• The file prevents arbitrary code execution by rejecting any command not matching the predefined whitelist.
• Skills referenced in the file are implemented in the .claude/skills/ directory, while optional command specifications may reside in .claude/commands/.

Frequently Asked Questions

What happens if the Claude agent tries to run a command not listed in .claude/settings.json?

The agent framework blocks the execution immediately. According to the repository's thin-pointer design implemented in MadsLorentzen/ai-job-search, any Bash command or Skill invocation missing from the permissions.allow array results in a permission denial, preventing unauthorized system access or potential security breaches.

Can I use regular expressions in the .claude/settings.json allow patterns?

No, the configuration uses simple prefix matching with wildcard suffixes only. Patterns like Bash(python tools/verify_pdf.py:*) match commands starting with that exact string, where the asterisk represents any subsequent arguments. Complex regex patterns or middle-of-string wildcards are not supported by the parser.

Where are the Skill definitions stored that are referenced in the permissions file?

Skill definitions reside in the .claude/skills/ directory. For example, the permission Skill(job-application-assistant) points to the implementation stored in .claude/skills/job-application-assistant/, containing the actual workflow logic, prompts, and tool integrations the agent may execute when processing job applications.

Is .claude/settings.json required for the ai-job-search repository to function?

Yes. Without this configuration file, the Claude agent framework lacks the authorization map required to execute any Bash commands or load skill modules. The file is essential for the thin-pointer agent architecture to operate securely, serving as the mandatory single source of truth for all agent capabilities within the repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}