3.5 KiB
3.5 KiB
Hooks And Settings
Hooks/settings are the entry layer that connects a platform to Trellis. They decide which scripts, plugins, or extensions a platform runs for which events.
Settings Responsibilities
settings/config files usually register:
- session-start hook: injects a Trellis overview when a new session starts or context resets.
- workflow-state hook: injects the next-action hint for the current state on each user input.
- sub-agent context hook: injects task context when implementation/check/research agents start.
- shell/session bridge: lets shell commands see the same Trellis session identity.
- platform plugin or extension entry points.
Common files:
| Platform | settings/config |
|---|---|
| Claude Code | .claude/settings.json |
| Cursor | .cursor/hooks.json |
| Codex | .codex/hooks.json, .codex/config.toml |
| OpenCode | .opencode/package.json, .opencode/plugins/* |
| Kiro | .kiro/hooks/ + platform config |
| Gemini CLI | .gemini/settings.json |
| Qoder | .qoder/settings.json |
| CodeBuddy | .codebuddy/settings.json |
| GitHub Copilot | .github/copilot/hooks.json |
| Factory Droid | .factory/settings.json |
| Pi Agent | .pi/settings.json, .pi/extensions/trellis/ |
Whether these files exist in a project depends on which trellis init --<platform> flags the user ran.
Hook Script Types
| Script | Purpose |
|---|---|
session-start.py |
Generates session-start context. |
inject-workflow-state.py |
Injects the next-action hint based on active task status. |
inject-subagent-context.py |
Injects PRD, JSONL context, and related spec/research into sub-agents. |
inject-shell-session-context.py |
Lets shell commands inherit Trellis session identity. |
Not every platform has every hook. Do not copy files from another platform just because a platform lacks a hook; first confirm whether that platform supports the corresponding event.
Local Change Scenarios
| User need | Edit location |
|---|---|
| AI should see more/less context in a new session | Platform session-start hook. |
| Per-turn hint policy should change | State blocks in .trellis/workflow.md + inject-workflow-state hook. |
| Sub-agent cannot read PRD/spec | inject-subagent-context hook or agent prelude. |
task.py current in shell has no active task |
Shell/session bridge hook or platform environment variable configuration. |
| Disable an automatic injection | The corresponding hook registration in settings/config. |
Modification Principles
- Settings wire things up; hooks define behavior. If only the hook changes, the platform may never call it. If only settings change, behavior may not change.
- Confirm platform event names first. Different platforms use different names for SessionStart, UserPromptSubmit, AgentSpawn, shell execution, and similar events.
- Hooks read local
.trellis/, not upstream source..trellis/scripts/and.trellis/workflow.mdin the user project are the default targets. - Errors must be visible. Hook failures should tell the user what was not injected instead of silently leaving the AI without context.
Troubleshooting Path
If the user says "AI did not read Trellis state":
- Check whether the platform settings register the hook.
- Check whether the hook file exists.
- Manually run the
.trellis/scripts/get_context.pyortask.py current --sourcecommand that the hook depends on. - Check whether active task state exists in
.trellis/.runtime/sessions/. - Check whether the platform shell passes session identity.