rlph-cli 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# Ralph
+
+Loop coding agent CLI - run AI coding agents headlessly in a loop.
+
+Inspired by [Geoff Huntley's ralph technique](https://ghuntley.com/ralph/) - putting a coding agent in a while loop and letting it work autonomously.
+
+```bash
+while :; do cat prompt.md | claude -p; done
+```
+
+Ralph wraps this pattern into a proper CLI with session logging, iteration limits, and automatic task completion detection.
+
+## Installation
+
+```bash
+# npm
+npm install -g rlph-cli
+
+# or run directly
+npx rlph-cli run -p "your task"
+```
+
+### From source
+
+```bash
+git clone https://github.com/rem4ik4ever/ralph.git
+cd ralph
+bun install
+bun run build
+bun link
+```
+
+## Usage
+
+```bash
+ralph run -p <prompt> [-a agent] [-i iterations]
+```
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-p, --prompt <files...>` | Prompt text or files to pass to agent | required |
+| `-a, --agent <agent>` | Agent type (currently: claude) | `claude` |
+| `-i, --iterations <n>` | Max loop iterations | `4` |
+
+### Examples
+
+**Simple task**
+```bash
+ralph run -p "fix the login bug" -i 3
+```
+
+**Using a prompt file**
+```bash
+ralph run -p prompt.md -i 10
+```
+
+**Multiple prompts/files**
+```bash
+ralph run -p task.md context.md "also add tests"
+```
+
+**Long running task**
+```bash
+ralph run -p "port this codebase from React to Vue" -i 50
+```
+
+## How it works
+
+1. Ralph reads your prompt (text or files)
+2. Appends completion instructions asking agent to output `<ralph>RALPH_COMPLETED</ralph>` when done
+3. Runs the agent in a loop up to N iterations
+4. Streams output in real-time
+5. Stops early if agent signals completion
+6. Logs each iteration to `~/.ralph/sessions/<session-id>/`
+
+## Session logs
+
+All sessions are logged to `~/.ralph/sessions/`:
+
+```
+~/.ralph/sessions/
+  └── <session-id>/
+      ├── meta.json    # session metadata
+      ├── 0.log        # iteration 0 output
+      ├── 1.log        # iteration 1 output
+      └── ...
+```
+
+## Supported agents
+
+- `claude` - Claude Code CLI (requires [claude](https://claude.ai/claude-code) installed)
+
+## Requirements
+
+- Node.js >= 18
+- Claude Code CLI installed and authenticated
+
+## License
+
+MIT

package/dist/agents/base.d.ts

@@ -0,0 +1,16 @@
+export interface AgentResult {
+    output: string;
+    exitCode: number;
+    duration: number;
+}
+export interface ExecuteOptions {
+    onOutput?: (chunk: string) => void;
+}
+export interface Agent {
+    name: string;
+    execute(prompt: string, cwd: string, options?: ExecuteOptions): Promise<AgentResult>;
+}
+export type AgentType = 'claude';
+export declare const SUPPORTED_AGENTS: AgentType[];
+export declare function isValidAgent(agent: string): agent is AgentType;
+//# sourceMappingURL=base.d.ts.map

package/dist/agents/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/agents/base.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACnC;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CACrF;AAED,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAA;AAEhC,eAAO,MAAM,gBAAgB,EAAE,SAAS,EAAe,CAAA;AAEvD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,SAAS,CAE9D"}

package/dist/agents/base.js

@@ -0,0 +1,5 @@
+export const SUPPORTED_AGENTS = ['claude'];
+export function isValidAgent(agent) {
+    return SUPPORTED_AGENTS.includes(agent);
+}
+//# sourceMappingURL=base.js.map

package/dist/agents/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/agents/base.ts"],"names":[],"mappings":"AAiBA,MAAM,CAAC,MAAM,gBAAgB,GAAgB,CAAC,QAAQ,CAAC,CAAA;AAEvD,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,gBAAgB,CAAC,QAAQ,CAAC,KAAkB,CAAC,CAAA;AACtD,CAAC"}

package/dist/agents/claude.d.ts

@@ -0,0 +1,3 @@
+import type { Agent } from './base.js';
+export declare const claude: Agent;
+//# sourceMappingURL=claude.d.ts.map

package/dist/agents/claude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAA+B,MAAM,WAAW,CAAA;AAmBnE,eAAO,MAAM,MAAM,EAAE,KAqEpB,CAAA"}

package/dist/agents/claude.js

@@ -0,0 +1,80 @@
+import { spawn } from 'node:child_process';
+function parseStreamJson(line) {
+    try {
+        const data = JSON.parse(line);
+        // Only parse assistant messages, skip result (already streamed)
+        if (data.type === 'assistant' && data.message?.content) {
+            for (const block of data.message.content) {
+                if (block.type === 'text') {
+                    return block.text;
+                }
+            }
+        }
+    }
+    catch {
+        // Not valid JSON, ignore
+    }
+    return null;
+}
+export const claude = {
+    name: 'claude',
+    async execute(prompt, cwd, options) {
+        const startTime = Date.now();
+        const onOutput = options?.onOutput;
+        return new Promise((resolve, reject) => {
+            const proc = spawn('claude', [
+                '-p',
+                '--dangerously-skip-permissions',
+                '--output-format', 'stream-json',
+                '--verbose',
+            ], {
+                cwd,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                shell: true,
+            });
+            let output = '';
+            let stderr = '';
+            let buffer = '';
+            proc.stdout.on('data', (data) => {
+                buffer += data.toString();
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || ''; // Keep incomplete line in buffer
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    const text = parseStreamJson(line);
+                    if (text) {
+                        output += text;
+                        onOutput?.(text);
+                    }
+                }
+            });
+            proc.stderr.on('data', (data) => {
+                const chunk = data.toString();
+                stderr += chunk;
+            });
+            proc.on('error', (err) => {
+                reject(new Error(`Failed to spawn claude: ${err.message}`));
+            });
+            proc.on('close', (code) => {
+                // Process any remaining buffer
+                if (buffer.trim()) {
+                    const text = parseStreamJson(buffer);
+                    if (text) {
+                        output += text;
+                        onOutput?.(text);
+                    }
+                }
+                const duration = Date.now() - startTime;
+                resolve({
+                    output: output + (stderr ? `\n[stderr]\n${stderr}` : ''),
+                    exitCode: code ?? 1,
+                    duration,
+                });
+            });
+            proc.stdin.write(prompt);
+            proc.stdin.end();
+        });
+    },
+};
+//# sourceMappingURL=claude.js.map

package/dist/agents/claude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"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"}

package/dist/agents/index.d.ts

@@ -0,0 +1,4 @@
+import type { Agent, AgentType } from './base.js';
+export declare function getAgent(type: AgentType): Agent;
+export * from './base.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAOjD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,CAE/C;AAED,cAAc,WAAW,CAAA"}

package/dist/agents/index.js

@@ -0,0 +1,9 @@
+import { claude } from './claude.js';
+const agents = {
+    claude,
+};
+export function getAgent(type) {
+    return agents[type];
+}
+export * from './base.js';
+//# sourceMappingURL=index.js.map

package/dist/agents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,MAAM,MAAM,GAA6B;IACvC,MAAM;CACP,CAAA;AAED,MAAM,UAAU,QAAQ,CAAC,IAAe;IACtC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAA;AACrB,CAAC;AAED,cAAc,WAAW,CAAA"}

package/dist/commands/run.d.ts

@@ -0,0 +1,7 @@
+export interface RunOptions {
+    prompt: string[];
+    agent: string;
+    iterations: string;
+}
+export declare function run(opts: RunOptions): Promise<void>;
+//# sourceMappingURL=run.d.ts.map

package/dist/commands/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/commands/run.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,wBAAsB,GAAG,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA4EzD"}

package/dist/commands/run.js

@@ -0,0 +1,73 @@
+import chalk from 'chalk';
+import { getAgent, isValidAgent } from '../agents/index.js';
+import { createSession, writeLog, getSessionDir } from '../session/index.js';
+import { buildPrompt, COMPLETION_MARKER } from '../utils/index.js';
+export async function run(opts) {
+    // Validate agent
+    if (!isValidAgent(opts.agent)) {
+        console.error(chalk.red(`Unknown agent: ${opts.agent}`));
+        console.error(`Supported agents: claude`);
+        process.exit(1);
+    }
+    // Validate iterations
+    const iterations = parseInt(opts.iterations, 10);
+    if (isNaN(iterations) || iterations <= 0) {
+        console.error(chalk.red(`Iterations must be a positive number, got: ${opts.iterations}`));
+        process.exit(1);
+    }
+    const agent = getAgent(opts.agent);
+    // Build prompt with completion instructions
+    let prompt;
+    try {
+        prompt = await buildPrompt(opts.prompt);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(chalk.red(`Failed to read prompt files: ${message}`));
+        process.exit(1);
+    }
+    // Create session
+    const sessionId = await createSession({
+        promptFiles: opts.prompt,
+        agent: opts.agent,
+        iterations,
+    });
+    console.log(chalk.blue(`Session: ${sessionId}`));
+    console.log(chalk.gray(`Agent: ${agent.name}`));
+    console.log(chalk.gray(`Iterations: ${iterations}`));
+    console.log();
+    // Run loop
+    let completed = false;
+    let actualIterations = 0;
+    for (let i = 0; i < iterations; i++) {
+        actualIterations++;
+        console.log(chalk.yellow(`[${i + 1}/${iterations}] Running ${agent.name}...`));
+        console.log();
+        const result = await agent.execute(prompt, process.cwd(), {
+            onOutput: (chunk) => process.stdout.write(chunk),
+        });
+        console.log();
+        await writeLog(sessionId, i, result);
+        if (result.exitCode !== 0) {
+            console.log(chalk.red(`  Exit code: ${result.exitCode}`));
+        }
+        else {
+            console.log(chalk.green(`  Done (${result.duration}ms)`));
+        }
+        // Check for completion marker
+        if (result.output.includes(COMPLETION_MARKER)) {
+            console.log(chalk.cyan(`  Agent signaled task complete`));
+            completed = true;
+            break;
+        }
+    }
+    console.log();
+    if (completed) {
+        console.log(chalk.green(`Task completed after ${actualIterations} iteration(s)`));
+    }
+    else {
+        console.log(chalk.yellow(`Reached max iterations (${iterations})`));
+    }
+    console.log(chalk.gray(`Logs: ${getSessionDir(sessionId)}`));
+}
+//# sourceMappingURL=run.js.map

package/dist/commands/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/commands/run.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import { run } from './commands/run.js';
+program
+    .name('ralph')
+    .description('Loop coding agent CLI - run agents headlessly in a loop')
+    .version('0.1.0');
+program
+    .command('run')
+    .description('Run an agent in a loop')
+    .requiredOption('-p, --prompt <files...>', 'Prompt files to pass to agent')
+    .option('-a, --agent <agent>', 'Agent type', 'claude')
+    .option('-i, --iterations <n>', 'Number of loop iterations', '4')
+    .action(run);
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAA;AAEvC,OAAO;KACJ,IAAI,CAAC,OAAO,CAAC;KACb,WAAW,CAAC,yDAAyD,CAAC;KACtE,OAAO,CAAC,OAAO,CAAC,CAAA;AAEnB,OAAO;KACJ,OAAO,CAAC,KAAK,CAAC;KACd,WAAW,CAAC,wBAAwB,CAAC;KACrC,cAAc,CAAC,yBAAyB,EAAE,+BAA+B,CAAC;KAC1E,MAAM,CAAC,qBAAqB,EAAE,YAAY,EAAE,QAAQ,CAAC;KACrD,MAAM,CAAC,sBAAsB,EAAE,2BAA2B,EAAE,GAAG,CAAC;KAChE,MAAM,CAAC,GAAG,CAAC,CAAA;AAEd,OAAO,CAAC,KAAK,EAAE,CAAA"}

package/dist/session/index.d.ts

@@ -0,0 +1,3 @@
+export * from './manager.js';
+export * from './logger.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA"}

package/dist/session/index.js

@@ -0,0 +1,3 @@
+export * from './manager.js';
+export * from './logger.js';
+//# sourceMappingURL=index.js.map

package/dist/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA"}

package/dist/session/logger.d.ts

@@ -0,0 +1,10 @@
+import type { AgentResult } from '../agents/base.js';
+export interface LogEntry {
+    iteration: number;
+    timestamp: string;
+    duration: number;
+    exitCode: number;
+    output: string;
+}
+export declare function writeLog(sessionId: string, iteration: number, result: AgentResult): Promise<void>;
+//# sourceMappingURL=logger.d.ts.map

package/dist/session/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/session/logger.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAGpD,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/session/logger.js

@@ -0,0 +1,17 @@
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getSessionDir } from './manager.js';
+export async function writeLog(sessionId, iteration, result) {
+    const sessionDir = getSessionDir(sessionId);
+    const logPath = join(sessionDir, `${iteration}.log`);
+    const header = [
+        `# Iteration ${iteration}`,
+        `Timestamp: ${new Date().toISOString()}`,
+        `Duration: ${result.duration}ms`,
+        `Exit Code: ${result.exitCode}`,
+        '---',
+        '',
+    ].join('\n');
+    await writeFile(logPath, header + result.output);
+}
+//# sourceMappingURL=logger.js.map

package/dist/session/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/session/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAU5C,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,SAAiB,EACjB,SAAiB,EACjB,MAAmB;IAEnB,MAAM,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC,CAAA;IAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,GAAG,SAAS,MAAM,CAAC,CAAA;IAEpD,MAAM,MAAM,GAAG;QACb,eAAe,SAAS,EAAE;QAC1B,cAAc,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE;QACxC,aAAa,MAAM,CAAC,QAAQ,IAAI;QAChC,cAAc,MAAM,CAAC,QAAQ,EAAE;QAC/B,KAAK;QACL,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAEZ,MAAM,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAA;AAClD,CAAC"}

package/dist/session/manager.d.ts

@@ -0,0 +1,18 @@
+export interface SessionMeta {
+    id: string;
+    promptFiles: string[];
+    agent: string;
+    cwd: string;
+    iterations: number;
+    startTime: string;
+}
+export declare function getRalphDir(): string;
+export declare function getSessionsDir(): string;
+export declare function getSessionDir(sessionId: string): string;
+export interface CreateSessionOpts {
+    promptFiles: string[];
+    agent: string;
+    iterations: number;
+}
+export declare function createSession(opts: CreateSessionOpts): Promise<string>;
+//# sourceMappingURL=manager.d.ts.map

package/dist/session/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/session/manager.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB5E"}

package/dist/session/manager.js

@@ -0,0 +1,29 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { nanoid } from 'nanoid';
+export function getRalphDir() {
+    return join(homedir(), '.ralph');
+}
+export function getSessionsDir() {
+    return join(getRalphDir(), 'sessions');
+}
+export function getSessionDir(sessionId) {
+    return join(getSessionsDir(), sessionId);
+}
+export async function createSession(opts) {
+    const sessionId = nanoid(10);
+    const sessionDir = getSessionDir(sessionId);
+    await mkdir(sessionDir, { recursive: true });
+    const meta = {
+        id: sessionId,
+        promptFiles: opts.promptFiles,
+        agent: opts.agent,
+        cwd: process.cwd(),
+        iterations: opts.iterations,
+        startTime: new Date().toISOString(),
+    };
+    await writeFile(join(sessionDir, 'meta.json'), JSON.stringify(meta, null, 2));
+    return sessionId;
+}
+//# sourceMappingURL=manager.js.map

package/dist/session/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/session/manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAW/B,MAAM,UAAU,WAAW;IACzB,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAA;AAClC,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,CAAC,WAAW,EAAE,EAAE,UAAU,CAAC,CAAA;AACxC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,OAAO,IAAI,CAAC,cAAc,EAAE,EAAE,SAAS,CAAC,CAAA;AAC1C,CAAC;AAQD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAuB;IACzD,MAAM,SAAS,GAAG,MAAM,CAAC,EAAE,CAAC,CAAA;IAC5B,MAAM,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC,CAAA;IAE3C,MAAM,KAAK,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAE5C,MAAM,IAAI,GAAgB;QACxB,EAAE,EAAE,SAAS;QACb,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;QAClB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAA;IAED,MAAM,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;IAE7E,OAAO,SAAS,CAAA;AAClB,CAAC"}

package/dist/utils/files.d.ts

@@ -0,0 +1,4 @@
+export declare const COMPLETION_MARKER = "<ralph>RALPH_COMPLETED</ralph>";
+export declare function readPromptFiles(inputs: string[]): Promise<string>;
+export declare function buildPrompt(inputs: string[]): Promise<string>;
+//# sourceMappingURL=files.d.ts.map

package/dist/utils/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/utils/files.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,iBAAiB,mCAAmC,CAAA;AAmBjE,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBvE;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAGnE"}

package/dist/utils/files.js

@@ -0,0 +1,39 @@
+import { readFile, access } from 'node:fs/promises';
+import { resolve } from 'node:path';
+export const COMPLETION_MARKER = '<ralph>RALPH_COMPLETED</ralph>';
+const COMPLETION_INSTRUCTIONS = `
+---
+When you have fully completed the task with no remaining work, include this marker in your final response:
+${COMPLETION_MARKER}
+
+Only use this marker when the task is 100% complete.
+`;
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function readPromptFiles(inputs) {
+    const contents = [];
+    for (const input of inputs) {
+        const absolutePath = resolve(process.cwd(), input);
+        if (await fileExists(absolutePath)) {
+            const content = await readFile(absolutePath, 'utf-8');
+            contents.push(content);
+        }
+        else {
+            // treat as direct text
+            contents.push(input);
+        }
+    }
+    return contents.join('\n\n');
+}
+export async function buildPrompt(inputs) {
+    const content = await readPromptFiles(inputs);
+    return content + COMPLETION_INSTRUCTIONS;
+}
+//# sourceMappingURL=files.js.map

package/dist/utils/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/utils/files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC,MAAM,CAAC,MAAM,iBAAiB,GAAG,gCAAgC,CAAA;AAEjE,MAAM,uBAAuB,GAAG;;;EAG9B,iBAAiB;;;CAGlB,CAAA;AAED,KAAK,UAAU,UAAU,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAA;QAClB,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAgB;IACpD,MAAM,QAAQ,GAAa,EAAE,CAAA;IAE7B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC,CAAA;QAElD,IAAI,MAAM,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YACnC,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAA;YACrD,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACxB,CAAC;aAAM,CAAC;YACN,uBAAuB;YACvB,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACtB,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;AAC9B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAgB;IAChD,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,CAAA;IAC7C,OAAO,OAAO,GAAG,uBAAuB,CAAA;AAC1C,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './files.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA"}

package/dist/utils/index.js

@@ -0,0 +1,2 @@
+export * from './files.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "rlph-cli",
+  "version": "0.1.0",
+  "description": "Loop coding agent CLI - run agents headlessly in a loop",
+  "type": "module",
+  "bin": {
+    "ralph": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "cli",
+    "agent",
+    "claude",
+    "loop",
+    "automation"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rem4ik4ever/ralph.git"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "nanoid": "^5.0.9"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "@vitest/coverage-v8": "^2.1.8",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  }
+}