---
title: Agents
description: Let a coding agent build layers and bindings through Vimputer's MCP server.
---

Vimputer's CLI runs an [MCP](https://modelcontextprotocol.io) server, so an agent
like Claude Code or Codex can read your layers and add bindings. The agent talks
to the running app over a local socket that only your user account can open; no
network port is opened. Vimputer checks every edit before saving it, and the
open window picks it up straight away.

## Connect an agent

Build the CLI once, then register it with your agent:

```bash
pnpm --filter @vimputer/cli build
claude mcp add vimputer -- node ~/code/projects/vimputer/packages/cli/dist/index.js mcp
```

Codex takes the same command as an `mcp_servers` entry. Vimputer has to be
running while the agent works.

## Tools

| Tool | Does |
| --- | --- |
| `layers_list` | Layers in sidebar order, with how many bindings each has |
| `layer_get` | One layer and its bindings |
| `layer_create`, `layer_update`, `layer_delete` | Edit layers. Deleting a layer moves its bindings to its parent |
| `bindings_put` | Add bindings, or replace them by id. Returns any conflicts the new bindings cause |
| `bindings_delete` | Remove bindings |
| `conflicts` | Keys that shadow or duplicate each other |
| `actions_search` | Find plugin and Vimputer actions by name, each ready to put in a binding |
| `config_read` | The whole config, including the variables and apps that conditions refer to |
| `generate` | Write `karabiner.test.json`. With `activate: true`, write the live `karabiner.json` and switch to its profile |

An agent can edit your config and write the test file without changing the
remaps you're using. Your keys only change when it calls `generate` with
`activate: true`, or when you press **Generate & Activate**.

If you have unsaved changes in the window when an agent writes, the window
reloads the agent's version and your last edit is dropped.

## From the shell

The CLI does the same without an agent (`vimputer` is `node packages/cli/dist/index.js`):

```bash
vimputer layers list
vimputer layers add Windows --parent <layerId>
vimputer config generate            # test file
vimputer config generate --activate # live karabiner.json
```