企业官网建设流程全解析

jcode Spawn Hook完整教程：如何自定义新会话在哪个终端打开

【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode

jcode是一款主打内存效率的终端 AI 编程助手，它的Spawn Hook（派生钩子）让你自定义每一个新会话在哪里打开：tmux 窗口、kitty 标签页、zellij 面板，甚至按会话类型智能路由。本教程带你快速上手这个强大的终端会话管理功能。

什么是 jcode Spawn Hook

jcode 会在多个场景下打开新终端窗口：swarm 智能体派生、恢复会话到新终端、self-dev 会话、重启恢复、jade relay 启动。默认情况下，jcode 自动检测你安装的终端模拟器（kitty、wezterm、alacritty、gnome-terminal 等）并打开新窗口。

而Spawn Hook允许一个外部程序接管这个派生过程，由它决定新会话在哪里、以什么形式出现——这正是多终端路由、会话管理器（如 herd 风格封装）的核心能力。

核心机制：jcode 执行<spawn_hook> <jcode二进制> <参数...>，把完整命令行追加为额外参数，工作目录即会话的工作目录。

快速配置：3 步完成 Spawn Hook

第 1 步：编辑配置文件~/.jcode/config.toml，添加[terminal]段：

[terminal] spawn_hook = "tmux new-window"

第 2 步：或者使用环境变量（环境变量始终优先于配置文件）：

export JCODE_SPAWN_HOOK="tmux new-window" # 设为空值可临时禁用配置文件中的钩子 export JCODE_SPAWN_HOOK=

第 3 步：触发任意有头（headed）派生——比如让 swarm 启动一个智能体——新会话就会按你的钩子打开。

钩子命令按 shell 规则解析（支持引号和反斜杠转义），但直接执行而不经过 shell。若钩子无法启动（命令不存在、解析失败），jcode 会记录警告并回退到内置终端检测，不会中断你的工作流。

新会话从哪来：5 种派生场景

每次派生都会导出JCODE_SPAWN_KIND环境变量，标识新会话的来历：

这意味着你可以按场景路由：swarm 智能体进 tmux 面板，恢复会话开 kitty 标签页。

元数据环境变量：钩子的"眼睛"

钩子进程会收到一组JCODE_SPAWN_*环境变量，帮你精准控制新会话：

• JCODE_SPAWN_SESSION_ID：窗口将运行的 jcode 会话 ID
• JCODE_SPAWN_TITLE：建议的窗口/标签标题（含会话图标+名称）
• JCODE_SPAWN_CWD：会话工作目录
• JCODE_SPAWN_PROGRAM：jcode 二进制路径
• JCODE_SPAWN_COMMAND：完整命令行（shell 转义后），适合只接受一个字符串的启动器
• JCODE_SPAWN_SWARM_ID/JCODE_SPAWN_COORDINATOR_SESSION_ID：仅 swarm 派生，标识所属 swarm 与协调者
• JCODE_FRESH_SPAWN：1表示全新窗口交接

实战：3 个经典路由方案

方案一：tmux 每个智能体一个窗口

[terminal] spawn_hook = "tmux new-window"

若你想保留 jcode 内置的"右侧分屏"行为（它会自动检测 tmux 并定向到请求者的TMUX_PANE），可显式写：

[terminal] spawn_hook = "tmux split-window -h"

方案二：kitty 每个智能体一个标签页

利用 kitty 远程控制：

[terminal] spawn_hook = "kitty @ --to unix:/tmp/kitty.sock launch --type=tab --"

方案三：自定义路由脚本（完全控制）

指向一个脚本，按派生类型分流：

#!/usr/bin/env bash # ~/bin/jcode-spawn-router：argv 为 jcode 命令，env 为 JCODE_SPAWN_* 元数据 case "$JCODE_SPAWN_KIND" in swarm-agent) tmux new-window -n "swarm:${JCODE_SPAWN_SWARM_ID:0:8}" "$@" 2>/dev/null \ || tmux split-window "$@" ;; *) kitty --title "$JCODE_SPAWN_TITLE" -e "$@" & ;; esac

⚠️注意：若钩子启动后以非零退出（但没启动任何窗口），jcode不会触发内置回退——路由脚本应像上例一样自行处理兜底。

对于只接受单个 shell 字符串的启动器（如 zellij），直接消费$JCODE_SPAWN_COMMAND：

zellij action new-pane -- bash -lc "$JCODE_SPAWN_COMMAND"

多终端路由：新会话为什么开错终端？

jcode 的服务器进程是长驻的，它在启动时捕获TMUX、ZELLIJ_SESSION_NAME、KITTY_WINDOW_ID、DISPLAY等终端标识变量。当你之后从另一个终端连上同一服务器，服务器里的副本已经过期，钩子可能把新会话开进旧终端。

jcode 的解法很优雅：每个连接的客户端会快照自己的终端环境变量并上报，服务器执行钩子时重新导出请求客户端的值——钩子自然跟随你实际正在看的那个终端。同时还会导出JCODE_CLIENT_<NAME>别名（如JCODE_CLIENT_TMUX），方便钩子显式区分客户端与服务器终端。

覆盖范围包括 tmux、zellij、screen、herdr 等复用器，kitty、wezterm、ghostty、alacritty、iTerm、Windows Terminal 等模拟器，以及DISPLAY/WAYLAND_DISPLAY。相关实现见 CLIENT_TERMINAL_ENV_VARS。

Focus Hook：让焦点也归你管

当 jcode 想把已有会话窗口带到前台时，默认在 X11 上做 wmctrl/xdotool 标题搜索——这在 Wayland 或复用器里不可用。如果你用 spawn hook 接管了窗口放置，也应接管焦点：

[terminal] spawn_hook = "tmux new-window" focus_hook = "~/bin/jcode-focus"

Focus hook 会收到JCODE_FOCUS_SESSION_ID和JCODE_FOCUS_TITLE两个环境变量，失败时同样回退到内置焦点路径。环境变量覆盖：JCODE_FOCUS_HOOK（空值禁用）。

常见误区速查

相关资源

• 📄 官方设计文档：docs/SPAWN_HOOK.md
• 🧩 配置定义：TerminalConfig
• 🔧 环境变量覆盖实现：env_overrides.rs
• 🚀 终端派生核心：jcode-terminal-launch
• 🐝 Swarm 架构背景：docs/SWARM_ARCHITECTURE.md

掌握 Spawn Hook 后，你的每一个 jcode 新会话都能精确落在预期的终端里——这是构建多智能体工作流和会话管理器的关键拼图。

【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode