movild

Movild local runner. Pair your Mac with movild.dev and run coding agents (Claude, Codex, Gemini) on your machine instead of the cloud.

Install

npm i -g movild

Requires Node 20+. macOS uses the system Keychain to store your session token. Linux falls back to a 0600 dot-file at ~/.movild/session.

Quick start

movild

First run opens your browser, asks you to approve the device on movild.dev, and then starts listening for tasks. Subsequent runs reuse the saved session and go straight to listening.

┌──────────────────────────────────────┐
│ movild v0.1.0                        │
│ ship code from anywhere · cli        │
└──────────────────────────────────────┘

┌─ pair this device ─────────────┐
│ verification code              │
│ ABCD-1234                      │
│                                │
│ opening:                       │
│ https://movild.dev/pair?code=… │
└────────────────────────────────┘

· opening browser…
⠙ waiting for approval…
✓ device paired
✓ signed in as @you
✓ agents available: anthropic, openai
· listening for tasks…

Agents

Movild drives whichever of these you have installed and authenticated:

• claude — Claude Code
• codex — OpenAI Codex CLI
• gemini — Gemini CLI

Run movild doctor to verify what the CLI can see.

You also need gh installed if you want the agent to open pull requests for you (it shells out to gh pr create).

Commands

| Command | What it does | | ----------------- | -------------------------------------------------- | | movild | Pair if needed, then listen for tasks. Default. | | movild pair | Force a fresh pairing flow. | | movild daemon … | Run in the background at login (macOS). See below. | | movild logout | Clear the saved session token. | | movild doctor | Show config + agent + session checks. | | movild version | Print the CLI version. |

Run in the background (macOS)

Don't want to keep a terminal open? Install movild as a background runner. It starts at login, restarts itself if it crashes, and keeps processing tasks — so you never have to think about it.

movild daemon install     # pair (once) + register a launchd LaunchAgent
movild daemon status      # is it running?
movild daemon logs        # tail the daemon log
movild daemon uninstall   # stop it and remove it

Notes:

• macOS only, built on launchd — nothing extra to download, the CLI writes the launch agent itself.
• Per-user, no sudo. It runs inside your own login session (a LaunchAgent, not a system LaunchDaemon) so it can reach your Keychain and your locally-authenticated claude / codex / gemini.
• Only runs while you're logged in; stops at logout.
• macOS lists it under Settings → General → Login Items → Allow in the Background, so you can always see and toggle it.
• It's an unattended runner: it will pick up and execute tasks without you watching. Uninstall any time with movild daemon uninstall.

Environment variables

| Variable | Purpose | | ---------------------- | ------------------------------------------------------------------ | | MOVILD_API_URL | Override the API endpoint. Defaults to https://api.movild.app. | | MOVILD_RUNNER_NAME | Override the runner name. Defaults to your machine's hostname. | | MOVILD_CLAUDE_COMMAND | Override the Claude invocation. Defaults to the bundled command. | | MOVILD_CODEX_COMMAND | Override the Codex invocation. | | MOVILD_GEMINI_COMMAND | Override the Gemini invocation. |

How it works

1. CLI calls POST /cli/pair/init to get a short-lived code.
2. CLI opens your browser at https://movild.dev/pair?code=<code>.
3. You approve the device — the web mints a long-lived session JWT and stores it on the pairing row.
4. CLI polls GET /cli/pair/<id> until approved, redeems the token, and stores it in the macOS Keychain (or a 0600 file on other OSes).
5. CLI starts the worker loop: registers as a runner, polls POST /local-runner/tasks/next, and executes claimed tasks inside a persistent per-task workspace at ~/.movild/runs/<task-id>.

Each task is a persistent chat thread. The agent reuses the workspace between turns; it only pushes a branch or opens a PR when you explicitly ask for it.

License

MIT