Overview

Hooks allow you to execute scripts at specific points in the GemKit session lifecycle. They're defined in .gemini/hooks/ and configured in settings.json.

Hook Lifecycle Stages

GemKit provides four lifecycle stages:

Stage	When It Runs	Use Case
`SessionStart`	When a new session begins	Load context, initialize resources
`BeforeAgent`	Before an agent processes	Inject rules, add context
`BeforeModel`	Before sending to AI model	Capture state, validate
`SessionEnd`	When session completes	Notifications, cleanup, metrics

Hook Files Location

Hooks are stored in .gemini/hooks/:

markdown

.gemini/hooks/
├── gk-session-init.cjs
├── gk-session-end.cjs
├── gk-scout-block.cjs
├── gk-dev-rules-reminder.cjs
├── gk-scout-block/
├── lib/
└── notifications/

Configuration in settings.json

Hooks are configured in .gemini/settings.json:

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 Object Properties

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

Available Hook Scripts

gk-session-init.cjs

Runs at session start and before agent/model calls. Use for:

Loading project context
Setting environment variables
Capturing project state

gk-session-end.cjs

Runs when a session completes. Use for:

Sending notifications (Discord, Slack)
Updating metrics
Cleanup tasks

gk-dev-rules-reminder.cjs

Runs before agent processing. Use for:

Injecting coding standards
Adding project conventions
Enforcing development rules

gk-scout-block.cjs

Security guardrails. Use for:

Blocking sensitive file access
Preventing dangerous commands
Enforcing security policies

Hook Examples

Example 1: Session Init Hook

javascript

// .gemini/hooks/gk-session-init.cjs
module.exports = async function(context) {
  console.log('Session starting...');

  // Return additional context files
  return {
    additionalContext: [
      'docs/ARCHITECTURE.md',
      'docs/CONVENTIONS.md'
    ]
  };
};

Example 2: Session End Hook with Discord

javascript

// .gemini/hooks/gk-session-end.cjs
const https = require('https');

module.exports = async function(context) {
  const { session, result } = context;

  // Send Discord notification
  if (process.env.DISCORD_WEBHOOK) {
    const message = {
      embeds: [{
        title: 'GemKit Session Complete',
        description: `Agent: ${session.agent}`,
        color: result.success ? 0x00ff00 : 0xff0000
      }]
    };

    await sendWebhook(process.env.DISCORD_WEBHOOK, message);
  }
};

async function sendWebhook(url, data) {
  // Implementation
}

Example 3: Dev Rules Reminder

javascript

// .gemini/hooks/gk-dev-rules-reminder.cjs
module.exports = async function(context) {
  return {
    reminder: `
      Project conventions:
      - Use TypeScript strict mode
      - Add JSDoc comments for public APIs
      - Write tests for new functionality
      - Follow existing code patterns
    `
  };
};

Example 4: Scout Block for Security

javascript

// .gemini/hooks/gk-scout-block.cjs
module.exports = async function(context) {
  const { tool, args } = context;

  // Block access to sensitive files
  const blocked = [/\.env$/, /secrets\//, /\.pem$/, /\.key$/];

  if (tool === 'read' || tool === 'write') {
    const path = args.path || args.file;
    for (const pattern of blocked) {
      if (pattern.test(path)) {
        return {
          blocked: true,
          reason: `Access to ${path} blocked by security policy`
        };
      }
    }
  }

  return { blocked: false };
};

Enabling Hooks

Hooks must be enabled in settings.json:

json

{
  "tools": {
    "hooks": true
  }
}

Hook Subdirectories

lib/

Shared utilities for hooks:

javascript

// .gemini/hooks/lib/utils.cjs
module.exports = {
  formatDuration(ms) {
    return `${Math.round(ms / 1000)}s`;
  },

  async sendNotification(webhook, message) {
    // Notification logic
  }
};

notifications/

Notification handlers:

javascript

// .gemini/hooks/notifications/discord.cjs
module.exports = async function sendDiscord(webhook, message) {
  // Discord-specific logic
};

gk-scout-block/

Additional scout block configurations.

Best Practices

Keep hooks fast - Use appropriate timeouts
Handle errors gracefully - Wrap in try-catch
Use the lib/ folder - Share common utilities
Log hook activity - Add logging for debugging
Test hooks locally - Verify before relying on them

Debugging Hooks

Enable verbose mode to see hook execution:

bash

gk agent spawn --verbose -p "Test prompt"

Configuration Reference - Full settings.json reference
gk init - Initialize GemKit with hooks

Overview

Hook Lifecycle Stages

Hook Files Location

Configuration in settings.json

Hook Object Properties

Available Hook Scripts

gk-session-init.cjs

gk-session-end.cjs

gk-dev-rules-reminder.cjs

gk-scout-block.cjs

Hook Examples

Example 1: Session Init Hook

Example 2: Session End Hook with Discord

Example 3: Dev Rules Reminder

Example 4: Scout Block for Security

Enabling Hooks

Hook Subdirectories

lib/

notifications/

gk-scout-block/

Best Practices

Debugging Hooks

Related Documentation