@kraftapps-ai/kai 1.7.1 → 1.8.1

package/CLAUDE.md

@@ -6,29 +6,38 @@ Autonomous AI Shopify expert, product manager, and developer loop for Claude Cod
 
 - `kai` — the entire tool; a single bash script that bootstraps the PM agent and dev loop
 - `package.json` — npm metadata and version
-- `.kai/PROMPT.md` — per-project context (generated at runtime, not in repo)
 - `.kai/memory.md` — persistent memory across sessions (generated at runtime, not in repo)
 - `.kai/loop.sh` — dev loop script (generated at runtime, not in repo)
+- `.kai/loop-mcp.json` — MCP config without Playwright for the dev loop (generated at runtime)
 
 ## How it works
 
-1. `kai` script auto-inits project files (`kai.json`, `kai-progress.txt`, `.kai/PROMPT.md`, `.kai/memory.md`)
+1. `kai` script auto-inits project files (`.kai/stories.json`, `.kai/progress.txt`, `.kai/memory.md`)
 2. Auto-installs MCP servers if not already configured:
-   - **Playwright** — browser testing inside Shopify Admin
+   - **Playwright** — browser testing inside Shopify Admin (PM only, excluded from dev loop)
    - **@shopify/dev-mcp** — Shopify docs, GraphQL schema introspection, Liquid/GraphQL/component validation
-3. Generates `.kai/loop.sh` (the autonomous dev loop)
-4. Launches Claude with `--continue` to resume the last conversation (per-repo)
-5. Falls back to `.kai/memory.md` for context if conversation history is unavailable
+   - **Mantle** — Shopify app billing, subscriptions, analytics
+3. Generates `.kai/loop.sh` (the autonomous dev loop) and `.kai/loop-mcp.json` (MCP config without Playwright)
+4. Launches a tmux session with two panes: PM (left) and dev loop (right)
+5. Falls back to non-tmux mode if tmux is not installed or `--no-tmux` is passed
+
+## tmux integration
+
+Kai runs inside a tmux session (`kai`) with two panes:
+- **Pane 0 (left)** — The PM: interactive Claude session where you chat with Kai
+- **Pane 1 (right)** — Dev loop: streams live output when the PM kicks off `.kai/loop.sh`
+
+When you exit and run `kai` again, it reattaches to the existing tmux session. If the dev loop is still running in pane 1, it continues undisturbed — the PM respawns in pane 0 with full context from `.kai/memory.md`, `.kai/stories.json`, and `.kai/progress.txt`.
+
+Use `kai --no-tmux` to skip tmux and run in the current terminal (original behavior).
 
 ## Session persistence
 
-Kai uses a two-layer persistence strategy:
-- **`claude --continue`** — resumes the exact last conversation in this directory (primary)
-- **`.kai/memory.md`** — Kai-maintained memory file with key decisions, current focus, and session log (fallback)
+Kai uses `.kai/memory.md` to preserve context between sessions. The PM system prompt injects story status, progress log, and memory on every startup.
 
 Use `kai --new` to force a fresh conversation (memory.md is still loaded for context).
 
-The PM creates user stories in `kai.json`, then kicks off `.kai/loop.sh` which runs Claude in a loop — one story per iteration with self-review. Both the PM and the dev loop worker use Shopify Dev MCP tools to introspect APIs, search docs, and validate code.
+The PM creates user stories in `.kai/stories.json`, then kicks off `.kai/loop.sh` which runs Claude in a loop — one story per iteration with self-review. The dev loop uses a Playwright-free MCP config (`.kai/loop-mcp.json`) to avoid spawning Chromium browsers. Only the PM uses Playwright for QA.
 
 ## MCP servers
 
@@ -46,4 +55,4 @@ Version lives in `package.json` only.
 
 ## Testing changes
 
-Run `./kai` in any project directory. It will auto-init if `kai.json` doesn't exist.
+Run `./kai` in any project directory. It will auto-init if `.kai/stories.json` doesn't exist. Use `./kai --no-tmux` to test without tmux.

package/kai

@@ -15,6 +15,47 @@ if [ "${1:-}" = "--version" ] || [ "${1:-}" = "-v" ]; then
     exit 0
 fi
 
+# ── Parse kai flags ──────────────────────────────────
+
+KAI_TMUX=true
+PASSTHROUGH_ARGS=()
+for arg in "$@"; do
+    case "$arg" in
+        --no-tmux) KAI_TMUX=false ;;
+        --new) PASSTHROUGH_ARGS+=("$arg") ;;
+        *) PASSTHROUGH_ARGS+=("$arg") ;;
+    esac
+done
+set -- "${PASSTHROUGH_ARGS[@]}"
+
+# Fall back if tmux is not installed
+if ! command -v tmux &>/dev/null; then
+    KAI_TMUX=false
+fi
+
+# ── tmux session management ──────────────────────────
+
+KAI_TMUX_SESSION="kai"
+
+if [ "$KAI_TMUX" = true ]; then
+    # Already inside the kai tmux session — skip setup, run PM directly
+    if [ -n "${TMUX:-}" ] && [ "$(tmux display-message -p '#S' 2>/dev/null)" = "$KAI_TMUX_SESSION" ]; then
+        : # continue to normal execution below
+    elif tmux has-session -t "$KAI_TMUX_SESSION" 2>/dev/null; then
+        # Existing session — respawn PM in pane 0, reattach
+        tmux respawn-pane -k -t "${KAI_TMUX_SESSION}:0.0" \
+            "kai --no-tmux $(printf '%q ' "$@")"
+        exec tmux attach-session -t "$KAI_TMUX_SESSION"
+    else
+        # New session: pane 0 = PM, pane 1 = dev loop (waiting)
+        tmux new-session -d -s "$KAI_TMUX_SESSION" \
+            "kai --no-tmux $(printf '%q ' "$@")"
+        tmux split-window -h -t "${KAI_TMUX_SESSION}:0"
+        tmux select-pane -t "${KAI_TMUX_SESSION}:0.0"
+        exec tmux attach-session -t "$KAI_TMUX_SESSION"
+    fi
+fi
+
 PRD_FILE=".kai/stories.json"
 PROGRESS_FILE=".kai/progress.txt"
 MEMORY_FILE=".kai/memory.md"
@@ -167,6 +208,15 @@ MCPEOF
     echo "  MCP servers configured in .mcp.json"
 fi
 
+# ── Create loop MCP config (no Playwright) ───────────
+
+# Worker/reviewer don't need Playwright — it spawns Chromium and causes freezes
+if [ -f ".mcp.json" ]; then
+    jq 'del(.mcpServers.playwright)' .mcp.json > .kai/loop-mcp.json
+else
+    echo '{"mcpServers":{}}' > .kai/loop-mcp.json
+fi
+
 # ── Create the implementation loop script ─────────────
 
 cat > "$LOOP_SCRIPT" << 'LOOPEOF'
@@ -176,6 +226,13 @@ set -e
 
 PRD_FILE=".kai/stories.json"
 PROGRESS_FILE=".kai/progress.txt"
+LOOP_MCP_ARGS="--mcp-config .kai/loop-mcp.json"
+
+# Stream output live when running in a tmux pane
+KAI_STREAM=false
+if [ -n "${TMUX:-}" ]; then
+    KAI_STREAM=true
+fi
 
 WORKER_PROMPT='You are an autonomous AI developer specializing in Shopify app and theme development.
 
@@ -268,12 +325,18 @@ while :; do
     start_time=$(date +%s)
 
     set +e
-    result=$(claude -p --dangerously-skip-permissions --system-prompt "$WORKER_PROMPT" $context_files)
-    exit_code=$?
+    if [ "$KAI_STREAM" = true ]; then
+        claude -p --dangerously-skip-permissions $LOOP_MCP_ARGS --system-prompt "$WORKER_PROMPT" $context_files 2>&1 | tee .kai/worker-output.tmp
+        exit_code=${PIPESTATUS[0]}
+        result=$(cat .kai/worker-output.tmp)
+    else
+        result=$(claude -p --dangerously-skip-permissions $LOOP_MCP_ARGS --system-prompt "$WORKER_PROMPT" $context_files)
+        exit_code=$?
+        echo "$result" | tail -20
+    fi
     set -e
 
     elapsed=$(( $(date +%s) - start_time ))
-    echo "$result" | tail -20
 
     if [ $exit_code -ne 0 ]; then
         echo "Failed (code ${exit_code}). Restarting..."
@@ -286,14 +349,12 @@ while :; do
     fi
 
     # Review
-    STORY_PASSES=$(jq -r ".userStories[] | select(.id == $NEXT_ID) | .passes" "$PRD_FILE")
+    STORY_PASSES=$(jq -r --arg id "$NEXT_ID" '.userStories[] | select(.id == $id) | .passes' "$PRD_FILE")
     if [ "$STORY_PASSES" = "true" ]; then
         last_commit=$(git log --oneline -1 2>/dev/null || echo "no git")
-        ACCEPTANCE=$(jq -r ".userStories[] | select(.id == $NEXT_ID) | .acceptanceCriteria | join(\"\n- \")" "$PRD_FILE")
+        ACCEPTANCE=$(jq -r --arg id "$NEXT_ID" '.userStories[] | select(.id == $id) | .acceptanceCriteria | join("\n- ")' "$PRD_FILE")
 
-        set +e
-        review=$(claude -p --dangerously-skip-permissions \
-          "You are a Shopify expert code reviewer. Story #${NEXT_ID} ('${NEXT}') claims complete.
+        REVIEW_PROMPT="You are a Shopify expert code reviewer. Story #${NEXT_ID} ('${NEXT}') claims complete.
 Last commit: ${last_commit}
 Acceptance criteria:
 - ${ACCEPTANCE}
@@ -301,19 +362,35 @@ Read git diff HEAD~1 HEAD. Verify EACH criterion. Be skeptical.
 If the story involves Shopify APIs, use introspect_graphql_schema to verify the code uses correct fields and types.
 If it involves Liquid, use validate_theme_codeblocks to check for errors.
 If ANY fails: REVIEW_FAIL: [reason]
-If all pass: REVIEW_PASS")
-        set -e
+If all pass: REVIEW_PASS"
 
-        echo "$review" | tail -5
+        set +e
+        if [ "$KAI_STREAM" = true ]; then
+            claude -p --dangerously-skip-permissions $LOOP_MCP_ARGS "$REVIEW_PROMPT" 2>&1 | tee .kai/review-output.tmp
+            review=$(cat .kai/review-output.tmp)
+        else
+            review=$(claude -p --dangerously-skip-permissions $LOOP_MCP_ARGS "$REVIEW_PROMPT")
+            echo "$review" | tail -5
+        fi
+        set -e
 
         if [[ "$review" == *"REVIEW_FAIL"* ]]; then
-            jq --argjson id "$NEXT_ID" '(.userStories[] | select(.id == $id)).passes = false' "$PRD_FILE" > "${PRD_FILE}.tmp" && mv "${PRD_FILE}.tmp" "$PRD_FILE"
+            jq --arg id "$NEXT_ID" '(.userStories[] | select(.id == $id)).passes = false' "$PRD_FILE" > "${PRD_FILE}.tmp" && mv "${PRD_FILE}.tmp" "$PRD_FILE"
             echo "REVIEW FEEDBACK: $review" >> "$PROGRESS_FILE"
             review_failures=$((review_failures + 1))
-            [ $review_failures -ge 3 ] && {
-                jq --argjson id "$NEXT_ID" '(.userStories[] | select(.id == $id)).passes = true' "$PRD_FILE" > "${PRD_FILE}.tmp" && mv "${PRD_FILE}.tmp" "$PRD_FILE"
-                review_failures=0
-            }
+            if [ $review_failures -ge 3 ]; then
+                echo ""
+                echo "╔══════════════════════════════════════════════════╗"
+                echo "║  STALLED: Story #${NEXT_ID} failed review 3 times  ║"
+                echo "╚══════════════════════════════════════════════════╝"
+                echo ""
+                echo "Review feedback:" >> "$PROGRESS_FILE"
+                echo "$review" >> "$PROGRESS_FILE"
+                echo "" >> "$PROGRESS_FILE"
+                echo "STALLED: Story #${NEXT_ID} failed review 3 times. Human intervention needed." >> "$PROGRESS_FILE"
+                echo "Loop stopped at $(date). Waiting for human intervention."
+                exit 1
+            fi
         else
             review_failures=0
         fi
@@ -365,6 +442,16 @@ dev_greeting=""
 [ -n "$dev_name" ] && dev_greeting="
 The developer's name is: ${dev_name}"
 
+# ── Build loop run instructions for PM ────────────────
+
+if [ "$KAI_TMUX" = true ] || [ -n "${TMUX:-}" ]; then
+    LOOP_INSTRUCTIONS="To run implementation, execute: \`tmux send-keys -t ${KAI_TMUX_SESSION}:0.1 '.kai/loop.sh 2>&1 | tee .kai/loop.log' Enter\`
+The dev loop output streams live in the right tmux pane. You can also check \`tail -f .kai/loop.log\`.
+To stop the loop: \`tmux send-keys -t ${KAI_TMUX_SESSION}:0.1 C-c\`"
+else
+    LOOP_INSTRUCTIONS="To run implementation, execute: \`nohup .kai/loop.sh > .kai/loop.log 2>&1 &\` then monitor with \`tail -f .kai/loop.log\`"
+fi
+
 # ── Build Claude args ─────────────────────────────────
 
 CLAUDE_ARGS="--dangerously-skip-permissions --name kai"
@@ -462,7 +549,7 @@ OAuth authentication happens automatically via browser on first use — no API k
 
 Stories live in .kai/stories.json. Each has: id, title, description, acceptanceCriteria, priority, passes (true/false).
 To add stories, edit .kai/stories.json directly using the Edit or Write tool.
-To run implementation, execute: \`nohup .kai/loop.sh > .kai/loop.log 2>&1 &\` then monitor with \`tail -f .kai/loop.log\`
+${LOOP_INSTRUCTIONS}
 
 ## Browser testing (Playwright)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kraftapps-ai/kai",
-  "version": "1.7.1",
+  "version": "1.8.1",
   "description": "Autonomous AI developer loop for Claude Code",
   "bin": {
     "kai": "kai"