remote-ralph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 georg.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# remote-ralph
+
+Autonomous AI coding workflow with human-in-the-loop via GitHub PRs:
+
+remote-ralph takes your features → implements → opens PRs → responds to reviews → repeats. 24/7.
+
+You review & merge - from anywhere 🏝️
+
+> **Want to see remote-ralph in action?** [Check out the pull requests](https://github.com/georg-unterholzner/remote-ralph/pulls?q=is%3Apr+is%3Aclosed+author%3Aremote-ralph) - remote-ralph builds itself.
+
+## Prerequisites
+
+- **Node.js 22+**
+- **AI coding agent** (e.g. Claude Code, Codex CLI, OpenCode)
+- **Separate GitHub account** for the agent (so PRs come from a distinct user)
+- **[gh CLI](https://cli.github.com/)** authenticated as the agent's GitHub account
+
+## Usage
+
+### Minimal
+
+> **Caution:** in this case, the agent has access to your filesystem & network. You should run it in a sandbox (see below).
+
+```bash
+npx remote-ralph \
+  --requirements-path ./requirements.json \
+  --command "claude -p {prompt} --dangerously-skip-permissions"
+```
+
+### Sandboxed (recommended)
+
+Requires [Docker sandboxes](https://docs.docker.com/ai/sandboxes/). If not available (i.e. on Linux), create your own custom container for sandboxing.
+
+```bash
+npx remote-ralph \
+  --requirements-path ./requirements.json \
+  --command "docker sandbox run claude -p --max-turns 10 {prompt} --dangerously-skip-permissions"
+```
+
+### Resume after crash/reboot
+
+Re-run the same command. The agent will resume automatically where it left off.
+
+## CLI Options
+
+| Option | Required | Default | Description |
+|---|---|---|---|
+| `--requirements-path` | Yes | — | Path to requirements JSON file |
+| `--command` | Yes | — | Agent command template (must contain `{prompt}`) |
+| `--config-path` | No | `.remote-ralph/config.json` | Path to config file |
+| `--state-path` | No | `.remote-ralph/state.json` | Where to persist current PR link |
+| `--log-level` | No | `info` | `error`, `warn`, `info`, or `debug` |
+
+CLI args override config file values.
+
+## Config File
+
+Optional JSON config at `.remote-ralph/config.json` (or path specified by `--config-path`). Missing file = all defaults.
+
+```json
+{
+  "pollIntervalMinutes": 5,
+  "statePath": "./.remote-ralph/state.json",
+  "logLevel": "info",
+  "pretext": "Always use TypeScript",
+  "allowlist": ["alice", "bob"],
+  "requireMention": false,
+  "mergeConflictResolution": "withThreads"
+}
+```
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `pollIntervalMinutes` | number | `5` | Minutes between poll ticks (must be positive) |
+| `statePath` | string | `./.remote-ralph/state.json` | Where to persist current PR link |
+| `logLevel` | `error` \| `warn` \| `info` \| `debug` | `info` | Log verbosity |
+| `pretext` | string | `""` | Prepended to implement & reaction prompts |
+| `allowlist` | string[] | `[]` | Allowed reviewer GitHub usernames. Limits who can trigger agent reactions (empty = allow all). Prevents unnecessary token usage and somewhat mitigates prompt injection from non-allowlisted users (note: agent still has full `gh` CLI access and may see all comments on subsequent passes). |
+| `requireMention` | boolean | `false` | When `true`, a thread is only actionable if the latest comment @mentions the bot. Useful to avoid reacting to every comment |
+| `mergeConflictResolution` | `"never"` \| `"withThreads"` \| `"always"` | `"withThreads"` | Controls auto-resolution of merge conflicts. `never`: no automatic merge conflict resolution. `withThreads`: attempt conflict resolution when actionable threads exist. `always`: invoke agent for conflict resolution even without threads |
+
+All fields are optional. Validated with zod — invalid JSON or schema violations exit with error.
+
+## Caveats
+
+- If you use different git users for orchestrator and agent, ensure they use the same auth method (both SSH or both HTTPS). They share `.git/config`, so mismatched methods can cause the agent to rewrite the remote URL.
+
+## State File
+
+The state file stores only the **current PR link**. This enables crash recovery: on restart, the orchestrator detects the existing PR and resumes polling instead of creating a duplicate.
+
+When a PR is merged or closed, the state is cleared and the next implementation cycle begins.
+
+## Requirements File
+
+A JSON array of items. The only field the loop cares about is `passes: boolean`. The agent picks the first item where `passes` is `false`, implements it, flips it to `true`, and opens a PR.
+
+```json
+[
+  { "id": "F-001", "title": "My feature", "passes": false },
+  { "id": "F-002", "title": "Another feature", "passes": false }
+]
+```
+
+Structure beyond `passes` is up to you; add whatever context helps your agent.
+
+## Roadmap
+
+### 0.2.0
+
+- **Reply prefix:** configurable prefix for bot replies, used for bot comment detection
+- **Command routing:** route review threads to different agents based on tokens (e.g. `#Opus`, `#Sonnet`)
+
+### 1.0.0
+
+- **Concurrency:** multiple agents working on different features simultaneously, shipping in parallel
+- **GitHub Issues integration:** describe what you want in an issue, remote-ralph clarifies the requirements with you, then picks it up and starts building