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

DeepSeek-TUI supports pre and post lifecycle hooks defined in 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, 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 (lines 80-81), hook configurations reside in a top-level [hooks] table within your 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:

[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:

[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:

[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:

[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:

# ~/.deepseek/config.toml

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

Console output appears as:

[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:

[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:

{"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
• 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 (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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}