# When Are Background Hook Pipelines Spawned Concurrently in Worktrunk?

> Discover when Worktrunk's background hook pipelines spawn concurrently. Learn how post-hooks launch simultaneously after command success for efficient workflow automation.

- Repository: [Maximilian Roos/worktrunk](https://github.com/max-sixty/worktrunk)
- Tags: internals
- Published: 2026-09-14

---

**Background hook pipelines in Worktrunk spawn concurrently immediately after the main command succeeds, with all registered post-hooks launching simultaneously as detached processes rather than executing sequentially.**

Worktrunk orchestrates post-operation hooks through a sophisticated background pipeline system in the `max-sixty/worktrunk` repository. Understanding when and how these **background hook pipelines** activate is crucial for optimizing workflow automation and resource management. This article examines the concurrent execution model as implemented in the source code.

## The Trigger Point for Concurrent Execution

Background hook pipelines activate only after the primary command completes successfully. When you execute operations like `merge`, `remove`, or `start`, Worktrunk first completes the main task, then initiates the background phase.

According to the source code in [`src/commands/hook_plan.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/commands/hook_plan.rs) (lines 405-415), the system registers applicable background hooks—such as `post-merge`, `post-remove`, or `post-start`—immediately after the primary operation succeeds. The `HookPlan` determines which hooks apply to the current command context and prepares them for concurrent execution.

## How the HookAnnouncer Orchestrates Concurrent Spawning

The **HookAnnouncer** struct serves as the central coordinator for launching background pipelines. Located in [`src/commands/hook_announcement.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/commands/hook_announcement.rs), this component manages the transition from registration to execution.

### Registration Phase

Before spawning, the system collects all relevant hooks into the announcer's registry. The `HookPlan` identifies which post-hooks match the current command type and registers them for background execution, ensuring only relevant pipelines are queued for the operation.

### Concurrent Spawning Mechanism

At lines 425-440 of [`src/commands/hook_announcement.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/commands/hook_announcement.rs), the `spawn_registered_hooks` method iterates through all registered hooks and launches them simultaneously. Rather than awaiting each hook's completion sequentially, the announcer invokes `spawn_detached_exec` for every registered pipeline in rapid succession.

The actual process spawning implementation resides in [`src/commands/process.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/commands/process.rs) (lines 339-360). Here, the `spawn_detached_exec` function creates detached `wt hook run-pipeline` processes for each registered hook. This approach ensures true concurrency, as each pipeline operates independently with its own output logging and process context.

## Foreground vs. Background Execution Context

Worktrunk distinguishes between inline and detached execution modes. As documented in [`src/cli/mod.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/cli/mod.rs) (lines 1620-1630), post-hooks run in the background by default, with output redirected to log files. Users can override this behavior using `wt hook <type> --foreground` to execute hooks inline within the main process, blocking until completion.

The priority model described in [`src/priority.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/priority.rs) (lines 41-62) confirms that background pipelines execute as separate detached processes, allowing the main command to return control to the user immediately while hooks continue processing asynchronously.

## Practical Code Example

The following Rust code illustrates the concurrent spawning pattern found in the Worktrunk source:

```rust
// From src/commands/hook_announcement.rs
pub fn spawn_registered_hooks(&self) -> Result<()> {
    for hook in self.registered_hooks.iter() {
        // Each hook spawns immediately without awaiting others
        spawn_detached_exec(
            &hook.command, 
            &hook.log_path, 
            &hook.context_json
        )?;
    }
    Ok(())
}

```

This iteration demonstrates the concurrent nature: the loop processes all registered hooks without blocking between iterations, creating multiple detached processes nearly simultaneously via `spawn_detached_exec`.

## Summary

- **Background hook pipelines** spawn immediately after the main command succeeds, not before or during
- The **HookAnnouncer** coordinates all spawning through [`src/commands/hook_announcement.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/commands/hook_announcement.rs) (lines 425-440)
- All registered post-hooks launch concurrently via `spawn_detached_exec` in [`src/commands/process.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/commands/process.rs) (lines 339-360)
- Execution occurs as detached `wt hook run-pipeline` processes, not sequential blocking calls
- Hook registration and filtering occurs in [`src/commands/hook_plan.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/commands/hook_plan.rs) (lines 405-415) before spawning begins

## Frequently Asked Questions

### What triggers background hook pipelines to start in Worktrunk?

Background hook pipelines trigger immediately after the primary command completes successfully. The system first finishes operations like merge or remove, then registers applicable post-hooks through the `HookPlan` and spawns them all at once via the `HookAnnouncer`.

### Do background hooks run sequentially or in parallel?

Background hooks run in parallel. The `HookAnnouncer`'s `spawn_registered_hooks` method iterates through all registered hooks and calls `spawn_detached_exec` for each without awaiting completion, creating concurrent detached processes for every registered pipeline.

### Can I run Worktrunk hooks in the foreground instead of background?

Yes. According to [`src/cli/mod.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/cli/mod.rs), you can execute hooks inline using the `--foreground` flag with `wt hook <type>`. This runs the hook pipeline within the main process rather than spawning a detached background process, allowing you to observe output directly in the terminal.

### Where does Worktrunk handle the actual process spawning for hooks?

The actual process spawning occurs in [`src/commands/process.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/commands/process.rs) within the `spawn_detached_exec` function (lines 339-360). This function creates the detached `wt hook run-pipeline` processes that execute the background hooks independently, as noted in the priority model documentation at [`src/priority.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/priority.rs).