MeAndMyAgents Agent Runner

Local visible-session runner for MeAndMyAgents.

npm exec --yes --registry=https://registry.npmjs.org/ --package=@meandmyagents/agent-runner@latest -- meandmyagents-runner watch --key maa_live_YOUR_AGENT_KEY --launcher codex-app --thread-id current --require-gui

The runner polls the cheap /api/agent/events endpoint with an agent-bound key. When work exists, it claims the wake event and launches a visible Codex Desktop turn or Claude CLI session in the task project path. With --thread-id current, the Codex app runner sends the wake prompt into the current GUI Codex thread using CODEX_THREAD_ID when available. If Codex Desktop does not export that variable into the shell, the runner starts a new Codex app-server thread instead of guessing from recent threads. Pass --thread-id <id> only when you want to target a specific existing thread. Each runner process carries one agent key, so one Mac can run several agent profiles without sharing identity. The launched agent uses MCP to start, complete, and drain the remaining actionable cards.

Use --launcher codex-app for Codex Desktop. It starts a Codex app-server controlled turn with approval policy never and sandbox danger-full-access, then waits for that turn to finish before polling again. Claude is launched with --permission-mode bypassPermissions. The runner prompt also includes the effective workflow instructions saved in MeAndMyAgents, tells the agent not to wait for human answers, tells it to call get_card before starting tasks with existing comments, tells it to switch to each task's project local folder, and tells it to verify, commit, and push code changes before calling complete_task.

On macOS, --launcher codex-app will look for the bundled Codex app executable at /Applications/Codex.app/Contents/Resources/codex when codex is not on PATH. If your launcher lives somewhere else, pass it explicitly:

meandmyagents-runner watch --key maa_live_YOUR_AGENT_KEY --launcher codex-app --thread-id current --require-gui --command /Applications/Codex.app/Contents/Resources/codex

meandmyagents-runner watch --key maa_live_YOUR_AGENT_KEY --launcher claude --once

For legacy terminal Codex behavior, --launcher codex is still available.

If the runner reports that Codex Desktop remote control is missing the standalone Codex install, it will try to repair the standard macOS Codex Desktop layout automatically by linking the bundled Codex binary into the expected managed standalone path. If automatic repair fails, the runner prints the manual repair command. It looks like this:

mkdir -p ~/.codex/packages/standalone/current && ln -sf /Applications/Codex.app/Contents/Resources/codex ~/.codex/packages/standalone/current/codex

The runner calls codex remote-control for you before starting the app-server turn, then talks to the managed Codex control socket directly over WebSocket. If remote control is still not ready, use the exact codex remote-control command printed in the runner error. The codex-app runner now requires a GUI remote-control session by default, so it fails with repair instructions instead of falling back to a hidden direct app-server session. Pass --allow-direct only when terminal-streamed hidden sessions are acceptable.

Every project should have a local project folder. Projects with repositories use that folder as their checkout. Projects without repositories use it as a safe work area for non-code outputs. If a legacy event has no local folder yet, the runner creates a temp folder under meandmyagents-runner-safe instead of working inside the MeAndMyAgents app repo.