claude-remote/README.md

claude-remote

Send text to a Claude Code instance running inside a Docker container from the host machine.

Work in progress — core paste/focus machinery works, but reliable window detection is still being solved. See plan.md for details.

What it does

Claude Code runs inside a Docker container attached to a Konsole terminal window. claude-remote lets you programmatically send text to that terminal from the host — as if you had typed it — by locating the correct Konsole window and using xdotool to focus it and paste input via the clipboard.

This is the foundation for automation workflows where other processes (e.g. a mail handler) need to trigger Claude with a message without manual interaction.

Usage

# Paste text and submit (press Enter)
claude-remote "check email"

# Paste text without submitting
claude-remote --no-submit "some text"

# Focus the Claude window without pasting anything
claude-remote --focus-only

# Print the detected window ID and exit
claude-remote --find-window

# Read from stdin
echo "check email" | claude-remote

# Target a specific window by ID
claude-remote --window-id 0x1800021 "hello"

# List all running processes with exe paths (for debugging)
claude-remote --list-procs

How it works

1. Scans /proc for a docker-compose process whose cmdline matches the Claude invocation
2. Walks the process tree upward to find the Konsole ancestor
3. Maps the Konsole PID to a window ID via _NET_WM_PID / xprop
4. Copies text to clipboard and sends shift+Insert via xdotool

Falls back to xdotool search --name claude-docker if the process-tree approach fails.

Known limitations

• Window detection is unreliable when multiple Konsole windows exist, because all windows in a single Konsole process share the same _NET_WM_PID. The planned fix is to pass WINDOWID into the container at launch so it can be read back from a bind-mounted file. See plan.md.
• Focus stealing — every paste brings the Konsole window to the foreground. A future approach using direct PTY writes (/dev/pts/X) would eliminate this entirely.

Requirements

• xdotool
• xclip
• xprop
• Node.js with ES module support

Install

npm install -g git+https://gitea.efforting.tech/mikael-lovqvists-claude-agent/claude-remote