SessionStart Hook

SessionStart

SessionStart is triggered when Hawa Code starts a new session or resumes an existing session. Suitable for loading development context (such as pending issues or recent changes to the codebase), or setting environment variables.

Note: For static context that doesn’t require scripts, HAWA.md is recommended. Since SessionStart runs in every session, ensure hooks execute quickly and efficiently.

Matcher Support

SessionStart supports matchers for matching different session startup methods:

Matcher Trigger Timing
startup When a new session starts
resume When resuming a session using --resume, --continue, or /resume
clear After executing /clear
compact After automatic or manual conversation compaction

Input Parameters

In addition to common input fields, SessionStart hooks also receive the following fields:

Field Description
source Session startup method: "startup" (new session), "resume" (resume session), "clear" (after /clear), "compact" (after compaction)
model Identifier of the currently used model
agent_type Optional, Agent type

Input Example:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.hcode/projects/.../dakabxi.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SessionStart",
  "source": "startup",
  "model": "kimi-k2.5"
}

Output Parameters

The content output by the hook script to stdout will be added as context to Claude. In addition to common JSON output fields, the following specific fields can also be returned:

Field Description
additionalContext String to be added to Claude’s context, values from multiple hooks will be concatenated

JSON Output Example:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "My additional context here"
  }
}

Configuration

Hook Handler Fields

Common Fields (all hook types)

Field Required Description
type Yes Hook type: "command", "prompt" or "agent"
timeout No Timeout in seconds. Defaults: 600 for command, 30 for prompt, 60 for agent
statusMessage No Custom spinner message displayed while the hook is running

Command Hook Specific Fields

Field Required Description
command Yes Shell command to execute
async No Set to true to run in the background without blocking session startup

Prompt Hook Specific Fields

Field Required Description
prompt Yes Prompt text sent to the model, use $ARGUMENTS as a placeholder for hook input JSON
model No Model used for evaluation, defaults to fast model

Configuration Examples

1. Command Hook

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "node ./scripts/test.js",
            "timeout": 600
          }
        ]
      }
    ]
  }
}

Script Example (./scripts/test.js):

function testAddContext() {
  const result = {
    "hookSpecificOutput": {
      "hookEventName": "SessionStart",
      "additionalContext": "Session started, current project uses Node.js tech stack, main directories include src, tests, and docs."
    }
  };
  console.log(JSON.stringify(result));
}
testAddContext();

2. Prompt Hook

Prompt Hook sends the prompt to the model for single-round evaluation. The JSON returned by the model can be used as a decision basis, suitable for scenarios requiring LLM judgment.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Analyze the current project structure and provide a brief summary of the main technologies used. Input: $ARGUMENTS",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Running Hooks in Background

Command Hook supports the async field. When set to true, the hook will run in the background without blocking session startup.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/background-task.sh",
            "async": true
          }
        ]
      }
    ]
  }
}
Next