Configuration

CodeForge configuration is spread across three files that each control a different aspect of the environment: settings.json for Claude Code behavior, devcontainer.json for container setup, and file-manifest.json for config file deployment.

settings.json

The primary configuration file lives at .codeforge/config/settings.json. It is deployed to ~/.claude/settings.json on every container start and controls Claude Code’s runtime behavior.

Core Settings

{
  "model": "opus",
  "effortLevel": "high",
  "cleanupPeriodDays": 60,
  "autoCompact": true,
  "alwaysThinkingEnabled": true,
  "teammateMode": "auto",
  "includeCoAuthoredBy": false
}

Setting	Purpose	Default
model	Default Claude model (opus, sonnet, haiku)	opus
effortLevel	Response effort (low, medium, high)	high
cleanupPeriodDays	Days before old session data is cleaned up	60
autoCompact	Automatically compact context when it gets long	true
alwaysThinkingEnabled	Enable extended thinking for all responses	true
teammateMode	Agent Teams mode (auto, manual, off)	auto

Environment Variables Block

The env block sets environment variables that configure Claude Code internals:

{
  "env": {
    "ANTHROPIC_MODEL": "claude-opus-4-6",
    "BASH_DEFAULT_TIMEOUT_MS": "240000",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000",
    "MAX_THINKING_TOKENS": "63999",
    "CLAUDE_CODE_SHELL": "zsh",
    "CLAUDE_CODE_EFFORT_LEVEL": "high",
    "CLAUDE_CODE_ENABLE_TASKS": "true",
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

See Environment Variables for the complete list of available variables and their effects.

Permissions

The permissions block controls what Claude Code can do without asking:

{
  "permissions": {
    "allow": ["Read(/workspaces/*)", "WebFetch(domain:*)"],
    "deny": [],
    "ask": [],
    "defaultMode": "plan",
    "additionalDirectories": []
  }
}

• allow — Operations that proceed without user confirmation
• deny — Operations that are always blocked
• ask — Operations that prompt for confirmation each time
• defaultMode — Starting permission mode (plan means Claude proposes before acting)

Plugin Toggles

The enabledPlugins section controls which plugins are active:

{
  "enabledPlugins": {
    "agent-system@devs-marketplace": true,
    "skill-engine@devs-marketplace": true,
    "spec-workflow@devs-marketplace": true,
    "session-context@devs-marketplace": true,
    "auto-code-quality@devs-marketplace": true,
    "dangerous-command-blocker@devs-marketplace": true,
    "protected-files-guard@devs-marketplace": true,
    "workspace-scope-guard@devs-marketplace": true,
    "notify-hook@devs-marketplace": true,
    "ticket-workflow@devs-marketplace": true,
    "codeforge-lsp@devs-marketplace": true,
    "git-workflow@devs-marketplace": true,
    "prompt-snippets@devs-marketplace": true,
    "frontend-design@claude-plugins-official": true
  }
}

Set any plugin to false to disable it. The plugin remains installed but its hooks will not fire.

Status Line

The statusLine block configures the terminal status bar:

{
  "statusLine": {
    "type": "command",
    "command": "/usr/local/bin/ccstatusline-wrapper"
  }
}

file-manifest.json

The file manifest at .codeforge/file-manifest.json controls which configuration files are deployed to ~/.claude/ and how they are updated. Each entry specifies a source file, a destination, and an overwrite strategy:

[
  {
    "src": "config/settings.json",
    "dest": "${CLAUDE_CONFIG_DIR}",
    "enabled": true,
    "overwrite": "if-changed"
  },
  {
    "src": "config/main-system-prompt.md",
    "dest": "${CLAUDE_CONFIG_DIR}",
    "enabled": true,
    "overwrite": "if-changed"
  },
  {
    "src": "config/rules/spec-workflow.md",
    "dest": "${CLAUDE_CONFIG_DIR}/rules",
    "enabled": true,
    "overwrite": "if-changed"
  }
]

Overwrite Modes

Mode	Behavior
if-changed	Overwrites only when the source file’s SHA-256 hash differs from the deployed copy. This is the default and recommended mode.
always	Overwrites on every container start, regardless of changes
never	Copies only if the destination does not exist. User edits are always preserved.

Preserving Your Edits

If you customize a deployed file (like settings.json or the system prompt) and want your changes to survive container rebuilds, change its overwrite mode to "never" in file-manifest.json.

Adding a New Config File

To deploy a new file to ~/.claude/ automatically:

1. Place the file in .codeforge/config/
2. Add an entry to .codeforge/file-manifest.json
3. Rebuild the container

devcontainer.json

The DevContainer configuration at .devcontainer/devcontainer.json defines the container itself: base image, installed features, VS Code settings, port forwarding, and resource limits.

Base Image and Resources

{
  "image": "mcr.microsoft.com/devcontainers/python:3.14",
  "runArgs": ["--memory=6g", "--memory-swap=12g"],
  "remoteUser": "vscode",
  "containerUser": "vscode"
}

Feature Installation

DevContainer features install runtimes and tools. CodeForge pins external features to specific versions for reproducibility:

{
  "features": {
    "ghcr.io/devcontainers/features/node:1.7.1": { "version": "lts" },
    // "ghcr.io/devcontainers/features/rust:1.5.0": { "version": "latest" },  // Opt-in
    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0.5": {},
    "./features/ruff": { "version": "latest" },
    // "./features/ccms": {}        // Currently disabled — replacement pending
  }
}

Disabling a Feature

Any local feature (those starting with ./features/) can be disabled by setting "version": "none". The feature’s install script will skip entirely.

Secrets

Optional secrets can be declared for VS Code Codespaces or other DevContainer hosts:

{
  "secrets": {
    "GH_TOKEN": {
      "description": "GitHub Personal Access Token (optional)",
      "documentationUrl": "https://github.com/settings/tokens"
    },
    "NPM_TOKEN": {
      "description": "NPM auth token (optional)"
    },
    "GH_USERNAME": {
      "description": "GitHub username for git config (optional)"
    },
    "GH_EMAIL": {
      "description": "GitHub email for git config (optional)"
    }
  }
}

Secrets File

Create .devcontainer/.secrets to configure automatic authentication on container start. The file uses KEY=VALUE format:

GH_TOKEN=ghp_your_token_here
GH_USERNAME=your-github-username
GH_EMAIL=your-email@example.com
NPM_TOKEN=npm_your_token_here
CLAUDE_AUTH_TOKEN=sk-ant-oat01-your-token-here

Variable	Purpose
GH_TOKEN	GitHub Personal Access Token for gh CLI and git authentication
GH_USERNAME	GitHub username for git config user.name
GH_EMAIL	Email for git config user.email
NPM_TOKEN	NPM authentication token for publishing and private packages
CLAUDE_AUTH_TOKEN	Long-lived Claude Code token from claude setup-token

When CLAUDE_AUTH_TOKEN is set, setup-auth.sh creates ~/.claude/.credentials.json on container start with 600 permissions. If .credentials.json already exists, token injection is skipped (idempotent). Tokens must match the sk-ant-* format.

Don’t Commit Secrets

The .secrets file is listed in .gitignore. Never commit it to version control. For Codespaces, use GitHub Secrets instead — environment variables with the same names take precedence over .secrets file values.

Configuration Precedence

When the same setting is defined at multiple levels, the most specific value wins:

1. Environment variables (per-session or shell profile) — highest precedence
2. Project settings (.codeforge/config/ in the current project)
3. Default settings (shipped with CodeForge)

For example, setting ANTHROPIC_MODEL=claude-sonnet-4-5-20250929 in your shell overrides whatever is configured in settings.json.

Related

• Environment Variables — complete env var reference
• System Prompts — configure Claude’s behavioral guidelines
• Plugins — per-plugin configuration options
• Architecture — how configuration layers compose at runtime