# How to Configure Hooks in DeepSeek-TUI for Pre/Post Lifecycle Events

> Learn to configure DeepSeek-TUI hooks for pre/post lifecycle events. Control output with stdout, JSONL, or webhooks for every agent execution. Customize your agent workflow today.

- Repository: [DeepSeek/awesome-deepseek-agent](https://github.com/deepseek-ai/awesome-deepseek-agent)
- Tags: how-to-guide
- Published: 2026-08-15

---

**DeepSeek-TUI supports pre and post lifecycle hooks defined in [`config.toml`](https://github.com/deepseek-ai/awesome-deepseek-agent/blob/main/config.toml) under the `[hooks]` table, enabling stdout, JSONL file, or webhook output for every agent execution.**

DeepSeek-TUI, part of the `deepseek-ai/awesome-deepseek-agent` repository, provides a flexible hook system that triggers custom actions before and after agent tasks. By configuring the `[hooks]` section in your [`config.toml`](https://github.com/deepseek-ai/awesome-deepseek-agent/blob/main/config.toml), you can capture execution metadata through multiple output channels. This guide explains the exact schema and implementation details found in the source documentation.

## Understanding the [hooks] Configuration Schema

According to the DeepSeek-TUI documentation at [`docs/deepseek-tui.md`](https://github.com/deepseek-ai/awesome-deepseek-agent/blob/main/docs/deepseek-tui.md) (lines 80-81), hook configurations reside in a top-level `[hooks]` table within your [`config.toml`](https://github.com/deepseek-ai/awesome-deepseek-agent/blob/main/config.toml). Each hook—`pre` for actions before execution and `post` for actions after completion—accepts a dictionary of output destinations.

The configuration supports three output formats:

| Format | Key | Description |
|--------|-----|-------------|
| **stdout** | `stdout = true` | Prints the event payload directly to the console |
| **JSONL** | `jsonl = "/path/to/file.log"` | Appends the payload as a new line to a JSON Lines file |
| **Webhook** | `webhook = "https://example.com/endpoint"` | Sends the payload via HTTP POST to a remote endpoint |

You can combine these formats within a single hook definition to log locally and notify remote systems simultaneously.

## Configuring Pre-Execution Hooks

Pre-hooks execute before the agent begins processing. Define them under `[hooks]` with the key `pre`.

### stdout Output

Enable console output for debugging or monitoring:

```toml
[hooks]
pre = { stdout = true }

```

When the agent starts, DeepSeek-TUI prints the event payload to the terminal, useful for real-time debugging in interactive sessions.

### JSONL File Logging

Persist pre-execution events to a JSON Lines file for audit trails:

```toml
[hooks]
pre = { jsonl = "/tmp/deepseek-pre.log" }

```

Each invocation appends a single line of JSON containing the `event`, `session_id`, `agent_id`, `timestamp`, and `metadata` fields.

### Webhook Integration

Trigger external CI/CD pipelines or monitoring systems:

```toml
[hooks]
pre = { webhook = "https://hooks.example.com/deepseek/pre" }

```

DeepSeek-TUI sends an HTTP POST request with a JSON body to the specified endpoint before the agent executes.

## Configuring Post-Execution Hooks

Post-hooks execute after the agent finishes or is cancelled. Use the `post` key under `[hooks]`.

### Combined Output Example

Log to a file and send a webhook notification upon completion:

```toml
[hooks]
post = { jsonl = "/var/log/deepseek/post.log", webhook = "https://api.example.com/notify" }

```

This configuration ensures local persistence and external notification when tasks complete, fail, or are interrupted.

## Complete Configuration Examples

### Minimal stdout Configuration

For quick debugging without file persistence:

```toml

# ~/.deepseek/config.toml

[hooks]
pre  = { stdout = true }
post = { stdout = true }

```

Console output appears as:

```text
[pre] 2024-04-01T12:34:56Z session=abc123 agent=repo-worker
[post] 2024-04-01T12:35:12Z session=abc123 agent=repo-worker status=completed

```

### Full Integration Setup

Combine all three output methods for comprehensive observability:

```toml
[hooks]
pre  = { stdout = true, jsonl = "/tmp/deepseek-pre.log", webhook = "https://example.com/pre" }
post = { stdout = true, jsonl = "/tmp/deepseek-post.log", webhook = "https://example.com/post" }

```

This setup logs to `/tmp/deepseek-pre.log` and `/tmp/deepseek-post.log` while simultaneously alerting external endpoints.

## Payload Structure and Event Data

When DeepSeek-TUI triggers a hook, it constructs a standardized payload containing:

- `event`: String value `"pre"` or `"post"` indicating the lifecycle phase
- `session_id`: Unique identifier for the current execution session
- `agent_id`: The specific agent generating the event
- `timestamp`: ISO-8601 formatted timestamp
- `metadata`: User-defined key-value pairs attached to the task

For JSONL output, each line represents one event object:

```json
{"event":"pre","session_id":"abc123","agent_id":"repo-worker","timestamp":"2024-04-01T12:34:56Z","metadata":{}}

```

Webhooks receive this identical JSON structure as the POST body.

## Summary

- Configure lifecycle hooks in DeepSeek-TUI by adding a `[hooks]` table to your [`config.toml`](https://github.com/deepseek-ai/awesome-deepseek-agent/blob/main/config.toml)
- Define `pre` hooks for pre-execution actions and `post` hooks for post-execution actions
- Choose from three output formats: **stdout** for console debugging, **jsonl** for file-based logging, and **webhook** for HTTP notifications
- Combine multiple formats in a single hook definition for redundant logging
- Reference the official documentation at [`docs/deepseek-tui.md`](https://github.com/deepseek-ai/awesome-deepseek-agent/blob/main/docs/deepseek-tui.md) (lines 80-81) in the `deepseek-ai/awesome-deepseek-agent` repository for schema validation

## Frequently Asked Questions

### What file do I edit to configure DeepSeek-TUI hooks?

You edit the [`config.toml`](https://github.com/deepseek-ai/awesome-deepseek-agent/blob/main/config.toml) configuration file, typically located at `~/.deepseek/config.toml` or your project's root directory. Add a top-level `[hooks]` table with `pre` and `post` keys as documented in [`docs/deepseek-tui.md`](https://github.com/deepseek-ai/awesome-deepseek-agent/blob/main/docs/deepseek-tui.md) at lines 80-81.

### Can I use multiple output formats for the same hook?

Yes. Each hook accepts a dictionary where you can simultaneously set `stdout = true`, `jsonl = "/path/to/file"`, and `webhook = "https://..."`. DeepSeek-TUI emits the payload to all configured destinations when the lifecycle event fires.

### What data is included in the webhook payload?

The JSON payload includes `event` (pre/post), `session_id`, `agent_id`, `timestamp` (ISO-8601), and `metadata` (user-defined key-value pairs). This structure allows external systems to track session lifecycle, timing, and custom task attributes.

### Where is the hook feature documented in the source code?

The hook configuration schema is documented in [`docs/deepseek-tui.md`](https://github.com/deepseek-ai/awesome-deepseek-agent/blob/main/docs/deepseek-tui.md) at lines 80-81 within the `deepseek-ai/awesome-deepseek-agent` repository. This section describes the `[hooks]` table structure and its placement in [`config.toml`](https://github.com/deepseek-ai/awesome-deepseek-agent/blob/main/config.toml).