Overview

GemKit uses two configuration files in the .gemini/ directory:

.gk.json - Project settings, plans, paths, and agent configuration
settings.json - Tools, hooks, and automation settings

.gk.json Reference

The main project configuration file.

Plan Settings

json

{
  "plan": {
    "namingFormat": "{date}-{issue}-{slug}",
    "dateFormat": "YYMMDD-HHmm",
    "issuePrefix": "GH-",
    "reportsDir": "reports",
    "resolutionOrder": ["session", "branch"],
    "branchPattern": "^(?:feature|fix|chore)/(?<name>.+)$"
  }
}

Field	Description
`namingFormat`	Template for plan file names
`dateFormat`	Date format in plan names
`issuePrefix`	Prefix for issue references
`reportsDir`	Directory for generated reports
`resolutionOrder`	Order to resolve plan context
`branchPattern`	Regex to extract branch names

Path Configuration

json

{
  "paths": {
    "docs": "docs",
    "plans": "plans"
  }
}

Field	Description
`docs`	Documentation directory
`plans`	Plans directory

Agent Spawning

json

{
  "spawn": {
    "agentsDir": ".gemini/agents",
    "defaultModel": "gemini-2.5-flash",
    "music": false
  }
}

Field	Description
`agentsDir`	Directory containing agent definitions
`defaultModel`	Default AI model for agents
`music`	Enable ambient music during execution

Project Detection

json

{
  "project": {
    "type": "auto",
    "packageManager": "auto",
    "framework": "auto"
  }
}

All fields default to "auto" for automatic detection.

Notifications

json

{
  "notifications": {
    "discord": {
      "enabled": true,
      "mainAgent": true,
      "subAgentRoles": ["code-executor", "git-manager"]
    }
  }
}

Field	Description
`discord.enabled`	Enable Discord notifications
`discord.mainAgent`	Notify for main agent events
`discord.subAgentRoles`	Roles that trigger notifications

Locale and Trust

json

{
  "locale": {
    "responseLanguage": null
  },
  "trust": {
    "enabled": false,
    "passphrase": null
  }
}

Assertions

json

{
  "assertions": []
}

Custom assertions for validation (empty by default).

settings.json Reference

Controls tools, hooks, and automation behavior.

Tools Configuration

json

{
  "tools": {
    "hooks": true,
    "allowedTools": [
      "list", "read", "write", "glob", "search",
      "replace", "fetch", "memory", "todolist",
      "websearch", "shell"
    ],
    "interactiveShell": {
      "enabled": false,
      "inactivityTimeout": 60
    },
    "color": true,
    "autoApproved": ["git", "npm", "npx", "npm install", "npm run build"]
  }
}

Field	Description
`hooks`	Enable/disable hooks system
`allowedTools`	List of tools agents can use
`interactiveShell.enabled`	Allow interactive shell
`interactiveShell.inactivityTimeout`	Shell timeout in seconds
`color`	Enable colored output
`autoApproved`	Commands that don't require approval

Hooks Configuration

Hooks are defined in settings.json with lifecycle stages:

json

{
  "hooks": {
    "SessionStart": [
      {
        "command": "node .gemini/hooks/gk-session-init.cjs",
        "timeout": 30000,
        "matcher": "*"
      }
    ],
    "BeforeAgent": [
      {
        "command": "node .gemini/hooks/gk-session-init.cjs",
        "timeout": 30000,
        "matcher": "*"
      },
      {
        "command": "node .gemini/hooks/gk-dev-rules-reminder.cjs",
        "timeout": 10000,
        "matcher": "*"
      }
    ],
    "BeforeModel": [
      {
        "command": "node .gemini/hooks/gk-session-init.cjs",
        "timeout": 5000,
        "matcher": "*"
      }
    ],
    "SessionEnd": [
      {
        "command": "node .gemini/hooks/gk-session-end.cjs",
        "timeout": 10000,
        "matcher": "*"
      }
    ]
  }
}

Hook Lifecycle Stages

Stage	When It Runs
`SessionStart`	When a new session begins
`BeforeAgent`	Before an agent processes a request
`BeforeModel`	Before sending to the AI model
`SessionEnd`	When session completes

Hook Object Properties

Property	Type	Description
`command`	string	Command to execute
`timeout`	number	Timeout in milliseconds
`matcher`	string	Pattern to match (`*` for all)

Environment Variables

Required

Variable	Description
`GEMINI_API_KEY`	Google Gemini API key

Optional

Variable	Description
`ANTHROPIC_API_KEY`	Claude API key for dual-provider
`DISCORD_WEBHOOK`	Discord webhook URL for notifications

Setting Environment Variables

Linux/macOS:

bash

export GEMINI_API_KEY=your-key-here

Windows (PowerShell):

powershell

$env:GEMINI_API_KEY = "your-key-here"

.gkignore Reference

Specify files to ignore when loading context:

node_modules/
dist/
build/
.next/
.env
*.log

Complete .gk.json Example

json

{
  "plan": {
    "namingFormat": "{date}-{issue}-{slug}",
    "dateFormat": "YYMMDD-HHmm",
    "issuePrefix": "GH-",
    "reportsDir": "reports",
    "resolutionOrder": ["session", "branch"],
    "branchPattern": "^(?:feature|fix|chore)/(?<name>.+)$"
  },
  "paths": {
    "docs": "docs",
    "plans": "plans"
  },
  "spawn": {
    "agentsDir": ".gemini/agents",
    "defaultModel": "gemini-2.5-flash",
    "music": false
  },
  "project": {
    "type": "auto",
    "packageManager": "auto",
    "framework": "auto"
  },
  "notifications": {
    "discord": {
      "enabled": true,
      "mainAgent": true,
      "subAgentRoles": ["code-executor", "git-manager"]
    }
  },
  "locale": {
    "responseLanguage": null
  },
  "trust": {
    "enabled": false,
    "passphrase": null
  },
  "assertions": []
}

gk init - Initialize configuration
Hooks - Hook details
gk doctor - Diagnose configuration issues

Overview

.gk.json Reference

Plan Settings

Path Configuration

Agent Spawning

Project Detection

Notifications

Locale and Trust

Assertions

settings.json Reference

Tools Configuration

Hooks Configuration

Hook Lifecycle Stages

Hook Object Properties

Environment Variables

Required

Optional

Setting Environment Variables

.gkignore Reference

Complete .gk.json Example

Related Documentation