Lifecycle Hooks

Register custom commands, prompts, and HTTP calls at agent lifecycle events. Run scripts before/after tool use, at session start/end, and on compaction.

Lifecycle hooks let you run custom commands, inject prompts, or call HTTP endpoints at key points during the agent's execution. This enables auditing, logging, notifications, and custom integrations.

Available Events

XibeCode supports 9 lifecycle events:

Event	When It Fires	Use Case
`SessionStart`	When a new session begins	Initialize state, log session start
`SessionEnd`	When a session completes	Generate reports, cleanup
`UserPromptSubmit`	When the user submits a prompt	Input validation, preprocessing
`PreToolUse`	Before a tool is executed	Audit tool calls, enforce policies
`PostToolUse`	After a tool finishes	Log results, trigger downstream actions
`Stop`	When the agent stops normally	Notifications, summary generation
`StopFailure`	When the agent stops due to an error	Alerting, error tracking
`PreCompact`	Before context compaction	Save important context
`PostCompact`	After context compaction	Verify compaction quality

Hook Types

Each hook can be one of three types:

Command Hook

Runs a shell command. The command receives context via environment variables.

{
  "type": "command",
  "value": "echo 'Tool used: $TOOL_NAME'"
}

Environment variables available in command hooks:

Variable	Events	Description
`TOOL_NAME`	PreToolUse, PostToolUse	Name of the tool being called
`TOOL_INPUT`	PreToolUse	JSON string of tool input
`TOOL_OUTPUT`	PostToolUse	JSON string of tool output
`SESSION_ID`	SessionStart, SessionEnd	Session identifier
`PROMPT`	UserPromptSubmit	The user's submitted prompt
`ERROR`	StopFailure	Error message
`DURATION_MS`	SessionEnd	Session duration in milliseconds

Prompt Hook

Injects a text prompt into the agent's context.

{
  "type": "prompt",
  "value": "Always follow the project's coding standards in CONTRIBUTING.md."
}

Prompt hooks are injected as system-level instructions that the agent sees when the event fires.

HTTP Hook

Sends an HTTP POST request with event context as JSON.

{
  "type": "http",
  "value": "https://hooks.example.com/xibecode",
  "headers": {
    "Authorization": "Bearer your-token"
  },
  "timeout": 5000
}

The POST body contains:

{
  "event": "PreToolUse",
  "timestamp": "2026-05-03T10:00:00Z",
  "toolName": "write_file",
  "toolInput": { "path": "/src/app.ts", "content": "..." },
  "sessionId": "abc-123"
}

CLI Commands

List registered hooks

xc hooks list

Shows all hooks grouped by event.

View available events

xc hooks events

Add a hook

# Command hook
xc hooks add PreToolUse command "audit-log.sh"

# Prompt hook
xc hooks add SessionStart prompt "Follow the project style guide."

# HTTP hook
xc hooks add SessionEnd http "https://hooks.example.com/done"

Remove a hook

xc hooks remove PreToolUse 0

The index corresponds to the position in the hooks list for that event (0-based).

Chat Commands

Inside an interactive chat session:

/hooks list     Show all registered hooks
/hooks events   Show available events

Configuration

Hooks are stored in settings files. You can define them in any settings source:

User-level hooks (~/.xibecode/settings.json)

{
  "hooks": {
    "SessionStart": [
      { "type": "prompt", "value": "You are working on the XibeCode project." }
    ]
  }
}

Project-level hooks (.xibecode/settings.json)

{
  "hooks": {
    "PreToolUse": [
      { "type": "command", "value": "scripts/audit-tool-use.sh" }
    ],
    "PostToolUse": [
      { "type": "command", "value": "scripts/log-tool-result.sh" }
    ],
    "SessionEnd": [
      { "type": "http", "value": "https://api.example.com/session-done" }
    ]
  }
}

Hook Execution

Hooks run sequentially in the order they are defined
If a command hook exits with a non-zero code, a warning is logged but execution continues
If an HTTP hook times out (default 5 seconds), the hook is skipped
Prompt hooks are injected silently into the agent's context
Hooks cannot modify tool input/output (they are observers, not middleware)

Example Workflows

Audit trail for tool usage

Create .xibecode/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "value": "echo \"[$(date)] Tool: $TOOL_NAME Input: $TOOL_INPUT\" >> .xibecode/audit.log"
      }
    ]
  }
}

Slack notification on session end

{
  "hooks": {
    "SessionEnd": [
      {
        "type": "http",
        "value": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
        "headers": { "Content-Type": "application/json" }
      }
    ]
  }
}

Project-specific agent instructions

{
  "hooks": {
    "SessionStart": [
      {
        "type": "prompt",
        "value": "This project uses pnpm. Always use pnpm for package management. Follow the coding standards in CONTRIBUTING.md."
      }
    ]
  }
}

Next Steps

Settings — Configure settings sources
Permissions — Control tool execution with rules
Auto-Memory — Persistent project memory