Kiro

Install context-mode in Kiro, the AWS agentic IDE, with an MCP server plus native preToolUse and postToolUse JSON 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 — preToolUse and postToolUse over JSON on stdin — that reroute data-heavy tool calls into the sandbox 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.

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 22.5+ or Bun on your PATH. 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. The global file lives at ~/.kiro/settings/mcp.json; for a single project, use .kiro/settings/mcp.json instead. 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).

Wire up the hooks

Kiro reads hooks from an agent config file at ~/.kiro/agents/default.json under the hooks key. Add the preToolUse and postToolUse entries below. Each hook points at the dispatcher with the command context-mode hook kiro <event> and a lowercase event name. 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.

~/.kiro/agents/default.json

{
  "hooks": {
    "preToolUse": [
      {
        "matcher": "execute_bash|fs_read|@context-mode/ctx_execute|@context-mode/ctx_execute_file|@context-mode/ctx_batch_execute|@(?!context-mode/)",
        "command": "context-mode hook kiro pretooluse"
      }
    ],
    "postToolUse": [
      {
        "matcher": "*",
        "command": "context-mode hook kiro posttooluse"
      }
    ]
  }
}

Running context-mode upgrade writes these entries for you and keeps them current. context-mode also writes a KIRO.md routing file at your project root on first server startup, which Kiro reads for additional steering — you do not need to create it by hand.

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.

Kiro's agentSpawn (the SessionStart equivalent) and stop hooks are not yet wired, so session restore after compaction is not available on this host yet. The preToolUse enforcement and postToolUse capture are fully active.

What you get on this host

The ctx_* tools are fully available: the agent can run code with ctx_execute, search prior results with ctx_search, and index content with ctx_index. The preToolUse hook makes the routing of data-heavy output a hard intercept rather than advice — it can block a tool call (exit code 2) and steer it into the sandbox. See tool selection for how the agent decides which tool to reach for.

Verify

Confirm the install with the doctor. It checks language runtimes, the FTS5 knowledge base, MCP server registration, and the configured hooks, then reports anything that needs attention.

Verify the setup

context-mode doctor

A clean run means the MCP server is reachable, the hooks are configured, and the routing file is in place.

Configuration

Environment variables, storage, and permission rules.

Tool selection

How the agent chooses the right ctx tool.

Configuration

Tool selection

On this page