Kiro

Install context-mode in Kiro, AWS's agentic IDE, with an MCP server plus native preToolUse, postToolUse, agentSpawn, and userPromptSubmit hooks that reroute data-heavy tool output into the sandbox.

Kiro is AWS's agentic IDE and CLI. It integrates context-mode through an MCP server and Kiro's native lifecycle hooks — delivered over JSON on stdin — that reroute data-heavy tool calls into the sandbox, inject session context on start, and capture tool events for later search. Instead of reading raw bytes, the model writes a program that processes the data and prints only the answer. The ctx_* tools are always available alongside the hook enforcement.

preToolUse — reroutes data-heavy tool calls into the sandbox
postToolUse — captures tool events for later search
agentSpawn — injects session context on start (the SessionStart equivalent)
userPromptSubmit — captures the submitted prompt over JSON on stdin

context-mode runs 100% locally with zero telemetry. Indexing and execution never leave your machine.

Install

Kiro has no plugin marketplace, so install the package globally first, then wire up the MCP server and the hooks.

Check the prerequisites

You need Node.js 22.5+ (or Bun) on your PATH, and Kiro with MCP enabled (Settings, then search "MCP"). The hook dispatcher and sandbox run on this runtime.

Check the runtime

node --version

Install the package

This installs the MCP server, the hook dispatcher, and the context-mode command line.

Global install

npm install -g context-mode

Register the MCP server

Add an MCP server entry to the Kiro MCP config. For a single project, use .kiro/settings/mcp.json; for a global install, use ~/.kiro/settings/mcp.json. Both use Kiro's standard mcpServers JSON format and point at the global context-mode binary.

.kiro/settings/mcp.json

{
  "mcpServers": {
    "context-mode": {
      "command": "context-mode"
    }
  }
}

context-mode detects Kiro from the MCP client handshake (clientInfo.name reports Kiro CLI).

context-mode doctor validates only the global ~/.kiro/settings/mcp.json, even if you registered MCP at the project level. Prefer the global path, or register both.

Wire up the hooks

Kiro reads hooks from an agent config at ~/.kiro/agents/default.json under a top-level hooks key — not from a .kiro/hooks/ file. The reliable way to write them in the correct place is to run the upgrade command:

Wire and refresh the hooks

context-mode upgrade

This wires the preToolUse, postToolUse, agentSpawn, and userPromptSubmit hooks into ~/.kiro/agents/default.json and keeps them current. The preToolUse matcher targets the high-flood tools (execute_bash, fs_read), context-mode's own ctx_* tools, and any external MCP namespace that is not context-mode:

preToolUse matcher

execute_bash|fs_read|@context-mode/ctx_execute|@context-mode/ctx_execute_file|@context-mode/ctx_batch_execute|@(?!context-mode/)

(Optional) Copy the routing file

agentSpawn already injects the routing block at session start, so this is a belt-and-braces step for extra model awareness. Copy KIRO.md to your project root if you want it — context-mode does not auto-write it into your git tree.

Copy the routing instructions

cp node_modules/context-mode/configs/kiro/KIRO.md ./KIRO.md

Restart Kiro after wiring the hooks.

Hooks

Hook	What it does
`preToolUse`	Inspects and reroutes data-heavy tool calls into the sandbox before they run, blocking with exit code 2 when needed.
`postToolUse`	Captures executed tool calls into the FTS5 knowledge base for later search.
`agentSpawn`	The SessionStart equivalent — injects `additionalContext` on session start to restore routing and prior state after compaction.
`userPromptSubmit`	Captures the submitted prompt for session continuity.

Each hook is dispatched through the context-mode binary with a lowercase event name. The standalone CLI dispatcher tokens are:

Hook dispatch commands

context-mode hook kiro pretooluse
context-mode hook kiro posttooluse

agentSpawn and userPromptSubmit are written into ~/.kiro/agents/default.json by context-mode upgrade and fire through Kiro's runtime, but they are not exposed as standalone context-mode hook kiro <event> dispatcher tokens today. Run context-mode upgrade to get the full hook set. The stop event is not wired.

What you get on this host

The ctx_* tools are fully available, exposed under the @context-mode/ namespace (e.g. @context-mode/ctx_batch_execute, @context-mode/ctx_search):

Run code: ctx_execute runs a program in the sandbox
Search prior results: ctx_search queries the FTS5 knowledge base
Index content: ctx_index stores content for later search

Two hooks make this enforcement rather than advice:

preToolUse turns the routing of data-heavy output into a hard intercept — it can block a tool call (exit code 2) and steer it into the sandbox.
agentSpawn restores session context after compaction.

See tool selection for how the agent decides which tool to reach for.

Verify your savings

Confirm context-mode is actually saving you tokens, not just that the tools respond.

In the Kiro panel, open the MCP Servers tab and confirm "context-mode" shows a green status indicator.
In chat, type ctx stats to see the tokens saved and the context-window savings ratio for the session, plus the per-tool breakdown. Run a few data-heavy commands first so the numbers reflect real routing.
Run context-mode doctor in your terminal to confirm the MCP server and the tool-routing hooks are registered.

Confirm the install

context-mode doctor

The doctor checks the language runtimes, the FTS5 knowledge base, MCP registration at ~/.kiro/settings/mcp.json, and the preToolUse/postToolUse hooks in ~/.kiro/agents/default.json:

Hook	Doctor status	Missing-hook behavior
`preToolUse`	Required	Fails with the fix `context-mode upgrade` — the exact check that catches a hook config placed in the wrong location.
`postToolUse`	Optional	Non-fatal `warn` with no fix attached.
`agentSpawn`	Not checked	Doctor does not separately validate it.
`userPromptSubmit`	Not checked	Doctor does not separately validate it.

A clean doctor run confirms the MCP server and the preToolUse/postToolUse hooks are registered; agentSpawn and userPromptSubmit are wired by context-mode upgrade but are not separately checked by doctor.

A clean doctor run plus a climbing ctx stats savings ratio means context-mode is routing your data-heavy work into the sandbox.

Configuration

Environment variables, storage, and permission rules.

Tool selection

How the agent chooses the right ctx tool.

Configuration

Tool selection

On this page