From 54456ee90e843c8a17a7d69726fd5b4a2bbecc1b Mon Sep 17 00:00:00 2001
From: taorye <taorye@outlook.com>
Date: Wed, 25 Mar 2026 16:08:28 +0800
Subject: [PATCH] chore(tui): add build target for picoclaw-launcher TUI and
 create README for TUI launcher

---
 Makefile                            |  8 ++++
 cmd/picoclaw-launcher-tui/README.md | 69 +++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 cmd/picoclaw-launcher-tui/README.md

diff --git a/Makefile b/Makefile
index 0b09cf7f7c..77af92d4a8 100644
--- a/Makefile
+++ b/Makefile
@@ -131,6 +131,14 @@ build-launcher:
 	@ln -sf picoclaw-launcher-$(PLATFORM)-$(ARCH) $(BUILD_DIR)/picoclaw-launcher
 	@echo "Build complete: $(BUILD_DIR)/picoclaw-launcher"
 
+## build-launcher-tui: Build the picoclaw-launcher TUI binary
+build-launcher-tui:
+	@echo "Building picoclaw-launcher-tui for $(PLATFORM)/$(ARCH)..."
+	@mkdir -p $(BUILD_DIR)
+	@$(GO) build $(GOFLAGS) -o $(BUILD_DIR)/picoclaw-launcher-tui-$(PLATFORM)-$(ARCH) ./cmd/picoclaw-launcher-tui
+	@ln -sf picoclaw-launcher-tui-$(PLATFORM)-$(ARCH) $(BUILD_DIR)/picoclaw-launcher-tui
+	@echo "Build complete: $(BUILD_DIR)/picoclaw-launcher-tui"
+
 ## build-whatsapp-native: Build with WhatsApp native (whatsmeow) support; larger binary
 build-whatsapp-native: generate
 ## @echo "Building $(BINARY_NAME) with WhatsApp native for $(PLATFORM)/$(ARCH)..."
diff --git a/cmd/picoclaw-launcher-tui/README.md b/cmd/picoclaw-launcher-tui/README.md
new file mode 100644
index 0000000000..a942045a54
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/README.md
@@ -0,0 +1,69 @@
+# Picoclaw Launcher TUI
+
+This directory contains the terminal-based TUI launcher for `picoclaw`.
+It provides a lightweight, terminal-native user interface for managing, configuring, and interacting with the core `picoclaw` engine, without requiring a web browser or graphical environment.
+
+## Architecture
+
+The TUI launcher is implemented purely in Go with no external runtime dependencies:
+* **`main.go`**: Application entry point, handles initialization and main event loop
+* **`ui/`**: TUI interface components built on tview + tcell framework:
+  - `home.go`: Main dashboard with navigation menu
+  - `schemes.go`: AI model scheme management
+  - `users.go`: User and API key management for model providers
+  - `channels.go`: Communication channel (Telegram/Discord/WeChat etc.) configuration editor
+  - `gateway.go`: PicoClaw gateway daemon lifecycle management (start/stop/status)
+  - `app.go`: Core TUI application framework and navigation logic
+  - `models.go`: Data structures and state management
+* **`config/`**: Configuration management layer, integrates with the core picoclaw configuration system
+
+## Getting Started
+
+### Prerequisites
+
+* Go 1.25+
+* Terminal with 256-color support (most modern terminals are compatible)
+
+### Development
+
+Run the TUI launcher directly in development mode:
+
+```bash
+# From project root
+go run ./cmd/picoclaw-launcher-tui
+
+# Or from this directory
+go run .
+```
+
+### Build
+
+Build the standalone TUI launcher binary:
+
+```bash
+# From project root (recommended)
+make build-launcher-tui
+
+# Output will be at:
+# build/picoclaw-launcher-tui-<platform>-<arch>
+# with symlink build/picoclaw-launcher-tui
+
+# Or build directly from this directory
+go build -o picoclaw-launcher-tui .
+```
+
+### Key Features
+
+* 🖥️ Terminal-native interface - works over SSH, on headless servers, and in low-resource environments
+* ⚙️ AI model scheme and API key management
+* 📱 Communication channel configuration editor (Telegram/Discord/WeChat etc.)
+* 🔄 PicoClaw gateway daemon management (start/stop/status monitoring)
+* 💬 One-click launch of interactive AI chat session
+* 🎯 Keyboard-first design with intuitive shortcuts
+
+### Other Commands
+
+```bash
+# Run with custom config file path
+go run . /path/to/custom/config.json
+```