Configuration

Global Configuration

User settings stored in ~/.config/grove/grove.toml (or grove.override.toml for machine-specific/sensitive values). Controls project discovery, notebooks, logging, and TUI appearance.

Property	Description
`groves`	Defines a map of named root directories that Grove’s discovery service will scan for projects and ecosystems. This is the primary mechanism for telling Grove where your code is located and is configured in the global `~/.config/grove/grove.yml`.
`notebooks`	A container for all configuration related to the `grove nb` (notebook) tool, which manages Markdown notes, plans, and chats.
`logging`	Logging configuration
`tui.theme`	Sets the color theme for all Grove TUIs. Supported options include ‘kanagawa’ (default), ‘gruvbox’, and ‘terminal’ (uses your terminal’s ANSI colors).
`explicit_projects`	An array of objects used to manually add specific projects to Grove’s discovery system. This is useful for including projects that are outside of standard `groves` search paths or that don’t have a `grove.yml` file.

toml

# User settings stored in ~/.config/grove/grove.toml

# Defines a map of named root directories ('groves') where the tool should recursively search for projects. Each key is a unique identifier for that source.
[groves.work]
  path = "~/Work"
  notebook = "work_nb"

[groves.personal]
  path = "~/Code"
  notebook = "personal_nb"

[notebooks.rules]
  # The name of the notebook definition to use if a project is not explicitly assigned to one via 'groves'.
  default = "personal"

[notebooks.definitions.personal]
  # The base directory for this notebook. Setting this enables Centralized Mode for associated projects.
  root_dir = "~/notebooks/personal"

[logging]
  # Sets the minimum log severity to record. Options: debug, info, warn, error.
  level = "info"

[tui]
  # Selects the color theme for TUI components. Options: 'kanagawa', 'gruvbox', 'terminal'.
  theme = "kanagawa"

[[explicit_projects]]
  # The absolute filesystem path to the project root.
  path = "/opt/projects/legacy-app"
  # Sets the display name for the project in menus and logs.
  name = "legacy-app"
  # Toggles whether this explicitly defined project is active and visible in tools.
  enabled = true
  # Provides a human-readable description for an explicitly added project.
  description = "Main legacy application"

→ Full Grove Configuration Reference

LLM Settings

Default model configuration for AI-powered grove commands.

Property	Description
`default_model`	Sets the default LLM model to use for grove commands that require AI generation (e.g., changelog generation). This model will be used unless explicitly overridden by command-line flags.

toml

# Default model configuration for AI-powered grove commands
[llm]
  # Sets Gemini 3.1 Pro as the default model for AI-powered grove commands.
  default_model = "gemini-3.1-pro-preview"

→ Full Grove Configuration Reference

Flow Settings

Configuration for grove-flow job execution.

Property	Description
`oneshot_model`	Sets the default Large Language Model (e.g., `gemini-2.0-flash`) for `oneshot` jobs and chat sessions. Use this to establish a consistent model preference for quick tasks across your project, which can be overridden by individual jobs.

toml

# Configuration for grove-flow job execution
[flow]
  # Defines the default LLM model identifier to use for single-turn (oneshot) jobs when not explicitly specified in the job file.
  oneshot_model = "claude-opus-4-6"

→ Full Flow Configuration Reference

Tmux session navigation and hotkey configuration.

Property	Description
`available_keys`	Defines the list of single-character keyboard shortcuts available for mapping to specific project sessions in tmux. Use this to customize the pool of hotkeys used for quick session switching, ensuring they align with your workflow and don’t conflict with other bindings. These keys are used by the manager to generate tmux bindings that launch the sessionizer for specific projects.
`show_child_processes`	Controls whether the window selection interface displays the specific active child process (e.g., ‘vim’, ‘node’) running in each pane instead of just the shell name. Enable this to easily distinguish between multiple terminal windows by seeing exactly what command is currently running inside them. This feature relies on system process inspection tools like ‘ps’.

toml

# Tmux session navigation and hotkey configuration
[nav]
  # Defines the list of single-character keys that can be assigned to tmux sessions for rapid switching. Defaults to a-z.
  available_keys = ["w", "e", "r", "t", "y", "o", "a", "f", "g", "v"]

→ Full Navigation Configuration Reference

Notification Settings

Push notifications via ntfy.sh and system notifications.

Property	Description
`ntfy`	Configuration group for ntfy.sh integration, enabling push notifications to mobile or desktop devices. Use this to receive real-time alerts about long-running agent tasks or errors on your phone.
`system`	Configuration group for native operating system desktop notifications (macOS/Linux). Controls local alerts displayed directly in your desktop environment.

toml

# Push notifications via ntfy.sh and system notifications
[notifications]
  [notifications.ntfy]
    # Toggles ntfy.sh push notifications on or off.
    enabled = true
    # Sets the topic name where notifications will be published. This should be kept secret if using the public instance.
    topic = "my-events"
    # Specifies a custom ntfy server URL. Defaults to 'https://ntfy.sh' if not provided.
    url = "https://ntfy.sh"

→ Full Notification Configuration Reference

Gemini API Settings

Google Gemini API authentication. Use api_key_command to fetch from a secrets manager.

Property	Description
`api_key`	Specifies the Google Gemini API authentication key directly as a string. Use this for local, private configuration files (`grove.override.yml`) where convenience is prioritized over strict secret management, ensuring you do not commit actual credentials to version control.
`api_key_command`	Defines a shell command that outputs the Gemini API key to standard output (e.g., `gcloud secrets versions access latest ...` or `op read ...`). This is the recommended method for shared configuration files, as it retrieves credentials dynamically from a secure store like Google Secret Manager or 1Password without hardcoding secrets.

toml

# Google Gemini API authentication
[gemini]
  # Specifies a shell command to retrieve the API key at runtime, allowing integration with secret managers like 1Password or Google Secret Manager.
  api_key_command = "op read 'op://Private/Gemini API Key/credential'"

→ Full Gemini Configuration Reference

Ecosystem Configuration

Settings for a grove ecosystem root (e.g., ~/Code/myproject/grove.toml). Defines the ecosystem name and workspace glob patterns for package discovery.

Property	Description
`name`	The name of a project or ecosystem, defined in its `grove.yml`. This name is used for display in TUIs, as an alias for context resolution, and as a component name for logging.
`workspaces`	An array of glob patterns used in an ecosystem’s `grove.yml` to discover its sub-projects. For example, `['services/', 'libs/']` would find all projects in the `services` and `libs` directories.

toml

# Settings for a grove ecosystem root
# Identifies the current project or ecosystem configuration.
name = "my-ecosystem"

# A list of glob patterns used in an ecosystem config to identify member projects (similar to npm/yarn workspaces).
workspaces = [
  "packages/*",
  "services/api"
]

→ Full Grove Configuration Reference

Package Configuration

Per-package settings (e.g., docgen/grove.toml). Defines package metadata, binary location, and context rules.

Property	Description
`name`	The name of a project or ecosystem, defined in its `grove.yml`. This name is used for display in TUIs, as an alias for context resolution, and as a component name for logging.
`context`	A container for all configuration related to the `grove cx` (context) tool, which manages file-based context for LLMs.

toml

# Per-package settings
# Identifies the current project or ecosystem configuration.
name = "myproject"

[context]
  # Sets the default file path to look for context rules (glob patterns) within a project.
  default_rules_path = ".grove/rules"

→ Full Grove Configuration Reference

Global Configuration

LLM Settings

Flow Settings

Navigation Settings

Notification Settings

Gemini API Settings

Ecosystem Configuration

Package Configuration