# 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](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

```bash
# 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](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

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