Pre & Post Hooks

Define shell commands to run before and after structure generation.

Hook Types

pre_hooks — Run before generation. If any command fails, generation is aborted.
post_hooks — Run after generation. Errors are reported but don't stop execution.

Basic hooksyaml

pre_hooks:
  - echo "Preparing environment..."
  - ./scripts/prep.sh

post_hooks:
  - echo "Generation complete!"
  - ./scripts/cleanup.sh

files:
  - README.md:
      content: |
        # My Project

Practical Examples

Environment Setup

pre_hooks:
  - python -m venv .venv
  - source .venv/bin/activate
  - pip install --upgrade pip

post_hooks:
  - source .venv/bin/activate
  - pip install -r requirements.txt
  - echo "Virtual environment ready!"

Git Repository Initialization

pre_hooks:
  - git --version

post_hooks:
  - git init
  - git add .
  - git commit -m "Initial commit from StructKit"

Docker Setup

pre_hooks:
  - docker --version

post_hooks:
  - docker build -t {{@ project_name | slugify @}} .
  - echo "Docker image built successfully"

Variables in Hooks

pre_hooks:
  - echo "Setting up {{@ project_name @}}"

post_hooks:
  - echo "{{@ project_name @}} setup complete!"

Safety Controls

Hooks execute shell commands, so StructKit gates them. Disable hooks entirely, confirm them interactively, or allowlist the exact commands you trust.

Disable hooks

Pass --no-hooks, or set STRUCTKIT_NO_HOOKS=true:

Terminalbash

structkit generate .structkit.yaml --no-hooks

Interactive confirmation

By default StructKit asks for confirmation before running hooks. Skip the prompt with --non-interactive or STRUCTKIT_NON_INTERACTIVE=true. Note that non-interactive mode without --no-hooks still runs the hooks — it only removes the prompt.

Allowlist file

Commands listed in .struct-hooks-allowlist are pre-approved. The file is auto-detected in the current working directory; point at a different path with --hooks-allowlist or STRUCTKIT_HOOKS_ALLOWLIST. Entries match either the exact command or its base command (the first word). Lines starting with # and blank lines are ignored.

.struct-hooks-allowlisttext

# trusted hook commands
git
npm ci
./scripts/prep.sh

MCP server

The MCP generate_structure tool defaults to no_hooks: true. Running hooks from an assistant requires explicitly passing no_hooks: false, which is not recommended. See MCP integration.

Best Practices

Keep hooks simple — use external scripts for complex operations
Handle errors gracefully — check for tool availability in pre-hooks
Use absolute paths — hooks run in the target directory context
Log important actions — use echo statements for user feedback
Test independently — ensure hook commands work outside StructKit

File Handling

Custom Structures