Agents

Let a coding agent build layers and bindings through Vimputer's MCP server.

Vimputer’s CLI runs an MCP 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:

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):

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