Skip to content

grok-config-project-scope

.grok/config.toml must only carry settings a project file contributes
Severity warning (auto)
Autofix -
Since v0.20.0
Repo Types grok-project
Category Grok Build

Why

Grok Build loads configuration across multiple layers, including personal user configuration (~/.grok/config.toml) and repository project configuration (.grok/config.toml).

The project configuration file is designed specifically for shared repository settings: [mcp_servers], [permission], [plugins], and [mcp] max_output_bytes. Other settings (such as [model], [ui], [tools], [telemetry], and user preferences) are intended for your personal user configuration and are ignored when placed in .grok/config.toml.

Additionally, project hooks should be configured in .grok/hooks/*.json rather than a [hooks] table in config.toml.

This rule helps ensure project configurations stay focused and effective by identifying tables and settings that belong in user configuration or dedicated hook files.

To validate the internal syntax and structure of the allowed tables, see grok-config-valid.

Severity

Findings carry the rule's configured severity (warning by default):

Settings intended for user configuration

  • Top-level tables or scalar values outside the supported project scope. Common user preferences like [model], [ui], [tools], [telemetry], and disable_web_search belong in your personal ~/.grok/config.toml.
  • [hooks] defined in config.toml: project hooks belong in .grok/hooks/*.json.

Common table naming mismatches

  • [[mcp.servers]] or [mcp.servers] instead of [mcp_servers.<name>].
  • Hyphenated or camelCase spellings like [mcp-servers.<name>] or [mcpServers.<name>].
  • Plural [permissions] instead of [permission].
  • Using transport instead of type inside a server table.
  • Using defaultMode inside [permission] (a Claude Code setting).

What is not reported

  • [plugins] paths, which the live session loads from trusted project folders, and the documented plugin switches enabled and disabled.
  • The actual user config at $GROK_HOME/config.toml (default ~/.grok/config.toml), including a Git repository rooted at HOME. Other applicable config checks still run.
  • [mcp] max_output_bytes, which configures MCP message buffer limits.

Examples

Bad — placing user settings and hooks inside project .grok/config.toml:

[mcp_servers.gateway]
command = "bin/gateway"

[model]
name = "grok-4"

[hooks]
SessionStart = [{ hooks = [{ type = "command", command = "make deps" }] }]

Good — keeping project configuration focused and moving hooks to .grok/hooks/:

# .grok/config.toml
[mcp_servers.gateway]
command = "bin/gateway"

[permission]
allow = ["Bash(make test)"]

In .grok/hooks/deps.json:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "make deps" }] }
    ]
  }
}

How to fix

  • Move personal preferences (such as default model and UI themes) into your personal ~/.grok/config.toml.
  • Configure project automation in .grok/hooks/*.json files and validate them with grok-hooks-valid.
  • Use [mcp_servers.<name>] for MCP servers and [permission] for tool permissions.

Configuration

If a newer Grok Build release adds support for additional project-level tables, you can accept them in .skillsaw.yaml:

rules:
  grok-config-project-scope:
    extra-tables:
      - toolset

For a dotfiles checkout outside its deployed HOME, skillsaw cannot infer user scope from the repository name. Use extra-tables for its personal tables or a per-file rule exclusion in that checkout.

Configuration

rules:
  grok-config-project-scope:
    enabled: auto  # true | false | auto
    severity: warning
Parameter Description Default
extra-tables Additional top-level table names to accept, for tables a Grok release honors at project scope that this skillsaw release has not heard of []

Run skillsaw explain grok-config-project-scope to see this documentation and the rule's effective configuration in your terminal.