# 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](grok.md) | ## 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`](grok-config-valid.md). ## 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.]`. - Hyphenated or camelCase spellings like `[mcp-servers.]` or `[mcpServers.]`. - 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`: ```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/`: ```toml # .grok/config.toml [mcp_servers.gateway] command = "bin/gateway" [permission] allow = ["Bash(make test)"] ``` In `.grok/hooks/deps.json`: ```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`](grok-hooks-valid.md). - Use `[mcp_servers.]` 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`: ```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 ```yaml 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.*