From 21461077f6f88dba0fabea5d07b0f78977a07cff Mon Sep 17 00:00:00 2001
From: mikael-lovqvists-claude-agent <mikaels.claude.agent@efforting.tech>
Date: Wed, 18 Mar 2026 22:31:23 +0000
Subject: [PATCH] Add README

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dfa7c1d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,63 @@
+# 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
+```