local-motion Runs Cursor Agents Locally

local-motion is Matt Mireles’ MIT-licensed extension for Visual Studio Code, Microsoft’s code editor, and Cursor, Anysphere’s AI code editor, that runs a local coding model for chat and agent work on macOS. It deals with the annoying parts of using a local LLM with cursor agents: picking a model, starting a server, connecting Cursor, and freeing memory afterward. The useful idea is not that every coding agent should be local; it is that local runtime operations need an on/off switch, a memory budget, and clear repo boundaries. Local Motion is a local-model switch for Cursor and VS Code that loads a compatible model when you need it and unloads it when you are done.

The project showed up as a Show HN-style release on July 10, 2026. As of that date, the repository was small, mostly TypeScript, and focused on macOS with llama.cpp-style GGUF models. That size is part of the story: the problem is not a grand platform problem yet. It is a daily developer problem hiding in plain sight.

Turn the local model on only when you need it

Local Motion’s main move is simple: make the local model feel like something you start for a task, not a daemon you babysit all day.

The README says the extension profiles your Mac, chooses a compatible local coding model, reuses an installed model when possible, and keeps downloaded models on disk so you can switch between heavier and lighter options. It also frees the loaded model from memory when you are finished.

That matters on Apple Silicon because unified memory is shared. A model that is fine during lunch can become painful when Xcode, Docker, Chrome, and a test database are all awake. The trap is treating local inference as free just because the API bill is zero.

A realistic first use is narrow. Ask the local model to inspect a small utility package, explain a flaky test, or draft a refactor plan. Do not start by handing it a multi-package migration while your laptop is already under load.

Notice what still leaves the machine

Local Motion keeps the runtime bound to 127.0.0.1 and, when running inside Cursor, helps connect the local model so it appears in the model picker. The author’s description also mentions a Cloudflare Quick Tunnel, from Cloudflare, to make the connection path work.

That is convenient. It is not the same as saying every byte of the workflow is offline.

The project’s README is careful here: the model stays on the Mac, while Cursor relays chats through its servers. That is a good distinction. A local model can reduce dependency on hosted inference, but the editor workflow may still involve a relay, account, or product integration path.

The practical lesson is to separate three questions before you trust a local agent run: where the model weights live, where the prompt and transcript travel, and what files the agent can edit. Local Motion addresses the first and part of the runtime setup. Your repo rules still address the third.

Put repo boundaries where Cursor will see them

A local model does not make an agent safer by itself. It only changes where inference happens.

For Cursor work, keep the repo boundary close to the code. Cursor rules are the right place for durable project instructions, and an AGENTS.md note can make the same constraints visible to other agent tools. If you are already experimenting with Cursor skills, cursor subagents, or custom agent notes, keep the local-model rule boring and specific. The broader pattern lives in the related training topic.

Here is a small .mdc rule stub I would add before trying Local Motion on a real repository:

---
description: Safety boundary for local model agent work in this repo
alwaysApply: true
---

When using a local model:
- Read before editing.
- Do not modify migrations, lockfiles, secrets, auth code, or CI config without explicit approval.
- Prefer small patches under 200 changed lines.
- Run the nearest focused test before suggesting completion.
- Summarize files changed, tests run, and any uncertainty.

This is not fancy. That is the point. The trap is writing a philosophical rule when the agent needs a short operating boundary at edit time.

If you want a nearby example of agent boundaries from a different angle, compare this with Kastra Enforces Policies for Cursor Agents. Local Motion is about local runtime setup; policy tools are about permission and enforcement.

Try it safely before a serious edit

The safest first Local Motion run is a read-heavy task in a disposable branch. Use Cursor agent mode the way you normally would, choose the Local Motion model from the model picker, and ask for a bounded change that you can review in minutes.

I would not begin with cursor background agents or the cursor agent cli unless you already understand the model’s speed, context behavior, and memory cost on your Mac. Start where you can watch the edits happen.

Use this decision table before you run it locally:

The one gotcha to watch is memory, not installation. Local Motion tries to size the model budget against Apple Silicon limits, but your laptop still has a real ceiling. If the machine starts swapping or the editor gets sluggish, unload the model and come back with a smaller one.

A nice first command workflow looks like this:

git checkout -b try-local-motion
# start Local Motion from the editor extension
# choose the Local Motion model in Cursor
# ask for a read-only explanation first
git diff --stat
npm test -- --runInBand path/to/nearby.test.ts

Keep the first prompt plain: Read src/cache/sessionStore.ts and explain the smallest safe fix for the failing expiry test. Do not edit yet. If the explanation is solid, ask for the patch. If it wanders, stop there.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.

Practical starter checklist

- [ ] Name the Cursor artifact first: a .mdc rule stub, an AGENTS.md boundary, a custom subagent note, or a Cursor review checklist.
- [ ] Write the review checklist before generation starts: scope, owner, tests, rollback.
- [ ] Keep the first step small enough that a reviewer can inspect the receipt without replaying the whole chat.

Common questions

• What should teams know about cursor agent?

  Start by writing down one visible team rule for Cursor, not a loose preference. That is the practical core of cursor agent. That usually means a short repository convention, a review checklist, and one owner who can reject agent output when the evidence is missing.

• Which Cursor artifact should teams standardize first?

  Standardize the smallest artifact that reviewers already touch: a .mdc rule, AGENTS.md note, or review checklist. The point is not documentation volume; it is a shared place where scope, allowed tools, expected tests, and rollback notes are visible before generated code reaches review.

• How do teams know the convention is working?

  The convention is working when reviewers can approve or reject agent output from the artifact and evidence alone. Track whether pull requests name the rule used, include the promised checks, and avoid replaying long sessions just to understand what changed.

Best ways to use this research

• Best for: Cursor teams deciding which rule, subagent, skill, or MCP boundary to standardize next around “local-motion Runs Cursor Agents Locally.”
• Best first artifact: turn the named fix into a .mdc rule, AGENTS.md note, subagent receipt, or review checklist before the next automated run.
• Best comparison angle: compare the workflow against the current Cursor review path, connector scope, and team rule file; keep the path that leaves the shortest auditable trail.

Further reading

• local-motion — source
• Cursor — Agent
• Cursor — Rules
• Cursor docs: docs skills

Where to go next

Take this into the related training topic and test whether a new reviewer can defend the merge without replaying the chat.