bytedance / bytedance/trae-agent
Feature Request: Lifecycle hooks for external tool integration
- Dominant language
- Python
- Stars
- 12.1k
- Forks
- 1.3k
- PR merge metrics
- No merged PRs in 30d
Description
## Description
It would be great if trae-agent supported **lifecycle hooks** — user-defined commands that fire on agent events like session start/stop, tool use, prompt submission, etc.
The idea: when an event occurs (e.g., the agent starts using a tool), trae-agent spawns a subprocess, pipes event metadata as JSON to stdin, and optionally reads a JSON response from stdout.
### Suggested hook events
| Event | When it fires |
|-------|--------------|
| `SessionStart` | Agent session begins |
| `SessionStop` | Agent session ends |
| `UserPromptSubmit` | User sends a prompt |
| `PreToolUse` | Before a tool executes |
| `PostToolUse` | After a tool completes |
### Suggested config format
In `trae_config.yaml`:
```yaml
hooks:
SessionStart:
- type: command
command: "/path/to/my-tool --source trae"
PreToolUse:
- type: command
command: "/path/to/my-tool --source trae"
matcher: "*"
```
The subprocess receives JSON on stdin like:
```json
{
"hook_event_name": "PreToolUse",
"session_id": "abc-123",
"cwd": "/home/user/project",
"tool_name": "bash",
"tool_input": { "command": "ls -la" }
}
```
## Reason
This pattern has become a **de facto standard** across CLI coding agents:
- **Claude Code** — pioneered this hooks system, now used by 20+ external tools
- **OpenAI Codex CLI** — adopted the same hooks pattern
- **Google Gemini CLI** — `~/.gemini/settings.json` hooks
- **Cursor IDE** — `~/.cursor/hooks.json`
- **GitHub Copilot CLI**, **Qoder (Alibaba)**, **CodeBuddy (Tencent)**, **Factory Droid** — all ship with hooks
Tools built on this ecosystem include:
- **Status panels** (macOS notch overlays showing agent activity)
- **Sound notifications** (audio cues for tool use, completion, errors)
- **Usage trackers** (token consumption monitoring)
- **Custom approval flows** (gate dangerous operations)
Without hooks, trae-agent is invisible to this entire ecosystem. Adding hooks would let trae-agent plug into all of these tools with zero effort from their side — they already speak this protocol.
### Complementary to #90 (OpenTelemetry)
Hooks and OTel serve different needs:
- **OTel** = pull model, great for post-hoc tracing and observability dashboards
- **Hooks** = push model, great for real-time external tool integration (UI panels, sound, approval gates)
Both are valuable and complementary.
## Additional context
I maintain [Vibe Island](https://vibeisland.app), a macOS notch status panel for coding agents. We currently support 9 CLI tools via their hooks systems. Happy to help test or contribute a PR if this direction makes sense.
Reference implementations:
- Claude Code hooks: https://docs.anthropic.com/en/docs/claude-code/hooks
- Codex hooks: configured via `~/.codex/hooks.json`
Contributor guide
Research direction
Start by locating the configuration handling for trae_config.yaml and the agent lifecycle and tool-execution entry points; the issue names no implementation files or tests. Compare the referenced Claude Code and Codex hook behavior, then define the supported events, JSON contract, command execution, and matcher semantics. Done means configured hooks receive the documented event data and can return the documented response without disrupting normal agent operation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100