bytedance / bytedance/trae-agent

Feature Request: Lifecycle hooks for external tool integration

Open
#397 0 comments 2 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.