Hooks

Inject custom logic into Sypha's workflow to validate operations, monitor tool usage, and shape AI decisions

Hooks enable you to integrate custom logic into Sypha's operational flow at critical junctures. Consider them as automated validation points where you can inspect operations prior to execution, observe tool activity in real-time, and influence Sypha's decision-making process.

These hooks activate automatically during specific development events. They obtain comprehensive details about each operation, possess the ability to prevent problematic actions from occurring, and can introduce context that influences subsequent AI choices.

The true capability emerges when you combine these features. You have the ability to:

Prevent problematic operations from executing (such as generating .js files within a TypeScript codebase)
Gain insights from ongoing activities and accumulate project understanding progressively
Track performance metrics and identify emerging issues
Maintain comprehensive logs for analytics or regulatory compliance
Activate external systems or services at optimal times

Hooks are currently supported on macOS and Linux only. Windows support is not available.

Getting Started

Activating hooks within Sypha is a simple process. Follow these steps:

Access Sypha settings and activate the "Enable Hooks" checkbox.

Locate this setting through:

Launch Sypha
Select the "Settings" button positioned in the top right corner
Navigate to the "Feature" section from the left sidebar menu
Scroll to locate the "Enable Hooks" checkbox and activate it

Determine the appropriate location for your hooks:

For personal or organization-wide hooks:

Establish hooks within ~/Documents/Sypha/Rules/Hooks/
These take effect across all workspaces by default

For project-specific hooks:

Establish hooks within .sypharules/hooks/ at your project's root directory
These apply exclusively to the particular workspace
Add them to version control for team-wide accessibility

Hook files require precise naming without file extensions. As an illustration, creating a TaskStart hook:

# Create the hook file
vim .sypharules/hooks/TaskStart

Insert your script (shebang line required)

#!/usr/bin/env bash

# Store piped input into a variable
input=$(cat)

# Dump the entire JSON payload
echo "$input" | jq .

# Get the type of a field
echo "$input" | jq -r '.timestamp | type'

This sample script illustrates the fundamental mechanics of hook input/output: capturing the JSON payload from stdin using input=$(cat), and utilizing jq to examine the data structure and field types your hook receives. This clarifies available data before constructing more sophisticated hook logic.

Make it executable

chmod +x .sypharules/hooks/TaskStart

Initiate a task within Sypha and confirm your hook runs successfully.

Begin with a straightforward hook that merely logs data before developing complex validation logic. This approach clarifies the data structure and execution timing.

What You Can Build

After mastering the fundamentals, hooks unlock numerous creative opportunities:

code-branch

Intelligent Code Review

Execute linters or custom validators prior to file persistence. Prevent commits that fail quality checks. Monitor code quality metrics across time.

shield-halved

Security Enforcement

Block operations that breach security protocols. Identify potential exposure of sensitive information. Maintain audit trails of file access for regulatory purposes.

chart-line

Development Analytics

Calculate operation duration metrics. Recognize patterns within AI behavior. Create productivity reports derived from hook data.

plug

Integration Hub

Interface with issue tracking systems upon detecting specific keywords. Synchronize project management platforms. Integrate with external APIs at appropriate intervals.

The essential element involves integrating hooks with external systems. A hook serves as the connection layer between Sypha's operational flow and your broader development infrastructure.

Hook Types

Sypha offers various hook types that allow you to access different phases of the AI workflow. These are categorized according to their activation points and intended applications.

The hook names shown below represent the exact file names required for creation. As an example, implementing the TaskStart hook requires creating a file called TaskStart (without any file extension) within your hooks directory.

Every hook obtains base fields alongside its particular data: syphaVersion, hookName, timestamp, taskId, workspaceRoots, userId.

Tool Execution

These hooks capture and validate tool operations both before and after execution. Utilize them to implement policies, monitor modifications, and gain insights from operations.

PreToolUse

Executes prior to any tool invocation. Employ it to prevent invalid operations, verify parameters, and apply project policies before modifications occur.

Input Fields:

{
  "syphaVersion": "string",
  "hookName": "PreToolUse",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "preToolUse": {
    "toolName": "string",
    "parameters": {}
  }
}

PostToolUse

Executes following tool completion. Employ it to extract insights from results, monitor performance indicators, and develop project knowledge derived from performed operations.

Input Fields:

{
  "syphaVersion": "string",
  "hookName": "PostToolUse",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "postToolUse": {
    "toolName": "string",
    "parameters": {},
    "result": "string",
    "success": boolean,
    "executionTimeMs": number
  }
}

User Interaction

These hooks observe and augment user communication with Sypha. Utilize them to verify input, introduce context, and monitor interaction behaviors.

UserPromptSubmit

Executes upon user message submission to Sypha. Employ it to verify input, introduce context derived from the prompt, and monitor interaction behaviors.

Input Fields:

{
  "syphaVersion": "string",
  "hookName": "UserPromptSubmit",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "userPromptSubmit": {
    "prompt": "string",
    "attachments": ["string"]
  }
}

Task Lifecycle

These hooks observe and react to task state transitions from initiation to completion. Utilize them to monitor progress, reinstate state, and activate workflows.

TaskStart

Executes upon new task initiation. Employ it to identify project type, establish tracking, and introduce initial context that influences Sypha's approach to the work.

Input Fields:

{
  "syphaVersion": "string",
  "hookName": "TaskStart",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "taskStart": {
    "taskMetadata": {
      "taskId": "string",
      "ulid": "string",
      "initialTask": "string"
    }
  }
}

TaskResume

Executes upon task resumption following interruption. Employ it to reinstate state, update context, and record resumption for analytics or external system alerts.

Input Fields:

{
  "syphaVersion": "string",
  "hookName": "TaskResume",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "taskResume": {
    "taskMetadata": {
      "taskId": "string",
      "ulid": "string"
    },
    "previousState": {
      "lastMessageTs": "string",
      "messageCount": "string",
      "conversationHistoryDeleted": "string"
    }
  }
}

TaskCancel

Executes upon task cancellation. Employ it to release resources, record cancellation information, and alert external systems regarding interrupted work.

Input Fields:

{
  "syphaVersion": "string",
  "hookName": "TaskCancel",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "taskCancel": {
    "taskMetadata": {
      "taskId": "string",
      "ulid": "string",
      "completionStatus": "string"
    }
  }
}

System Events

These hooks observe internal Sypha operations and system-level occurrences. Utilize them to monitor context consumption, record system activity, and evaluate performance behaviors.

JSON Communication

Hooks obtain JSON through stdin and produce JSON via stdout.

Output structure:

{
  "cancel": false,
  "contextModification": "WORKSPACE_RULES: Use TypeScript",
  "errorMessage": "Error details if blocking"
}

Your hook script may emit logging or diagnostic data to stdout throughout execution, provided the JSON response represents the final output. Sypha processes exclusively the terminal JSON object from stdout.

As an illustration:

#!/usr/bin/env bash
echo "Processing hook..."  # This is fine
echo "Tool: $tool_name"    # This is also fine
# The JSON must be last:
echo '{"cancel": false}'

The cancel field determines whether execution proceeds. Assign it true to prevent an action, false to permit it.

The contextModification field introduces text into the conversation. This influences subsequent AI decisions, not the present one. Employ prefixes such as WORKSPACE_RULES: or PERFORMANCE: to assist with context categorization.

Understanding Context Timing

Context introduction influences subsequent decisions, not present ones. During hook execution:

The AI has previously determined its action
The hook possesses the ability to prevent or permit it
Any context becomes incorporated into the conversation
The subsequent AI request observes that context

This indicates PreToolUse hooks serve to prevent problematic actions, whereas PostToolUse hooks serve to extract insights from completed operations.

Troubleshooting

Hook Not Running

Confirm the "Enable Hooks" setting is activated
Validate the hook file possesses executable permissions (chmod +x hookname)
Verify the hook file contains no syntax errors
Examine VSCode's Output panel (Sypha channel) for errors

Hook Timing Out

Decrease the complexity of the hook script
Prevent resource-intensive operations (network requests, demanding computations)
Evaluate relocating complex logic to a background process

Context Not Affecting Behavior

Keep in mind that context modifications influence subsequent AI decisions, not the present operation. The AI's present behavior derives from the preceding "API Request..." block, and your contextModification becomes incorporated into the following "API Request..." block. This indicates if you require immediate impact, you should utilize PreToolUse hooks for validation and produce cancel: true in your hook's JSON response to prevent Sypha from proceeding.

When introducing context, guarantee your modifications are explicit and actionable so the AI can comprehend and implement them successfully. Additionally verify that your context isn't experiencing truncation due to the 50KB constraint, as this may prevent critical information from reaching the AI.

Handling Strings with Quotes in JSON Payloads

When your hook requires incorporating strings containing unescaped quote characters (") within JSON output, utilize jq's --arg flag for correct escaping:

#!/usr/bin/env bash

# When $output contains unescaped quote characters (")...
output='{"foo":"bar"}'

# Use the --arg flag for automatic string escaping
jq -n --arg ctx "$output" '{cancel: false, contextModification: $ctx}'

# This will result in:
# {
#     "cancel": false,
#     "contextModification": "{\"foo\":\"bar\"}"
# }

The --arg flag automatically escapes special characters, avoiding JSON parsing failures when your context modification incorporates complex strings or nested JSON structures.

Hooks execute with identical permissions as VS Code. They possess access to all workspace files and environment variables. Examine hooks from unverified sources prior to activation.

Hooks enhance other Sypha capabilities:

Sypha Rules establish high-level guidance that hooks can implement
Checkpoints enable you to revert modifications if a hook failed to identify an issue
Auto-Approve functions effectively with hooks as protective measures for automated operations

Intelligent Code Review

Security Enforcement

Development Analytics

Integration Hub

On this page