culater 1.0.5 → 1.1.0

package/README.md

@@ -1,16 +1,26 @@
 # culater
 
-Remote terminal for Claude Code - c(See) you later!
+**Your AI terminal, anywhere.**
 
-Access Claude Code from your phone via a secure tunnel.
+`culater` gives you fast phone access to your local Claude Code shell through a secure Cloudflare tunnel, so you can check output, unblock an agent, and keep moving when you're away from your desk.
 
-## Quick Start
+## Demo
 
-```bash
-npx culater mypassword
-```
+<p align="center">
+  <img src="assets/culater-demo.gif" alt="culater demo" width="720">
+</p>
+
+## Why culater
+
+- Agent-first remote terminal workflow from any mobile browser
+- Session survives refreshes and temporary network drops
+- Project-aware startup (recent folders remembered in `~/.culater/config.json`)
+- Manual `AI` launch when you want Claude, no forced auto-start
+- One command to start, no account setup
+
+## Quick Start
 
-## Requirements
+### 1) Install requirements
 
 - Node.js 18+
 - [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/)
@@ -23,10 +33,39 @@ brew install cloudflared
 sudo apt install cloudflared
 ```
 
-## Options
+### 2) Start culater
 
+```bash
+npx culater mypassword
 ```
--n, --ntfy <topic>     ntfy.sh topic for push notifications (saved for next time)
+
+### 3) Open it on your phone
+
+- Scan the terminal QR code
+- Enter the password
+- Start shell (or auto-start if no previous project history exists)
+
+## How It Works
+
+1. `culater` starts a local PTY shell.
+2. It creates a temporary Cloudflare tunnel URL.
+3. Your phone connects to the web terminal and controls that shell in real time.
+
+## Features
+
+- Mobile-optimized terminal UI
+- Touch scrolling with momentum
+- Quick action buttons (`/`, `Esc`, `Enter`, cursor pad)
+- Keyboard-aware controls that stay above the fold
+- Auto-reconnect and persistent session resume
+- Manual `AI` button to run Claude on demand
+- Password gate before terminal access
+- Optional ntfy push notifications for tunnel URL
+
+## CLI Options
+
+```txt
+-n, --ntfy <topic>     ntfy.sh topic for push notifications (saved)
 -d, --dir <path>       Working directory (default: current)
 -h, --help             Show help
 ```
@@ -37,27 +76,17 @@ sudo apt install cloudflared
 # Start with password
 npx culater mysecret
 
-# With push notifications (saved to /tmp/culater.json)
-npx culater mysecret -n my-ntfy-topic
-
-# Subsequent runs use saved ntfy topic automatically
-npx culater mysecret
-
-# Specific directory
+# Use a specific directory
 npx culater mysecret -d ~/projects/myapp
+
+# Enable ntfy notifications (saved for later runs)
+npx culater mysecret -n my-ntfy-topic
 ```
 
-## Features
+## Notes
 
-- Mobile-optimized terminal UI
-- Touch scrolling with momentum
-- Quick action buttons (/, Esc, ↓, Enter)
-- Auto-reconnect on disconnect
-- Keyboard-aware button positioning
-- Streaming indicator
-- Password protection
-- Secure cloudflare tunnel
-- Push notifications via ntfy.sh (remembers your topic)
+- Config is stored at `~/.culater/config.json`.
+- First tunnel open can briefly show Cloudflare `1033` while edge registration finishes.
 
 ## License
 

package/bin/culater.js

@@ -2,8 +2,13 @@
 
 const { execSync } = require('child_process');
 const fs = require('fs');
+const os = require('os');
+const path = require('path');
 
-const CONFIG_FILE = '/tmp/culater.json';
+const CONFIG_DIR = path.join(os.homedir(), '.culater');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const LEGACY_CONFIG_FILE = '/tmp/culater.json';
+const MAX_RECENT_DIRS = 12;
 
 // Check for cloudflared
 try {
@@ -19,13 +24,18 @@ function loadConfig() {
   try {
     return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
   } catch {
-    return {};
+    try {
+      return JSON.parse(fs.readFileSync(LEGACY_CONFIG_FILE, 'utf8'));
+    } catch {
+      return {};
+    }
   }
 }
 
 // Save config
 function saveConfig(config) {
   try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
     fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
   } catch {}
 }
@@ -63,20 +73,31 @@ if (!password) {
   process.exit(1);
 }
 
+workDir = path.resolve(workDir);
+
 // Load config and use saved ntfy if not provided
 const config = loadConfig();
 if (ntfyTopic) {
   // Save new ntfy topic
   config.ntfyTopic = ntfyTopic;
-  saveConfig(config);
 } else if (config.ntfyTopic) {
   // Use saved ntfy topic
   ntfyTopic = config.ntfyTopic;
 }
 
+const recentDirs = Array.isArray(config.recentDirs) ? config.recentDirs : [];
+const normalizedRecent = recentDirs
+  .filter(dir => typeof dir === 'string' && dir.trim())
+  .map(dir => path.resolve(dir));
+const previousRecentDirs = Array.from(new Set(normalizedRecent)).slice(0, MAX_RECENT_DIRS);
+const nextRecentDirs = [workDir, ...previousRecentDirs.filter(dir => dir !== workDir)].slice(0, MAX_RECENT_DIRS);
+config.recentDirs = nextRecentDirs;
+saveConfig(config);
+
 // Set env and run server
 process.env.REMOTE_PASSWORD = password;
 process.env.NTFY_TOPIC = ntfyTopic || '';
 process.env.WORK_DIR = workDir;
+process.env.RECENT_DIRS = JSON.stringify(previousRecentDirs);
 
 require('../lib/server.js');