Implement User-Configurable Lifecycle Hooks System

[Verdenroz]

What feature would you like to see?

Description

Currently, Kimi Code CLI operates with a fixed lifecycle. Users cannot easily inject custom context or trigger external workflows without modifying the core codebase.

Proposal

I propose implementing a Hooks System inspired by Claude Code. This would allow users to configure scripts that trigger at specific lifecycle events (e.g., SessionStart, PreToolUse, UserPromptSubmit), enabling local extensibility without bloating the core tool.

Proposed Approach

Implement a hook system configurable via a user settings file (e.g., ~/.kimi/settings.json or project-local config).

Additional information

No response

[xxchan]

For now we have no plan to support this. What's your use case for it?

For workflow-like use cases, you may try the Agent Flow feature instead.

[Verdenroz]

Thanks! I see how Agent Flows help with complex reasoning, but I am concerned they may waste tokens on tasks that shouldn't need to be thought of.

I am looking for a way to execute deterministic commands—like auto-formatting or cleanup—without the AI needing to 'decide' to do them. A lifecycle hook (like SessionEnd) allows these tasks to run 'invisibly' at the system level. This prevents Kimi from wasting context window space and tokens on maintenance tasks that don't actually require an LLM's judgment.

[stebbins]

@xxchan curious if you've seen Steve Yegge's gastown project? It uses hooks heavily; hooks appear to be useful for orchestration of agents, at least so far. Although it does seem with how models have been developing, eventually this structure will be counterproductive, like all the other structures that have been added around models so far. Presumably models will get to a point where they could "implement" the gastown-like orchestration itself, parallel subagents etc -- Kimi seems to already be on this path (agent swarm is beautiful to watch...)

I've been rambling a bit -- from my perspective at least, hooks have been an interesting aspect of how gastown orchestrates agent CLI instances. I'm not sure if adding them fits with the design philosophy of Kimi Code CLI, but maybe something to consider.

BTW -- I think this "gastown-style orchestration hook" concept can be implemented without hooks. My understanding is that hooks are mainly used to inject a "first" prompt into a running session:

1. agent CLI session begins
2. hook injects initial prompt

however, I think same could be accomplished by simply allowing the user to pass a "starting prompt" in when invoking the agent CLI -- but not terminating the session on response, which is how this functionality differs from the current --prompt / --command.

If hooks are unappealing, consider the latter, as I don't think it would conflict with Kimi Code CLI design philosophy: add a command to start a session with a prompt and don't terminate the session on completion. This would unlock a lot of the capabilities with gastown-style agent orchestration, because some other process can initiate long-lived Kimi Code CLI sessions with a starting prompt.

---

Anyways, sorry for hijacking your issue @Verdenroz , as my use-case sounds a little different than yours.

and @xxchan , warm greetings and well wishes from USA, and thank you and Moonshot team for all the work with Kimi models + tooling. Excellent quality and approach! Your blog is also very interesting and I've spent some time the last few days reading it. I'm curious for your thoughts around gastown-style orchestration. I've been investigating implementing ACP support in gastown using Kimi Code CLI as a test case. Anyways, if you'd like to discuss further, and to avoid polluting this thread even more, feel free to email hcstebbins@gmail.com

---

edit: submitted #864

[Verdenroz]

Ah, no problem at all! My use case is more of a minor optimization itch for somebody who wants complete control. Good luck on your path and thanks for sharing, I've never seen the gastown project.

[IndenScale]

Hi @Verdenroz and everyone interested in lifecycle hooks!

Great news — we have implemented a comprehensive AgentHooks system in PR #1131. This implementation addresses the feature request in this discussion.

What is Implemented

Our AgentHooks system is inspired by but extends beyond Claude Code approach:

Configuration: Uses HOOK.md files with YAML frontmatter (more flexible than JSON settings):

---
name: block-dangerous-commands
trigger: pre-tool-call
match:
  tool: Shell
---

Supported Events (canonical names):

• Session lifecycle: pre-session, post-session
• Agent turn: pre-agent-turn, post-agent-turn
• Quality gate: pre-agent-turn-stop
• Tool interception: pre-tool-call, post-tool-call, post-tool-call-failure
• Subagent: pre-subagent, post-subagent
• Context: pre-context-compact, post-context-compact

Hook Locations:

• User-level: ~/.config/kimi/hooks/
• Project-level: .agents/hooks/

Built-in Hooks included:

• block-dangerous-commands: Security hook for shell commands
• enforce-tests: Quality gate checking test existence
• auto-format-python: Auto-format Python files
• session-logger: Session audit logging

New /hooks Command: Lists all loaded hooks, their metadata, and execution stats.

About the AgentHooks Standard

This implementation follows the AgentHooks (https://github.com/IndenScale/AgentHooks) specification — a generic standard for agent lifecycle hooks that works across different CLI tools (not just Kimi Code CLI).

The spec defines:

• Standardized trigger events
• Exit code protocol (0=allow, 2=block, 1=internal error)
• Hook discovery and execution semantics

Would love to hear your thoughts on the current implementation and whether it covers your use cases! Feedback welcome on PR #1131.

[ishita-0301]

I would definitely find this useful. Hooks open up a lot of possibilities without adding complexity to the core CLI. Things like injecting project context, enforcing local policies, running validation automatically, or blocking risky actions become much easier to customize.
I also think the most interesting use cases go beyond context injection. Projects like https://github.com/FailproofAI/failproofai show how hooks can be used to detect repeated failures, prevent premature completion, or enforce execution policies during a run. Giving users lifecycle hooks would make it much easier to experiment with those kinds of behaviors locally.