rw-runner 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Davontae Jackson
+
+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,133 @@
+# rw-runner
+
+Autonomous task runner powered by Claude. Define tasks, set completion requirements, and let Claude work through them autonomously.
+
+## Install
+
+```bash
+# Using bun (recommended)
+bun install -g rw-runner
+
+# Using npm
+npm install -g rw-runner
+```
+
+**Requirements:** [Claude Code CLI](https://claude.ai/code) must be installed and authenticated.
+
+## Quick Start
+
+```bash
+# Initialize rw in your project
+rw init
+
+# Add a task
+rw add task
+
+# Add context files Claude can reference
+rw add resource
+
+# Start the autonomous loop
+rw run
+```
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  RALPH LOOP                                                      │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  1. Claude picks the most important pending task                │
+│  2. Claude works on it autonomously                             │
+│  3. Claude outputs "DONE: task name"                            │
+│  4. Ralph runs requirement checks (tests, commands)             │
+│     ├── PASS → mark complete, next task                         │
+│     └── FAIL → retry with error context (max 3)                 │
+│  5. Repeat until all tasks complete                             │
+│                                                                  │
+│  HOTKEYS:                                                        │
+│    [t] - takeover (jump into Claude session)                    │
+│    [q] - quit                                                    │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `rw init` | Initialize rw in current directory |
+| `rw add task` | Add a task interactively |
+| `rw add resource` | Add a context file |
+| `rw validate` | Check spec.md syntax |
+| `rw status` | Show task completion status |
+| `rw run` | Start the autonomous loop |
+
+## spec.md Format
+
+```markdown
+# Spec
+
+## Tasks
+- [ ] Implement user authentication
+  - [run]: `npm test`
+    [expect]: PASS
+    [expect-not]: FAIL
+
+- [ ] Add rate limiting
+  - [run]: `go test ./...`
+    [expect-exit]: 0
+  - [run]: `curl localhost:3000/health`
+    [eval]: "Returns 200 OK"
+
+## Resources
+[file]: `docs/architecture.md`
+High-level system design. Read this first.
+
+[file]: `docs/api.md`
+API endpoint documentation.
+```
+
+### Task States
+
+- `[ ]` - pending
+- `[x]` - completed
+- `[!]` - failed (skipped after 3 retries)
+
+### Requirement Checks
+
+| Check | Description |
+|-------|-------------|
+| `[expect]` | Output must contain this string |
+| `[expect-not]` | Output must NOT contain this string |
+| `[expect-exit]` | Exit code must match |
+| `[eval]` | LLM evaluates output against criteria |
+
+## Configuration
+
+Global config at `~/.rw/config.yaml`:
+
+```yaml
+# Model for LLM evaluations
+model: claude-sonnet
+
+# Max retries before marking task as failed
+max_retries: 3
+
+# Delay between loop iterations (seconds)
+loop_delay: 2
+```
+
+## Takeover Mode
+
+Press `t` during `rw run` to jump into the active Claude session. This lets you:
+
+- Provide additional context
+- Guide Claude through tricky parts
+- Fix issues manually
+
+When you exit (Ctrl+D or `/exit`), Ralph asks if you want to run requirements, then continues the loop.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "rw-runner",
+  "version": "0.1.0",
+  "description": "Autonomous task runner powered by Claude",
+  "author": "Davontae Jackson",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/theworksofvon/rw-runner"
+  },
+  "homepage": "https://github.com/theworksofvon/rw-runner#readme",
+  "bugs": {
+    "url": "https://github.com/theworksofvon/rw-runner/issues"
+  },
+  "keywords": [
+    "cli",
+    "claude",
+    "ai",
+    "automation",
+    "tasks",
+    "autonomous",
+    "agent",
+    "bun"
+  ],
+  "files": [
+    "src"
+  ],
+  "bin": {
+    "rw": "./src/index.ts"
+  },
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun --watch src/index.ts",
+    "build": "bun build src/index.ts --compile --outfile rw",
+    "prepublishOnly": "echo 'Ready to publish!'"
+  },
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.2.0",
+    "commander": "^14.0.2",
+    "ora": "^9.0.0",
+    "picocolors": "^1.1.1"
+  }
+}

package/src/commands/add.ts

@@ -0,0 +1,138 @@
+import { input, confirm, select } from "@inquirer/prompts";
+import { ui } from "../lib/ui";
+import { isInitialized, addTask, addResource } from "../lib/spec";
+import type { Task, Resource, CheckType } from "../types";
+
+export async function addTaskCommand(): Promise<void> {
+  ui.logo();
+
+  if (!isInitialized()) {
+    ui.error("rw not initialized. Run `rw init` first.");
+    process.exit(1);
+  }
+
+  ui.header("Add task");
+
+  // Get task description
+  const description = await input({
+    message: "Task description:",
+    validate: (v) => (v.trim() ? true : "Description required"),
+  });
+
+  // Build requirements
+  const requirements: Task["requirements"] = [];
+
+  const addRequirements = await confirm({
+    message: "Add requirements (commands to verify completion)?",
+    default: true,
+  });
+
+  if (addRequirements) {
+    let addMore = true;
+
+    while (addMore) {
+      ui.newline();
+      ui.info("Adding requirement...");
+
+      const command = await input({
+        message: "Command to run:",
+        validate: (v) => (v.trim() ? true : "Command required"),
+      });
+
+      const checks: Task["requirements"][0]["checks"] = [];
+      let addMoreChecks = true;
+
+      while (addMoreChecks) {
+        const checkType = await select<CheckType>({
+          message: "Check type:",
+          choices: [
+            {
+              name: "expect - output must contain string",
+              value: "expect",
+            },
+            {
+              name: "expect-not - output must NOT contain string",
+              value: "expect-not",
+            },
+            {
+              name: "expect-exit - exit code must match",
+              value: "expect-exit",
+            },
+            {
+              name: "eval - LLM evaluates output against criteria",
+              value: "eval",
+            },
+          ],
+        });
+
+        let valuePrompt = "Value:";
+        if (checkType === "expect") valuePrompt = "String to find in output:";
+        if (checkType === "expect-not")
+          valuePrompt = "String that should NOT be in output:";
+        if (checkType === "expect-exit") valuePrompt = "Expected exit code:";
+        if (checkType === "eval") valuePrompt = "Evaluation criteria:";
+
+        const value = await input({
+          message: valuePrompt,
+          validate: (v) => (v.trim() ? true : "Value required"),
+        });
+
+        checks.push({ type: checkType, value });
+
+        addMoreChecks = await confirm({
+          message: "Add another check for this command?",
+          default: false,
+        });
+      }
+
+      requirements.push({ command, checks });
+
+      addMore = await confirm({
+        message: "Add another requirement command?",
+        default: false,
+      });
+    }
+  }
+
+  const task: Task = {
+    description,
+    status: "pending",
+    requirements,
+  };
+
+  addTask(task);
+
+  ui.newline();
+  ui.success(`Added task: ${description}`);
+
+  if (requirements.length > 0) {
+    ui.info(`  ${requirements.length} requirement(s) configured`);
+  }
+}
+
+export async function addResourceCommand(): Promise<void> {
+  ui.logo();
+
+  if (!isInitialized()) {
+    ui.error("rw not initialized. Run `rw init` first.");
+    process.exit(1);
+  }
+
+  ui.header("Add resource");
+
+  const path = await input({
+    message: "File path (e.g., docs/architecture.md):",
+    validate: (v) => (v.trim() ? true : "Path required"),
+  });
+
+  const description = await input({
+    message: "Description (what is this file for?):",
+    validate: (v) => (v.trim() ? true : "Description required"),
+  });
+
+  const resource: Resource = { path, description };
+  addResource(resource);
+
+  ui.newline();
+  ui.success(`Added resource: ${path}`);
+}

package/src/commands/init.ts

@@ -0,0 +1,46 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { ui } from "../lib/ui";
+import { getSpecTemplate } from "../lib/spec";
+import { ensureConfigDir } from "../lib/config";
+
+const RALPH_DIR = ".rw";
+const SPEC_PATH = `${RALPH_DIR}/spec.md`;
+const CHANGELOG_PATH = `${RALPH_DIR}/changelog.md`;
+
+export async function initCommand(): Promise<void> {
+  ui.logo();
+
+  // Check if already initialized
+  if (existsSync(RALPH_DIR)) {
+    ui.warn("rw is already initialized in this directory");
+    ui.info(`Edit ${SPEC_PATH} to add tasks and resources`);
+    return;
+  }
+
+  ui.header("Initializing rw");
+
+  // Create .rw directory
+  mkdirSync(RALPH_DIR, { recursive: true });
+  ui.success(`Created ${RALPH_DIR}/`);
+
+  // Create spec.md
+  writeFileSync(SPEC_PATH, getSpecTemplate());
+  ui.success(`Created ${SPEC_PATH}`);
+
+  // Create empty changelog
+  writeFileSync(CHANGELOG_PATH, "# Changelog\n\n");
+  ui.success(`Created ${CHANGELOG_PATH}`);
+
+  // Ensure global config dir exists
+  ensureConfigDir();
+
+  ui.newline();
+  ui.box(
+    `Ready! Next steps:
+
+  rw add task       Add your first task
+  rw add resource   Add context files
+  rw run            Start the loop`,
+    "green"
+  );
+}

package/src/commands/run.ts

@@ -0,0 +1,38 @@
+import { ui } from "../lib/ui";
+import { isInitialized, validateSpec, getPendingTasks } from "../lib/spec";
+import { readConfig } from "../lib/config";
+import { startLoop } from "../lib/loop";
+
+export async function runCommand(): Promise<void> {
+  if (!isInitialized()) {
+    ui.error("rw not initialized. Run `rw init` first.");
+    process.exit(1);
+  }
+
+  // Validate spec first
+  const { valid, errors } = validateSpec();
+  if (!valid) {
+    ui.error("spec.md has errors:");
+    for (const error of errors) {
+      ui.error(`  ${error}`);
+    }
+    ui.newline();
+    ui.info("Fix errors and try again, or run `rw validate` for details");
+    process.exit(1);
+  }
+
+  // Check for pending tasks
+  const pending = getPendingTasks();
+  if (pending.length === 0) {
+    ui.logo();
+    ui.success("No pending tasks!");
+    ui.info("Add tasks with: rw add task");
+    return;
+  }
+
+  // Load config
+  const config = readConfig();
+
+  // Start the loop
+  await startLoop(config);
+}

package/src/commands/status.ts

@@ -0,0 +1,77 @@
+import { ui } from "../lib/ui";
+import { isInitialized, readSpec } from "../lib/spec";
+import pc from "picocolors";
+
+export async function statusCommand(): Promise<void> {
+  ui.logo();
+
+  if (!isInitialized()) {
+    ui.error("rw not initialized. Run `rw init` first.");
+    process.exit(1);
+  }
+
+  const spec = readSpec();
+
+  ui.header("Tasks");
+  ui.newline();
+
+  if (spec.tasks.length === 0) {
+    ui.dim("No tasks yet. Add one with: rw add task");
+  } else {
+    for (const task of spec.tasks) {
+      const icon = ui.taskIcon(task.status);
+      const desc =
+        task.status === "completed"
+          ? pc.dim(pc.strikethrough(task.description))
+          : task.status === "failed"
+            ? pc.red(task.description)
+            : task.description;
+
+      console.log(`  ${icon} ${desc}`);
+
+      // Show requirements count if any
+      if (task.requirements.length > 0) {
+        ui.dim(`    ${task.requirements.length} requirement(s)`);
+      }
+    }
+
+    // Summary
+    const pending = spec.tasks.filter((t) => t.status === "pending").length;
+    const completed = spec.tasks.filter((t) => t.status === "completed").length;
+    const failed = spec.tasks.filter((t) => t.status === "failed").length;
+    const total = spec.tasks.length;
+
+    ui.newline();
+    ui.divider();
+    ui.newline();
+
+    // Progress bar
+    if (total > 0) {
+      ui.progress(completed, total, `${completed}/${total} complete`);
+    }
+
+    ui.newline();
+    const parts: string[] = [];
+    if (completed > 0) parts.push(pc.green(`${completed} completed`));
+    if (pending > 0) parts.push(pc.yellow(`${pending} pending`));
+    if (failed > 0) parts.push(pc.red(`${failed} failed`));
+
+    ui.info(parts.join(", "));
+  }
+
+  // Resources
+  ui.newline();
+  ui.header("Resources");
+  ui.newline();
+
+  if (spec.resources.length === 0) {
+    ui.dim("No resources yet. Add one with: rw add resource");
+  } else {
+    for (const resource of spec.resources) {
+      console.log(`  ${pc.cyan("•")} ${pc.bold(resource.path)}`);
+      ui.dim(`    ${resource.description}`);
+    }
+  }
+
+  ui.newline();
+}

package/src/commands/validate.ts

@@ -0,0 +1,44 @@
+import { ui } from "../lib/ui";
+import { isInitialized, validateSpec, readSpec } from "../lib/spec";
+
+export async function validateCommand(): Promise<void> {
+  ui.logo();
+
+  if (!isInitialized()) {
+    ui.error("rw not initialized. Run `rw init` first.");
+    process.exit(1);
+  }
+
+  ui.header("Validating spec.md");
+
+  const { valid, errors } = validateSpec();
+
+  if (valid) {
+    const spec = readSpec();
+    ui.newline();
+    ui.success("spec.md is valid");
+    ui.newline();
+    ui.info(`${spec.tasks.length} task(s) found`);
+    ui.info(`${spec.resources.length} resource(s) found`);
+
+    // Show task breakdown
+    const pending = spec.tasks.filter((t) => t.status === "pending").length;
+    const completed = spec.tasks.filter((t) => t.status === "completed").length;
+    const failed = spec.tasks.filter((t) => t.status === "failed").length;
+
+    if (spec.tasks.length > 0) {
+      ui.newline();
+      ui.info(
+        `Status: ${ui.green(`${completed} completed`)}, ${pending} pending, ${ui.red(`${failed} failed`)}`
+      );
+    }
+  } else {
+    ui.newline();
+    ui.error("spec.md has errors:");
+    ui.newline();
+    for (const error of errors) {
+      ui.error(error);
+    }
+    process.exit(1);
+  }
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env bun
+import { Command } from "commander";
+import pc from "picocolors";
+import { initCommand } from "./commands/init";
+import { addTaskCommand, addResourceCommand } from "./commands/add";
+import { validateCommand } from "./commands/validate";
+import { statusCommand } from "./commands/status";
+import { runCommand } from "./commands/run";
+
+const program = new Command();
+
+program
+  .name("rw")
+  .description(pc.dim("Autonomous task runner powered by Claude"))
+  .version("0.1.0");
+
+// init command
+program
+  .command("init")
+  .description("Initialize rw in current directory")
+  .action(initCommand);
+
+// add command with subcommands
+const add = program.command("add").description("Add tasks or resources");
+
+add
+  .command("task")
+  .description("Add a new task to spec.md")
+  .action(addTaskCommand);
+
+add
+  .command("resource")
+  .description("Add a new resource to spec.md")
+  .action(addResourceCommand);
+
+// validate command
+program
+  .command("validate")
+  .description("Validate spec.md syntax")
+  .action(validateCommand);
+
+// status command
+program
+  .command("status")
+  .description("Show task completion status")
+  .action(statusCommand);
+
+// run command
+program
+  .command("run")
+  .description("Start the autonomous task loop")
+  .action(runCommand);
+
+// Parse arguments
+program.parse();