Skip to content

Hooks

Run project scripts automatically.

Hooks run your scripts on agent events, such as session startup or before and after a tool call. Use them to integrate your own checks and project routines into the workflow.

Set up in three steps.

  1. Create a session-start hook template

    Create a template for your chosen event in the Lurus Code chat. Use a new name to avoid overwriting an existing script.

    1. Create a session-start hook template
      /create-hook SessionStart project-start --ts

  2. Edit the script and event mapping

    Adapt the generated TypeScript script under .lurus/hooks/. This example logs session startup without blocking it. It requires Node.js and tsx. Keep the generated path in .lurus/hooks.json or replace it with the actual script path.

    .lurus/hooks/project-start.ts

    process.stdin.resume();
    process.stdin.on('end', () => {
      console.error('Project session started.');
      console.log(JSON.stringify({ decision: 'allow' }));
    });

    .lurus/hooks.json

    {
      "SessionStart": [
        {
          "hooks": [
            {
              "type": "command",
              "command": "npx tsx .lurus/hooks/project-start.ts",
              "timeout": 30000
            }
          ]
        }
      ]
    }
  3. Validate and activate

    Check the configuration with /hooks validate. Then start a new session, approve hook execution for the project and test your routine.

    1. Validate project hook configuration
      /hooks validate

Manage hooks

Change or remove the mapping in .lurus/hooks.json and load it with a new session. Global hooks live in ~/.lurus/hooks.json. Find additional events and matchers in the documentation.

Read the documentation

Hooks execute scripts. Review the commands before granting project startup approval; approved hooks can run without a separate prompt for each execution.

A few things to know before you start.

Are hook templates generated by AI?
The /create-hook command writes a template and registers it. Review and adapt the script yourself before approving execution.
Does validation prove a hook is safe?
No. /hooks validate checks basic configuration and referenced script structure. Review the script, permissions and destinations separately.
Will every hook execution ask again?
Do not assume so. Project startup approval can allow configured hooks to run commands without a separate prompt each time.

Hooks

Keep one useful routine close to the workflow.

Choose the event, review the script and test the routine before approving it for your project.

Hooks execute scripts. Review the commands before granting project startup approval; approved hooks can run without a separate prompt for each execution.

Want to start with your team? Talk to us.

A deliberate choice

Before your first prompt.

Interactive demo
Lurus Codeprivacy-demo · illustrative workspace

Demo session ready. Your model choice and data route are separate decisions.

Illustrative scenario. No real sign-in, security test or code transmission takes place.

Image preview