Kimi Code notifications: hooks, NotifyUser and TUI settings

Kimi Code's terminal UI sends desktop notifications, set under [notifications] in ~/.kimi-code/tui.toml. They are on by default and, by default, fire only when the terminal is not focused. For more control, a Notification hook in config.toml can run any command when a background task completes. The opt-in NotifyUser tool posts progress updates mid-turn, and the web UI has its own notification toggles. If you run several sessions, Orbtile shows each Kimi Code session on a Logitech MX Creative Keypad or an Android phone.

Overview of Kimi Code notification channels

Kimi Code has several notification channels, and each one is set in a different place.

Configure TUI, terminal and web UI notifications

Kimi Code keeps its settings in ~/.kimi-code/, or in $KIMI_CODE_HOME when that is set. config.toml holds runtime settings such as models, providers, permissions and hooks. tui.toml holds terminal UI preferences, including notifications.

# Written in ~/.kimi-code/tui.toml
[notifications]
enabled = true                        # default: send desktop notifications
notification_condition = "unfocused" # default; the other value is "always"

With "unfocused", Kimi Code notifies you only when the terminal is not focused. Set it to "always" to be notified every time. Changes apply on the next start, or straight away with /reload-tui. The /config, /theme and /editor commands also write to tui.toml for you.

Type / in the TUI input box to see slash commands, then press Enter to run one:

Idle-only commands are blocked while a session is streaming output or compacting context. Press Esc or Ctrl-C to interrupt first.

Kimi Code also signals through the terminal and the browser:

• From version 2.3.0, Kimi Code generates a session title after the first turn and shows it as the terminal window title.
• From version 2.4.0, it reports main-session and subagent status to compatible terminals with OSC 7501.
• The web UI, opened with kimi web or /web in the TUI, notifies you when a tool needs approval.
• Its Settings have separate toggles for completion notifications, question notifications and the completion sound.
• Question notifications are off by default, so question text reaches your desktop only after you opt in.

Pop up desktop notifications with Kimi Code hooks

Hooks run a local shell command when a lifecycle event happens. A common use is a system notification when a background task completes, so you come back to review the results.

Add a Notification hook in config.toml

Add rules to [[hooks]] in ~/.kimi-code/config.toml. This rule runs terminal-notifier, which must be installed on macOS, when a background task completes:

# Written in ~/.kimi-code/config.toml
[[hooks]]
event = "Notification" # Trigger: when a background task status changes
matcher = "task\\.completed" # Only care about "completed" notifications
command = "terminal-notifier -title Kimi -message 'Task done'"

Save the file and start a new session. Each [[hooks]] entry allows only these four fields. Extra fields cause the config file to fail to load.

How hook execution, stdin JSON and fail-open behaviour work

When an event triggers [[hooks]] rules:

• Matching rules run in parallel from the session's project directory.
• Rules with identical commands run only once.
• On non-Windows platforms, a hook that times out gets a signal first and is then force-terminated.
• If a script errors or times out, Kimi Code carries on without interrupting your work.

Each triggered hook receives base JSON on stdin, plus fields for its event:

{
  "hook_event_name": "PreToolUse",
  "session_id": "session_abc",
  "session_title": "Fix the login page",
  "client_type": "kimi_code_cli",
  "cwd": "/path/to/project"
}

Only PreToolUse, Stop and UserPromptSubmit can block. They block with exit code 2, or with stdout JSON that sets hookSpecificOutput.permissionDecision to "deny". All other events are observation-only:

Enable mid-turn progress updates with NotifyUser

Added in Kimi Code CLI 2.2.0, NotifyUser is a built-in tool that lets the main agent and subagents post progress updates without ending the turn. Its approval default is Auto-allow.

Each update has two parts:

• An optional title, one short line that is shown on its own wherever space is tight.
• A message with the details.

An update appears only after a successful tool result confirms it was displayed. The transcript keeps a record of whether each call displayed an update. Important findings still belong in the final reply or the subagent's handoff.

Where NotifyUser updates appear

• In the CLI TUI, updates appear in the Updates panel above the input box, grouped by agent.
• Press Ctrl-N to browse them, or click the panel in fullscreen mode.
• Fullscreen mode is the experimental tui_mode = "fullscreen" setting in tui.toml.
• The panel folds when the turn ends and resets for the next main-agent turn.
• In the desktop app and kimi web, each update is a progress row showing its title, and a click opens the message.

How to turn on NotifyUser

NotifyUser is off by default. Enable it in ~/.kimi-code/config.toml:

# Written in ~/.kimi-code/config.toml
[experimental]
notify_user = true

You can also enable it in other ways:

• Set the environment variable KIMI_CODE_EXPERIMENTAL_NOTIFY_USER=1.
• Turn on NotifyUser in /experiments in the TUI.
• Turn it on in the Lab section of Settings in the desktop app or web UI.

Session rules when you change it:

• The setting applies only to sessions created afterwards.
• Sessions created while it was off have neither the tool nor its prompt guidance, so start a new session.
• Changing only this flag in /experiments does not reload the session.
• Turning it off hides the panel and disables its shortcuts.
• Existing NotifyUser calls then finish normally and report that the update was not displayed.

How background tasks and questions notify the agent

These notifications go to the agent, not to you. They let it act on a finished command, subagent or answer. To hear about them yourself, use the Notification hook above.

Three built-in tools create background tasks. Bash runs commands:

• With run_in_background=true, Bash returns a task ID at once and notifies the agent when the task finishes.
• A background Bash call must include a description.
• A foreground command that hits its 60-second default timeout is not killed and keeps running as a background task.
• Background tasks time out after 600 seconds by default, set by bash_task_timeout_s, where 0 means no timeout.
• In kimi -p print mode, background tasks have no timeout by default.
• Set bash_auto_background_on_timeout = false under [background] to kill timed-out commands instead.

Agent runs subagents:

• With run_in_background=true, Agent starts a background subagent and returns a task ID.
• When the subagent is done, its result reaches the main agent as a synthetic User message.
• Agent tasks time out after 2 hours by default, set by [subagent] timeout_ms or KIMI_SUBAGENT_TIMEOUT_MS.
• If a subagent is stopped, times out or fails, the parent still gets its text so far, marked as incomplete.

AskUserQuestion asks you questions:

• It accepts 1 to 4 questions with 2 to 4 choices each, and adds an "Other" option automatically.
• With background set to true, it returns a task ID, and the question stays open after the turn ends.
• Your answer reaches the agent as a notification when you respond.

Four tools manage background tasks:

• TaskList lists only running tasks by default, with a limit of 20 that you can set from 1 to 100.
• /tasks in the TUI browses the same background task list.
• TaskOutput returns an immediate snapshot with an output_path and at most the latest 32 KB of output.
• WaitFor suspends the turn until a task finishes, its required timeout of up to 90 seconds passes, or a steer message arrives.
• A task already reported by WaitFor does not also produce an automatic completion notification.
• TaskStop stops a running task, needs your approval and is blocked in Plan mode.

In the TUI, /undo withdraws recent prompts. It restores conversation history, todo lists, plan mode and task notifications together.

Watch Kimi Code sessions on a keypad or phone with Orbtile

If you run several Kimi Code sessions alongside other coding agents, Orbtile shows each one as a key on the Logitech MX Creative Keypad or a tile on an Android phone. The phone needs Android 8.0 or later and Orbtile Mobile. Orbtile runs on a Mac with macOS 14.0 Sonoma or later and Apple silicon, or on a Windows 11 PC (x64).

• There is nothing to install: Orbtile reads Kimi Code's session files on your computer and shows each session's state and live text.
• It reads them from ~/.kimi-code, or %USERPROFILE%\.kimi-code on Windows, and KIMI_CODE_HOME overrides this folder.
• Working Kimi Code sessions glow magenta, and waiting sessions turn terracotta and move to the front.
• A tap on a session key brings its terminal or Kimi window to the front.
• A tap on key 9 focuses the first waiting session, including sessions on other pages.
• Optional Kimi Code hooks add a Compacting state and slightly earlier updates, and they never approve or deny anything.

On a Mac or a Windows PC, you can answer some requests from the keypad for sessions in Kimi's own server. Start it with kimi web or kimi rc, or type /rc in a Kimi terminal session to hand it over.

• Hold the waiting session's key to open Focus mode.
• For a permission request, press Deny on key 7, or hold Allow on key 9 for 0.6 seconds.
• The keypad can answer a permission request for up to 2 minutes, or less if Kimi Code's own limit is shorter.
• For a question with listed options, pick options on keys 1, 2, 3 and 7, then hold Send on key 9.

Other Kimi sessions, other questions and written answers stay on your computer. Kimi's server API is experimental. If a Kimi update changes it, keypad answers stop until Orbtile catches up, and sessions still show.

For how Kimi's browser server starts, authenticates with bearer tokens and shares sessions over a local network, see Kimi Code web UI: kimi web, /web, tokens and LAN setup.

Orbtile also shows Claude Code, Codex, ZCode and Antigravity sessions. See Approve agent tool calls without switching windows and Get notified when Claude Code needs approval or finishes.