@lawrence369/loop-cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-10
+
+### Added
+
+- Iterative execution loop: executor produces output, reviewer scores (1-10), feedback fed back until approved
+- Multi-engine support: Claude CLI, Gemini CLI, Codex CLI via unified `Engine` interface
+- File-based event bus: append-only JSONL event streaming, crash-safe, zero external dependencies
+- Background daemon: agent lifecycle management with Unix domain socket IPC
+- Agent wrappers: `lclaude`, `lgemini`, `lcodex` — transforms CLI agents into loop participants
+- Skills system: executable markdown (SKILL.md) auto-injected into agent prompts
+- Interactive TUI: `@clack/prompts` guided setup + `blessed` real-time monitoring dashboard
+- Terminal adapters: pluggable backends for Terminal.app, iTerm2, tmux, PTY emulation
+- Shared plan management: cross-session iteration context with architectural decision tracking
+- Configuration cascade: project-level `.loop/config.json` with sensible defaults
+- 282 tests across 23 test files with full pass rate

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 loop-cli contributors
+
+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,136 @@
+# loop
+
+> Iterative Multi-Engine AI Orchestration CLI
+
+Combine **Claude**, **Gemini**, and **Codex** in a quality-scored iteration loop. One engine executes, another reviews. Repeat until perfect.
+
+```
+npm install -g @lawrence369/loop-cli
+```
+
+## What It Does
+
+```
+┌─────────────┐     ┌─────────────┐
+│   Executor   │────▶│   Reviewer   │
+│  (Claude)    │◀────│  (Gemini)    │
+└─────────────┘     └─────────────┘
+       │                    │
+       │    Score < 8?      │
+       │◀───Feedback────────│
+       │                    │
+       │    Score ≥ 8?      │
+       │────APPROVED───────▶│
+```
+
+You give it a task. The **executor** engine produces output. The **reviewer** engine scores it (1-10) and provides feedback. If the score doesn't meet the threshold, the feedback is fed back to the executor. This continues until the output is approved or max iterations are reached.
+
+## Quick Start
+
+```bash
+# Interactive guided setup
+loop
+
+# Direct execution
+loop "Refactor the auth module to use JWT" -e claude -r gemini
+
+# Auto mode with custom threshold
+loop "Write comprehensive tests for utils/" -e gemini -r claude --auto --threshold 9
+
+# Pass flags to the executor CLI
+loop "Build the API endpoints" -e claude --pass --model opus
+```
+
+## Features
+
+- **Multi-engine**: Claude CLI, Gemini CLI, Codex CLI — mix and match
+- **Quality-scored iteration**: Automatic review loop with configurable threshold (1-10)
+- **File-based event bus**: Append-only JSONL, crash-safe, zero external dependencies
+- **Multi-agent orchestration**: Background daemon with IPC for coordinating agent teams
+- **Skills system**: Executable markdown (`SKILL.md`) auto-injected into agent prompts
+- **Interactive TUI**: Beautiful guided setup + real-time monitoring dashboard
+- **Terminal adapters**: Terminal.app, iTerm2, tmux, built-in PTY
+- **Decision tracking**: Architectural decisions persisted across sessions
+- **Local-first**: Everything runs on your machine. No cloud services, no databases.
+
+## Commands
+
+```bash
+loop [task]              # Run iteration loop (interactive if no task)
+loop daemon start        # Start background daemon
+loop daemon stop         # Stop daemon
+loop daemon status       # Check daemon status
+loop bus tail            # Stream event bus
+loop bus stats           # Show bus statistics
+loop chat                # Open real-time dashboard
+loop plan show           # Show current iteration plan
+loop plan clear          # Clear plan
+loop ctx add             # Add architectural decision
+loop ctx list            # List decisions
+loop skills list         # List available skills
+loop skills show <name>  # Show skill content
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-e, --executor <engine>` | Executor engine: `claude` \| `gemini` \| `codex` |
+| `-r, --reviewer <engine>` | Reviewer engine: `claude` \| `gemini` \| `codex` |
+| `-n, --iterations <num>` | Max iterations (default: 5) |
+| `-d, --dir <path>` | Working directory |
+| `-v, --verbose` | Stream real-time output |
+| `--auto` | Auto mode — skip manual conversation |
+| `--pass <args...>` | Pass native flags to executor CLI |
+| `--threshold <num>` | Approval score threshold, 1-10 (default: 8) |
+
+## How It Works
+
+1. **Configuration**: Reads `.loop/config.json` from your project (or uses defaults)
+2. **Engine selection**: Picks executor + reviewer from config or CLI flags
+3. **Iteration loop**:
+   - Executor receives the task (with prior feedback, if any)
+   - Executor produces output via PTY-based CLI session
+   - Output is sent to the reviewer with the LoopMessage v1 protocol
+   - Reviewer scores (1-10) and provides structured feedback
+   - If score meets threshold or "APPROVED" keyword: done
+   - Otherwise: feedback → executor → next iteration
+4. **Event bus**: All messages logged to append-only JSONL for crash recovery
+5. **Skills**: Relevant `SKILL.md` files injected into agent prompts for context
+
+## Configuration
+
+Create `.loop/config.json` in your project:
+
+```json
+{
+  "executor": "claude",
+  "reviewer": "gemini",
+  "maxIterations": 5,
+  "threshold": 8,
+  "verbose": false,
+  "auto": false
+}
+```
+
+## Requirements
+
+- Node.js 18+
+- At least one AI CLI tool installed:
+  - [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli)
+  - [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+  - [Codex CLI](https://github.com/openai/codex)
+
+## Install from Source
+
+```bash
+git clone https://github.com/lawrence3699/loop.git
+cd loop
+npm install
+npm run build
+npm link
+```
+
+## License
+
+MIT

package/dist/agent/activity.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ActivityDetector — monitors a PtySession to determine the agent's
+ * current activity state.
+ *
+ * State machine:
+ *
+ *   starting ──▶ working ◀──▶ idle
+ *                  │             ▲
+ *                  ▼             │
+ *            waiting_input ──────┘
+ *                  │
+ *                  ▼
+ *               blocked
+ *
+ * Ported from ufoo's activityDetector.js, adapted to listen on
+ * PtySession events rather than receiving raw processOutput calls.
+ */
+import type { PtySession } from "./pty-session.js";
+export type ActivityState = "idle" | "working" | "starting" | "waiting_input" | "blocked";
+type StateChangeListener = (newState: ActivityState, oldState: ActivityState) => void;
+export declare class ActivityDetector {
+    private _state;
+    private _since;
+    private _detail;
+    private _buffer;
+    private _listeners;
+    private _blockedTimer;
+    private _quietTimer;
+    private _quietToken;
+    private readonly _quietWindowMs;
+    private readonly _blockedTimeoutMs;
+    private readonly _agentType;
+    private readonly _onPtyData;
+    private readonly _onIdle;
+    private readonly _session;
+    constructor(ptySession: PtySession, agentType?: string, options?: {
+        quietWindowMs?: number;
+        blockedTimeoutMs?: number;
+    });
+    getState(): ActivityState;
+    /** Timestamp of the last state transition. */
+    get since(): number;
+    /** Detail string associated with the current state. */
+    get detail(): string;
+    onStateChange(listener: StateChangeListener): void;
+    destroy(): void;
+    private _setState;
+    /**
+     * Process raw PTY output: normalize, buffer, transition to WORKING,
+     * and schedule quiet-window classification.
+     */
+    private _processOutput;
+    private _markIdle;
+    private _scheduleQuietClassification;
+    private _classifyAfterQuiet;
+    private _tailWindow;
+    private _hasDeniedContext;
+    private _startBlockedTimer;
+    private _clearBlockedTimer;
+    private _clearQuietTimer;
+    private _normalize;
+}
+export {};
+//# sourceMappingURL=activity.d.ts.map

package/dist/agent/activity.js

@@ -0,0 +1,265 @@
+/**
+ * ActivityDetector — monitors a PtySession to determine the agent's
+ * current activity state.
+ *
+ * State machine:
+ *
+ *   starting ──▶ working ◀──▶ idle
+ *                  │             ▲
+ *                  ▼             │
+ *            waiting_input ──────┘
+ *                  │
+ *                  ▼
+ *               blocked
+ *
+ * Ported from ufoo's activityDetector.js, adapted to listen on
+ * PtySession events rather than receiving raw processOutput calls.
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Time to wait after last output before classifying as idle / waiting_input. */
+const DEFAULT_QUIET_WINDOW_MS = 5_000;
+/** Time in waiting_input before escalating to blocked. */
+const DEFAULT_BLOCKED_TIMEOUT_MS = 300_000; // 5 min
+/** How many tail characters to check for input prompts. */
+const TAIL_BUFFER_SIZE = 4_000;
+const TAIL_LINES = 10;
+/** ANSI / OSC stripping patterns (for the rolling buffer). */
+const ANSI_RE = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+const OSC_RE = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+// Agent-specific patterns that indicate the CLI is waiting for user input.
+const INPUT_PATTERNS = {
+    "claude-code": [
+        /\bAllow\b.*\bDeny\b/,
+        /\ballow mcp\b/i,
+        /Enter to select.*\u2191\/\u2193 to navigate/,
+    ],
+    codex: [
+        /\[Y\/n\]/,
+        /\by\/n\b/i,
+    ],
+};
+const COMMON_INPUT_PATTERNS = [
+    /Continue\?\s*$/m,
+    /Proceed\?\s*$/m,
+    /Press enter/i,
+    /\(y\/n\)\s*:?\s*$/m,
+];
+// Deny-list: per-line context that suppresses false positive prompt matches.
+const LINE_DENY_PATTERNS = [
+    /function\s+\w+/,
+    /\/\//,
+    /import\s+/,
+    /require\s*\(/,
+];
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+export class ActivityDetector {
+    _state = "starting";
+    _since = Date.now();
+    _detail = "";
+    _buffer = "";
+    _listeners = [];
+    _blockedTimer = null;
+    _quietTimer = null;
+    _quietToken = 0;
+    _quietWindowMs;
+    _blockedTimeoutMs;
+    _agentType;
+    _onPtyData;
+    _onIdle;
+    _session;
+    constructor(ptySession, agentType, options) {
+        this._session = ptySession;
+        this._agentType = agentType ?? "";
+        this._quietWindowMs = options?.quietWindowMs ?? DEFAULT_QUIET_WINDOW_MS;
+        this._blockedTimeoutMs = options?.blockedTimeoutMs ?? DEFAULT_BLOCKED_TIMEOUT_MS;
+        // PTY data → mark working, buffer output, schedule classification
+        this._onPtyData = (data) => {
+            this._processOutput(data);
+        };
+        // Idle event → fast-path to idle state
+        this._onIdle = () => {
+            this._markIdle();
+        };
+        this._session.on("pty-data", this._onPtyData);
+        this._session.on("idle", this._onIdle);
+    }
+    // ── Public API ──────────────────────────────────────────────────────────
+    getState() {
+        return this._state;
+    }
+    /** Timestamp of the last state transition. */
+    get since() {
+        return this._since;
+    }
+    /** Detail string associated with the current state. */
+    get detail() {
+        return this._detail;
+    }
+    onStateChange(listener) {
+        this._listeners.push(listener);
+    }
+    destroy() {
+        this._clearBlockedTimer();
+        this._clearQuietTimer();
+        this._listeners = [];
+        this._session.removeListener("pty-data", this._onPtyData);
+        this._session.removeListener("idle", this._onIdle);
+    }
+    // ── Internal transitions ────────────────────────────────────────────────
+    _setState(newState, detail = "") {
+        if (newState === this._state)
+            return;
+        const oldState = this._state;
+        this._state = newState;
+        this._since = Date.now();
+        this._detail = detail;
+        for (const cb of this._listeners) {
+            try {
+                cb(newState, oldState);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+    /**
+     * Process raw PTY output: normalize, buffer, transition to WORKING,
+     * and schedule quiet-window classification.
+     */
+    _processOutput(raw) {
+        const normalized = this._normalize(raw);
+        if (!normalized)
+            return;
+        // Check for meaningful visible content
+        const visible = normalized.replace(/[\s\u0000-\u001F\u007F]+/g, "");
+        if (visible.length === 0)
+            return;
+        // STARTING → WORKING on first meaningful output
+        if (this._state === "starting") {
+            this._setState("working", "output");
+        }
+        // Append to rolling buffer
+        this._buffer += normalized;
+        if (this._buffer.length > TAIL_BUFFER_SIZE) {
+            this._buffer = this._buffer.slice(-TAIL_BUFFER_SIZE);
+        }
+        // Any output means WORKING (cancels prior waiting/blocked)
+        if (this._state !== "working") {
+            this._clearBlockedTimer();
+            this._setState("working");
+        }
+        this._scheduleQuietClassification();
+    }
+    _markIdle() {
+        if (this._state !== "working" &&
+            this._state !== "waiting_input" &&
+            this._state !== "blocked") {
+            return;
+        }
+        this._clearBlockedTimer();
+        this._clearQuietTimer();
+        this._buffer = "";
+        this._setState("idle");
+    }
+    // ── Quiet-window classification ─────────────────────────────────────────
+    _scheduleQuietClassification() {
+        this._quietToken += 1;
+        const token = this._quietToken;
+        this._clearQuietTimer();
+        this._quietTimer = setTimeout(() => {
+            if (token !== this._quietToken)
+                return;
+            this._quietTimer = null;
+            this._classifyAfterQuiet();
+        }, this._quietWindowMs);
+        if (this._quietTimer && typeof this._quietTimer.unref === "function") {
+            this._quietTimer.unref();
+        }
+    }
+    _classifyAfterQuiet() {
+        if (this._state !== "working")
+            return;
+        const tail = this._tailWindow();
+        // Check agent-specific and common prompt patterns
+        const agentPatterns = INPUT_PATTERNS[this._agentType] ?? [];
+        const allPatterns = [...agentPatterns, ...COMMON_INPUT_PATTERNS];
+        for (const pattern of allPatterns) {
+            const match = pattern.exec(tail);
+            if (!match)
+                continue;
+            const matchedText = match[0] ?? "";
+            const matchIndex = Number.isFinite(match.index)
+                ? match.index
+                : Math.max(0, tail.length - matchedText.length);
+            if (this._hasDeniedContext(tail, matchIndex, matchedText.length))
+                continue;
+            this._setState("waiting_input", pattern.source);
+            this._startBlockedTimer();
+            return;
+        }
+        // No input patterns matched → idle
+        this._setState("idle");
+    }
+    _tailWindow() {
+        if (!this._buffer)
+            return "";
+        const lines = this._buffer.split("\n");
+        if (lines.length <= TAIL_LINES)
+            return this._buffer;
+        return lines.slice(-TAIL_LINES).join("\n");
+    }
+    _hasDeniedContext(haystack, matchIndex, matchLength) {
+        // Inside a code fence?
+        const before = haystack.slice(0, Math.max(0, matchIndex));
+        const fences = before.match(/```/g);
+        if ((fences ? fences.length : 0) % 2 === 1)
+            return true;
+        // Check surrounding line against deny patterns
+        const center = Math.max(0, matchIndex + Math.max(0, Math.trunc(matchLength / 2)));
+        const lineStart = haystack.lastIndexOf("\n", center - 1) + 1;
+        const lineEndCandidate = haystack.indexOf("\n", center);
+        const lineEnd = lineEndCandidate >= 0 ? lineEndCandidate : haystack.length;
+        const line = haystack.slice(lineStart, lineEnd);
+        return LINE_DENY_PATTERNS.some((deny) => deny.test(line));
+    }
+    // ── Timers ──────────────────────────────────────────────────────────────
+    _startBlockedTimer() {
+        this._clearBlockedTimer();
+        this._blockedTimer = setTimeout(() => {
+            this._blockedTimer = null;
+            if (this._state === "waiting_input") {
+                this._setState("blocked", `waiting_input for ${this._blockedTimeoutMs}ms`);
+            }
+        }, this._blockedTimeoutMs);
+        if (this._blockedTimer && typeof this._blockedTimer.unref === "function") {
+            this._blockedTimer.unref();
+        }
+    }
+    _clearBlockedTimer() {
+        if (this._blockedTimer) {
+            clearTimeout(this._blockedTimer);
+            this._blockedTimer = null;
+        }
+    }
+    _clearQuietTimer() {
+        if (this._quietTimer) {
+            clearTimeout(this._quietTimer);
+            this._quietTimer = null;
+        }
+    }
+    // ── Helpers ─────────────────────────────────────────────────────────────
+    _normalize(text) {
+        if (!text)
+            return "";
+        return String(text)
+            .replace(OSC_RE, "")
+            .replace(/\r\n/g, "\n")
+            .replace(/\r/g, "\n")
+            .replace(ANSI_RE, "");
+    }
+}
+//# sourceMappingURL=activity.js.map

package/dist/agent/launcher.d.ts

@@ -0,0 +1,42 @@
+/**
+ * AgentLauncher — unified agent lifecycle manager.
+ *
+ * Handles:
+ *   1. Ensuring the .loop/ project directory exists
+ *   2. Detecting (or using specified) launch mode
+ *   3. Spawning a PtySession via the appropriate terminal adapter
+ *   4. Setting up ReadyDetector + ActivityDetector
+ *   5. Registering with the daemon via IPC (fail-silently if no daemon)
+ *   6. SIGTERM / SIGINT cleanup
+ *
+ * Simplified port of ufoo's launcher.js.
+ */
+import { PtySession } from "./pty-session.js";
+import { ActivityDetector } from "./activity.js";
+import { ReadyDetector } from "./ready-detector.js";
+import { type LaunchMode } from "../terminal/detect.js";
+export interface LaunchOptions {
+    agentType: string;
+    command: string;
+    args: string[];
+    cwd: string;
+    launchMode?: LaunchMode;
+    nickname?: string;
+    env?: Record<string, string>;
+}
+export interface LaunchedAgent {
+    subscriberId: string;
+    ptySession: PtySession;
+    activityDetector: ActivityDetector;
+    readyDetector: ReadyDetector;
+    cleanup: () => Promise<void>;
+}
+export declare class AgentLauncher {
+    private readonly _projectRoot;
+    constructor(projectRoot: string);
+    /**
+     * Launch an agent, returning a handle with the PtySession and detectors.
+     */
+    launch(opts: LaunchOptions): Promise<LaunchedAgent>;
+}
+//# sourceMappingURL=launcher.d.ts.map