remotehands

Your agent's hands on someone else's keyboard.

Codex doesn't submit jobs to Claude Code. Codex uses Claude Code — typing into a live session, watching it work, cutting in mid-task when it drifts, and carrying on. Exactly what a person does, except the person is an agent.

   you  ──▶  Codex  ──MCP──▶  remotehands daemon  ──▶  live Claude Code session
                 ▲                                             │
                 └────────── everything it says and does ───────┘

You watch Codex. Codex watches Claude.

Why this is different

Every other Codex↔Claude bridge does task delegation: send a task, wait, collect a result. Each turn is a fresh process; the supervisor is a dispatcher standing outside the room.

remotehands keeps one Claude process alive with its stdin held open. That single fact changes what's possible:

Steering work in flight

This is the whole point. Codex sends a correction while Claude is working — nothing is interrupted, nothing restarts:

you › Create red/green/blue/gold.txt, each containing COLD.
  · Write red.txt
you › Change of plan — files not yet written must contain WARM.   [queued mid-task]
  · Read red.txt
claude: Got it — red.txt stays COLD (already written), the remaining three will be WARM.
  · Write green.txt

Result: red.txt: COLD, the rest WARM. Claude finished its current step, took the new instruction on board, and kept going — no lost context, no restart.

Related MCP server: claude-code-mcp

Install

npm install -g remotehands
remotehands init-codex

Needs the Claude Code CLI on your PATH and logged in, plus the Codex CLI.

The tools Codex gets

send and read are the loop. Everything else is occasional.

The daemon

Sessions live in a background daemon, not inside the MCP server — because Codex kills its MCP subprocess on exit, and a session that dies with your terminal isn't a session you can come back to.

So: quit Codex, reopen it, and Claude is still there — still mid-task, queue intact, full context. Verified by killing the MCP server mid-task and attaching a new one; the queued correction was still picked up and applied.

The daemon starts automatically on first use.

remotehands status    # is it running?
remotehands stop      # stop it and all sessions

If the daemon does die, nothing is lost permanently — session ids are persisted, and the next send resumes the same conversation.

Teaching Codex to drive

Put this in ~/.codex/AGENTS.md:

## Driving Claude Code

You are the user of a live Claude Code session, not a dispatcher. You plan,
type, watch, correct, and review. You do not write implementation code
yourself.

Loop:
1. Plan the change and state your acceptance criteria.
2. send({ cwd, message }) — brief it like a capable engineer.
3. read({ cwd, since }) repeatedly while it works. Narrate what you see to me.
4. The moment it looks wrong, send() a correction. Do NOT wait for the turn to
   end — the message queues and Claude picks it up between steps.
5. When idle, diff({ cwd }) and review against your criteria.
6. Correct with another short send(), or report the finished work to me.

The session remembers everything. Keep messages short and conversational —
never restate earlier context. Keep one unanswered message in flight at a time.

CLI

The same engine by hand.

remotehands send "add retry with backoff to the fetcher"   # send, then watch
remotehands send "actually use the existing helper"        # works mid-task too
remotehands watch                                          # follow the live session
remotehands read --since 42                                # replay from a cursor
remotehands session                                        # status
remotehands diff --stat                                    # review
remotehands end                                            # close the session

Flags: --cwd <dir>, --model <name>, --fresh, --since <n>, --stat, --no-follow.

You can always attach to the exact session Codex is driving:

claude --resume $(remotehands session | awk '/^session/{print $2}')

Autonomy

Claude runs with --dangerously-skip-permissions in your real working copy — it writes, runs tests, installs things, without prompting. Headless sessions have nobody to answer a permission dialog, and the point is hands-off delegation.

Your guardrails are Codex watching in real time, the ability to correct mid-task, and git. Work on a branch.

Known limits

• The queue is in-memory. If the Claude process dies, queued messages are gone silently. Keep one unanswered message in flight — the daemon reports queue depth as best-effort, not a guarantee. See anthropics/claude-code#78338.

• No mid-turn interrupt. send always queues and never cuts Claude off (deliberate). To stop something badly wrong, end the session — the conversation resumes on the next send.

• One session per directory. Two sessions in one working copy would fight over the same files.

Configuration

How it works

1. send asks the daemon for the session bound to that directory, starting one if needed — claude -p --input-format stream-json --output-format stream-json --verbose --dangerously-skip-permissions, stdin held open.

2. Your message is written to that stdin as a JSON user message. Claude takes it whenever it reaches a step boundary.

3. Claude's stream-json output is parsed into numbered events (text, thinking, tool calls, failures, results) kept in memory and appended to ~/.remotehands/logs/<session>.jsonl.

4. read returns events after your cursor, so Codex polls cheaply and only ever sees what's new.

License

MIT