Add lifecycle hooks for repo threads

[hagz0r]

It would be useful to support repository-level lifecycle hooks for threads — essentially constructors and destructors tied to a thread’s lifecycle.

The main use case is automatic environment setup and cleanup.

For example, when a thread starts:

cd rust-app && cargo build
cd js-app && npm install
cd scripts && ./db-open-connection.sh

And when the thread becomes settled:

cd rust-app && cargo clean
cd js-app && npm uninstall
cd scripts && ./db-close-connection.sh

Right now, desktop workflows can accumulate state and artifacts that need to be cleaned up manually after a thread is finished. Lifecycle hooks would make repo workflows easier to keep isolated and reproducible.

Possible config:

thread:
  on_start:
    - cd js-app && npm install
  on_settled:
    - cd rust-app && cargo clean
    - cd js-app && npm uninstall
    - cd scripts && ./db-close-connection.sh
  confirm_on_auto_settle: true

Manual vs automatic settling

Threads can become settled either manually or automatically.

For manual settle, running on_settled immediately is predictable since the user explicitly initiated the transition.

For automatic settle, cleanup hooks should probably not execute silently, since they may perform destructive actions such as deleting build artifacts, removing dependencies, closing DB connections, or tearing down temporary resources.

If confirm_on_auto_settle is enabled, the desktop app could show a confirmation modal before executing the destructor:

This thread was automatically settled and has cleanup hooks configured. Run cleanup now?

The setting should be configurable per repo, so users who trust their hooks can disable the confirmation.

Potentially useful hooks:

* on_start
* on_settled
* on_success
* on_failure
* on_cancel

The main feature is a reliable destructor mechanism tied to the settled state, with explicit handling for automatic settling so cleanup does not unexpectedly destroy useful state.

[hagz0r]

By repo i meant project in T3Code. Not an actual git repo

[hagz0r]

Note

Outdated: this describes the first version (a runOnSettle flag on each action). See the update below for the current design.

I implemented a small version of the cleanup half on a branch: hagz0r/t3code@feat/run-actions-on-settle. Per CONTRIBUTING, I'd like a maintainer to confirm the direction and scope before I open a PR.

Scope (smaller than the original post)

on_start already exists as a project action with Run automatically on worktree creation (runOnWorktreeCreate in t3.json). So this skips the new hooks config and adds the opposite trigger to the same project actions:

• runOnSettle on a project action. It's a switch in the action editor and a field in t3.json.
• When the user settles a thread, the server runs those actions one at a time, in list order, in the thread's worktree (or the project folder for a local thread). It uses the same kind of terminal as the setup script. A clean exit closes its terminal; a failed one stays open.
• Automatic settlement never runs them. That replaces confirm_on_auto_settle: no silent destructive cleanup, and no new prompt to build on web, desktop, and mobile. If you want the prompt, it can come later.
• It runs from the existing thread.settled reaction in ThreadSettlementService, next to the idle-terminal cleanup. So it covers every way to settle (web, desktop, mobile, agents) with one optional contract field.

Not included: on_success / on_failure / on_cancel, running anything on un-settle, or reversing cleanup when a settle is undone.

Focused tests cover running settle actions in order and skipping automatic settlement.

Is this direction and scope OK to open as a PR?

[hagz0r]

@juliusmarminge @t3dotgg tagging you since this builds on the setup-script runner and the settle hook in ThreadSettlementService you wrote. Could you take a look at the scope above when you have a moment? Happy to cut it down further or drop it if it does not fit.

[hagz0r]

Note

Outdated: this describes the first version (a runOnSettle flag on each action). See the update below for the current design.

Screenshots from a dev build of the branch, using a demo project (rust-app/target, js-app/node_modules, and a scripts/db-close-connection.sh that sleeps and prints). The action is rm -rf rust-app/target js-app/node_modules && ./scripts/db-close-connection.sh.

Action editor

Before (main)	After

Actions list in Settings → Project (the action is marked "on settle")

Settling the thread by hand. Before, settling only closes idle terminals. After, the thread moves to Settled and the action runs in its terminal:

Running	Done (exit 0)

rust-app/target and js-app/node_modules were gone right after the settle. The printf line in the terminal is the completion wrapper the setup script already uses.

[hagz0r]

Update: reworked the design after more thought. Hooks now live in their own block instead of a flag on each action:

• Settings → Project → Hooks: Add hook → pick an event → pick one of the project's actions. Events: Thread created, Turn completed, Turn failed or stopped, Thread settled.
• Hooks run on the server as background processes (no terminal), one at a time in the thread's worktree. Success is silent; a failure shows an error toast.
• Settling by hand runs settle hooks right away. An automatic settle asks first (dialog on web/desktop, prompt on mobile), with a per-project toggle to skip the question. A pending confirmation is in memory only, so a restart skips that cleanup instead of running it unasked.

Add hook	Configured hook

Automatic settle asks first:

Branch: main...hagz0r:feat/run-actions-on-settle. Focused tests cover run order, failures, confirm/skip, and once-per-run turn hooks.

Would you take this as a PR? Happy to cut it down to just the settle event if that's easier to review.