tloop-cli 0.4.0__tar.gz

tloop_cli-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XiaodongTong
+
+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.

tloop_cli-0.4.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: tloop-cli
+Version: 0.4.0
+Summary: Automated Claude Code task runner
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Dynamic: license-file
+
+# t-loop
+
+自动化 Claude Code 任务运行器。用 YAML 定义任务，t-loop 按顺序执行，自带 git 安全保护。
+
+## 安装
+
+```bash
+pip install t-loop            # 从 PyPI 安装
+pip install -e .              # 本地开发安装
+```
+
+需要 Python >=3.9，唯一外部依赖：`pyyaml`。
+
+## 快速开始
+
+```bash
+# 首次运行会创建 ~/.tloop/tasks.yaml 示例配置
+tloop run
+
+# 编辑任务后运行
+tloop edit
+tloop run
+```
+
+## 任务配置
+
+编辑 `~/.tloop/tasks.yaml`：
+
+```yaml
+tasks:
+  - name: 我的第一个任务
+    dir: ~/projects/my-project
+    prompt: |
+      描述 Claude 应该做什么。
+
+  - name: 使用 prompt 文件的任务
+    dir: ~/projects/my-project
+    prompt_file: ./prompts/my-task.md
+    branch: feat/login   # 自定义分支名
+```
+
+### 任务字段
+
+| 字段 | 说明 |
+|-------|-------------|
+| `name` | 任务显示名称 |
+| `dir` | 任务工作目录 |
+| `prompt` | 内联 prompt 文本 |
+| `prompt_file` | prompt 文件路径（解析顺序：绝对路径 → `~/.tloop/` 相对 → 任务目录相对） |
+| `model` | 覆盖该任务的模型 |
+| `branch` | `true`（自动 `feature-YYYYMMDD-NNN`）、`"custom/name"`、或 `false`（跳过分支） |
+
+## 用法
+
+```bash
+tloop run                  # 运行所有待执行任务
+tloop run --status         # 查看任务状态
+tloop run --only 2         # 只运行第 2 个任务
+tloop run --confirm        # 每个任务前确认
+tloop run -c               # 失败后继续执行
+tloop run --reset          # 重置所有任务为待执行
+tloop edit                 # 用 $EDITOR 打开 tasks.yaml
+tloop archive              # 列出归档记录
+tloop archive --latest     # 显示最近一次归档详情
+tloop migrate              # 迁移旧的项目本地数据到 ~/.tloop/
+```
+
+## 工作原理
+
+每个任务的执行流程：
+
+1. **自动提交** — 如果工作目录有未提交的更改，t-loop 会用 Claude 先提交暂存区内容，再提交剩余更改。敏感文件（.env、密钥等）会被排除。
+2. **创建分支** — 创建任务分支（默认 `feature-YYYYMMDD-NNN`）隔离更改。
+3. **执行任务** — 在目标目录运行 `cybervisor run <prompt>`。
+4. **归档** — 已完成的任务移至 `~/.tloop/archive/`，并从 `tasks.yaml` 中移除。
+
+## 文件位置
+
+```
+~/.tloop/
+├── tasks.yaml      # 任务定义
+├── state.json      # 运行时状态（任务状态）
+├── logs/           # 执行日志
+└── archive/        # 已完成任务的归档
+```
+
+## 开发
+
+```bash
+pip install -e .
+python -m pytest test/ -v
+```
+
+## 许可证
+
+MIT

tloop_cli-0.4.0/README.md

@@ -0,0 +1,96 @@
+# t-loop
+
+自动化 Claude Code 任务运行器。用 YAML 定义任务，t-loop 按顺序执行，自带 git 安全保护。
+
+## 安装
+
+```bash
+pip install t-loop            # 从 PyPI 安装
+pip install -e .              # 本地开发安装
+```
+
+需要 Python >=3.9，唯一外部依赖：`pyyaml`。
+
+## 快速开始
+
+```bash
+# 首次运行会创建 ~/.tloop/tasks.yaml 示例配置
+tloop run
+
+# 编辑任务后运行
+tloop edit
+tloop run
+```
+
+## 任务配置
+
+编辑 `~/.tloop/tasks.yaml`：
+
+```yaml
+tasks:
+  - name: 我的第一个任务
+    dir: ~/projects/my-project
+    prompt: |
+      描述 Claude 应该做什么。
+
+  - name: 使用 prompt 文件的任务
+    dir: ~/projects/my-project
+    prompt_file: ./prompts/my-task.md
+    branch: feat/login   # 自定义分支名
+```
+
+### 任务字段
+
+| 字段 | 说明 |
+|-------|-------------|
+| `name` | 任务显示名称 |
+| `dir` | 任务工作目录 |
+| `prompt` | 内联 prompt 文本 |
+| `prompt_file` | prompt 文件路径（解析顺序：绝对路径 → `~/.tloop/` 相对 → 任务目录相对） |
+| `model` | 覆盖该任务的模型 |
+| `branch` | `true`（自动 `feature-YYYYMMDD-NNN`）、`"custom/name"`、或 `false`（跳过分支） |
+
+## 用法
+
+```bash
+tloop run                  # 运行所有待执行任务
+tloop run --status         # 查看任务状态
+tloop run --only 2         # 只运行第 2 个任务
+tloop run --confirm        # 每个任务前确认
+tloop run -c               # 失败后继续执行
+tloop run --reset          # 重置所有任务为待执行
+tloop edit                 # 用 $EDITOR 打开 tasks.yaml
+tloop archive              # 列出归档记录
+tloop archive --latest     # 显示最近一次归档详情
+tloop migrate              # 迁移旧的项目本地数据到 ~/.tloop/
+```
+
+## 工作原理
+
+每个任务的执行流程：
+
+1. **自动提交** — 如果工作目录有未提交的更改，t-loop 会用 Claude 先提交暂存区内容，再提交剩余更改。敏感文件（.env、密钥等）会被排除。
+2. **创建分支** — 创建任务分支（默认 `feature-YYYYMMDD-NNN`）隔离更改。
+3. **执行任务** — 在目标目录运行 `cybervisor run <prompt>`。
+4. **归档** — 已完成的任务移至 `~/.tloop/archive/`，并从 `tasks.yaml` 中移除。
+
+## 文件位置
+
+```
+~/.tloop/
+├── tasks.yaml      # 任务定义
+├── state.json      # 运行时状态（任务状态）
+├── logs/           # 执行日志
+└── archive/        # 已完成任务的归档
+```
+
+## 开发
+
+```bash
+pip install -e .
+python -m pytest test/ -v
+```
+
+## 许可证
+
+MIT

tloop_cli-0.4.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tloop-cli"
+version = "0.4.0"
+description = "Automated Claude Code task runner"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+dependencies = [
+    "pyyaml>=6.0",
+]
+
+[project.scripts]
+tloop = "main:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+py-modules = ["main", "config", "state", "task", "cmd_run", "cmd_edit", "cmd_migrate", "cmd_archive", "git_ops", "claude_runner"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["runner*"]
+
+[tool.pytest.ini_options]
+testpaths = ["test"]

tloop_cli-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tloop_cli-0.4.0/src/claude_runner.py

@@ -0,0 +1,82 @@
+"""Reusable Claude CLI runner with retry and verification."""
+
+import subprocess
+
+GREEN = "\033[92m"
+RED = "\033[91m"
+YELLOW = "\033[93m"
+RESET = "\033[0m"
+
+DEFAULT_MAX_RETRIES = 3
+
+# Append this to prompts where Claude might just plan instead of executing.
+EXECUTION_SUFFIX = (
+    "\n\nIMPORTANT: Execute the steps above immediately. "
+    "Do NOT ask for confirmation, do NOT just describe what you would do. "
+    "Perform every step now using your available tools."
+)
+
+
+def run_claude(prompt, cwd, max_retries=DEFAULT_MAX_RETRIES, verify_fn=None, log_file=None):
+    """Run `claude -p` with --dangerously-skip-permissions and optional retry loop.
+
+    Args:
+        prompt: The prompt text to send to Claude.
+        cwd: Working directory for the subprocess.
+        max_retries: Max attempts before giving up.
+        verify_fn: Optional callable(cwd) -> bool that checks if the work was actually done.
+        log_file: Optional path to append logs.
+
+    Returns:
+        True if Claude succeeded (and passed verification if provided), False otherwise.
+    """
+    enriched_prompt = prompt + EXECUTION_SUFFIX
+    cmd = ["claude", "--dangerously-skip-permissions", "--print", enriched_prompt]
+
+    for attempt in range(1, max_retries + 1):
+        if attempt > 1:
+            hint = (
+                f"This is attempt {attempt}/{max_retries}. "
+                "The previous attempt did not complete the task. "
+                "You MUST execute the steps now, not describe them."
+            )
+            attempt_prompt = prompt + "\n\n" + hint + EXECUTION_SUFFIX
+            attempt_cmd = ["claude", "--dangerously-skip-permissions", "--print", attempt_prompt]
+        else:
+            attempt_cmd = cmd
+
+        result = subprocess.run(
+            attempt_cmd,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+        )
+
+        if log_file:
+            with open(log_file, "a") as log:
+                log.write(f"[claude_runner] attempt {attempt}/{max_retries} exit={result.returncode}\n")
+                if result.stdout:
+                    log.write(result.stdout + "\n")
+                if result.stderr:
+                    log.write(result.stderr + "\n")
+                log.flush()
+
+        if result.returncode != 0:
+            print(f"{YELLOW}  Claude exited with code {result.returncode} (attempt {attempt}/{max_retries}){RESET}")
+            if attempt < max_retries:
+                continue
+            return False
+
+        # If no verification function, trust the exit code.
+        if verify_fn is None:
+            return True
+
+        if verify_fn(cwd):
+            return True
+
+        print(f"{YELLOW}  Claude completed but verification failed (attempt {attempt}/{max_retries}){RESET}")
+        if attempt >= max_retries:
+            print(f"{RED}  Max retries reached. Giving up.{RESET}")
+            return False
+
+    return False

tloop_cli-0.4.0/src/cmd_archive.py

@@ -0,0 +1,15 @@
+"""tloop archive — view archived task runs."""
+
+import config
+from state import show_archives
+
+
+def add_parser(subparsers):
+    p = subparsers.add_parser("archive", help="View archived task runs")
+    p.add_argument("--latest", action="store_true", help="Show most recent archive details")
+    p.set_defaults(func=handle)
+
+
+def handle(args):
+    config.ARCHIVE_DIR.mkdir(parents=True, exist_ok=True)
+    show_archives(latest=args.latest)

tloop_cli-0.4.0/src/cmd_edit.py

@@ -0,0 +1,45 @@
+"""tloop edit — open ~/.tloop/tasks.yaml in editor."""
+
+import argparse
+import os
+import subprocess
+
+import config
+
+
+EDIT_HELP = """\
+Open ~/.tloop/tasks.yaml in your editor ($EDITOR, defaults to vi).
+
+Task file format (~/.tloop/tasks.yaml):
+
+  defaults:
+    model: opus              # optional default model
+
+  tasks:
+    - name: My task
+      dir: ~/projects/my-project
+      prompt: |
+        Describe what Claude should do.
+      # OR:
+      prompt_file: ./prompts/my-task.md
+      model: opus            # optional override
+      branch: true           # true=auto, "custom/name", false=skip
+
+  Each task runs in the specified directory. Completed tasks are
+  archived to ~/.tloop/archive/ after each run cycle.
+"""
+
+
+def add_parser(subparsers):
+    p = subparsers.add_parser(
+        "edit",
+        help="Open ~/.tloop/tasks.yaml in editor",
+        description=EDIT_HELP,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.set_defaults(func=handle)
+
+
+def handle(args):
+    editor = os.environ.get("EDITOR", "vi")
+    subprocess.run([editor, str(config.TASKS_FILE)])

tloop_cli-0.4.0/src/cmd_migrate.py

@@ -0,0 +1,71 @@
+"""tloop migrate — migrate old data files to ~/.tloop/."""
+
+import shutil
+import sys
+from pathlib import Path
+
+import yaml
+
+import config
+
+
+def add_parser(subparsers):
+    p = subparsers.add_parser("migrate", help="Migrate old data to ~/.tloop/")
+    p.set_defaults(func=handle)
+
+
+def handle(args):
+    project_root = Path(__file__).resolve().parent.parent.parent
+
+    old_tasks = project_root / "tasks.yaml"
+    old_state = project_root / ".tloop-state.json"
+    old_logs = project_root / "logs"
+
+    found = []
+    if old_tasks.exists():
+        found.append(old_tasks)
+    if old_state.exists():
+        found.append(old_state)
+    if old_logs.exists() and old_logs.is_dir():
+        found.append(old_logs)
+
+    if not found:
+        print(f"{config.YELLOW}No old data files found in {project_root}{config.RESET}")
+        print("Nothing to migrate.")
+        return
+
+    if config.TASKS_FILE.exists():
+        print(f"{config.RED}Conflict: {config.TASKS_FILE} already exists{config.RESET}")
+        print("Resolve the conflict manually before migrating.")
+        sys.exit(1)
+
+    config.TLOOP_HOME.mkdir(exist_ok=True)
+    config.LOGS_DIR.mkdir(exist_ok=True)
+    config.ARCHIVE_DIR.mkdir(exist_ok=True)
+
+    if old_tasks.exists():
+        shutil.copy2(old_tasks, config.TASKS_FILE)
+        print(f"  Migrated: tasks.yaml → {config.TASKS_FILE}")
+
+        data = yaml.safe_load(open(old_tasks)) or {}
+        for i, task in enumerate(data.get("tasks", [])):
+            pf = task.get("prompt_file")
+            if pf and not Path(pf).expanduser().is_absolute():
+                print(
+                    f"  {config.YELLOW}Warning: task '{task.get('name', f'Task {i + 1}')}' "
+                    f"has relative prompt_file '{pf}'{config.RESET}"
+                )
+                print(f"    Will resolve from {config.TLOOP_HOME} first, then the task's dir.")
+
+    if old_state.exists():
+        shutil.copy2(old_state, config.STATE_FILE)
+        print(f"  Migrated: .tloop-state.json → {config.STATE_FILE}")
+
+    if old_logs.exists() and old_logs.is_dir():
+        for log_file in old_logs.iterdir():
+            if log_file.is_file():
+                shutil.copy2(log_file, config.LOGS_DIR / log_file.name)
+        print(f"  Migrated: logs/ → {config.LOGS_DIR}/")
+
+    print(f"\n{config.GREEN}Migration complete.{config.RESET}")
+    print(f"Old files still exist in {project_root} — remove them manually when ready.")

tloop_cli-0.4.0/src/cmd_run.py

@@ -0,0 +1,83 @@
+"""tloop run — execute tasks defined in ~/.tloop/tasks.yaml."""
+
+import sys
+
+import config
+from config import ensure_tloop_home, load_config
+from state import load_state, save_state, show_status, archive_completed_tasks
+from task import run_task
+
+
+def add_parser(subparsers):
+    p = subparsers.add_parser("run", help="Run tasks defined in ~/.tloop/tasks.yaml")
+    p.add_argument("--status", "-s", action="store_true", help="Show task status")
+    p.add_argument("--reset", action="store_true", help="Reset all tasks to pending")
+    p.add_argument("--only", type=int, help="Run only task #N (1-based)")
+    p.add_argument("--confirm", "-i", action="store_true", help="Confirm before each task")
+    p.add_argument("--continue", "-c", dest="continue_on_fail", action="store_true",
+                    help="Continue even if a task fails")
+    p.set_defaults(func=handle)
+
+
+def handle(args):
+    ensure_tloop_home()
+
+    cfg = load_config()
+    tasks = cfg.get("tasks", [])
+    defaults = cfg.get("defaults", {})
+
+    if not tasks:
+        print("No tasks defined in tasks.yaml")
+        sys.exit(0)
+
+    state = load_state()
+
+    if args.status:
+        show_status(tasks, state)
+        return
+
+    if args.reset:
+        state = {"tasks": {}, "version": 1}
+        save_state(state)
+        print(f"{config.GREEN}State reset. All tasks are pending.{config.RESET}")
+        return
+
+    if args.only is not None:
+        if args.only < 1 or args.only > len(tasks):
+            print(f"{config.RED}Invalid task number: {args.only}{config.RESET}")
+            sys.exit(1)
+        indices = [args.only - 1]
+    else:
+        indices = list(range(len(tasks)))
+
+    ran_any = False
+    for i in indices:
+        ts = state.get("tasks", {}).get(str(i), {})
+        status = ts.get("status", "pending")
+
+        if status == "done" and args.only is None:
+            print(f"⏭️  Task [{i + 1}] already done, skipping")
+            continue
+
+        if args.confirm:
+            name = tasks[i].get("name", f"Task {i + 1}")
+            try:
+                resp = input(f"\nRun task [{i + 1}] '{name}'? [y/N] ")
+            except (EOFError, KeyboardInterrupt):
+                print("\nAborted.")
+                break
+            if resp.lower() != "y":
+                print("Skipped.")
+                continue
+
+        ran_any = True
+        success = run_task(tasks[i], i, state, defaults)
+        if not success and not args.continue_on_fail:
+            print(f"\n{config.YELLOW}Stopped. Use -c to continue after failures.{config.RESET}")
+            break
+
+    if ran_any:
+        print(f"\n{config.BOLD}--- Final Status ---{config.RESET}")
+        show_status(tasks, state)
+
+    archive_completed_tasks(cfg, state)

tloop_cli-0.4.0/src/config.py

@@ -0,0 +1,69 @@
+"""Configuration constants and helpers for t-loop."""
+
+import sys
+from pathlib import Path
+
+import yaml
+
+TLOOP_HOME = Path.home() / ".tloop"
+TASKS_FILE = TLOOP_HOME / "tasks.yaml"
+STATE_FILE = TLOOP_HOME / "state.json"
+LOGS_DIR = TLOOP_HOME / "logs"
+ARCHIVE_DIR = TLOOP_HOME / "archive"
+
+GREEN = "\033[92m"
+RED = "\033[91m"
+YELLOW = "\033[93m"
+CYAN = "\033[96m"
+BOLD = "\033[1m"
+RESET = "\033[0m"
+
+SAMPLE_TASKS_YAML = """\
+# t-loop tasks.yaml
+# Define your Claude Code automation tasks here.
+#
+# Location: ~/.tloop/tasks.yaml
+#
+# Each task runs "cybervisor run <prompt>" in the specified directory.
+# Completed tasks are automatically archived after each run cycle.
+# View archives with: tloop archive
+#
+# prompt_file paths resolve in this order:
+#   1. Absolute path (after ~ expansion)
+#   2. Relative to ~/.tloop/
+#   3. Relative to the task's dir
+
+defaults:
+  # model: opus
+
+tasks: []
+  # - name: My first task
+  #   dir: ~/projects/my-project
+  #   prompt: |
+  #     Describe what Claude should do here.
+  #
+  # - name: Task with prompt file
+  #   dir: ~/projects/my-project
+  #   prompt_file: ./prompts/my-task.md
+"""
+
+
+def ensure_tloop_home():
+    TLOOP_HOME.mkdir(exist_ok=True)
+    LOGS_DIR.mkdir(exist_ok=True)
+    ARCHIVE_DIR.mkdir(exist_ok=True)
+
+    if not TASKS_FILE.exists():
+        TASKS_FILE.write_text(SAMPLE_TASKS_YAML)
+        print(f"{GREEN}Created {TASKS_FILE}{RESET}")
+        print(f"\nEdit ~/.tloop/tasks.yaml to define your tasks, then run tloop run.")
+        sys.exit(0)
+
+
+def load_config():
+    if not TASKS_FILE.exists():
+        print(f"{RED}Error: {TASKS_FILE} not found{RESET}")
+        print(f"Run tloop run to initialize, then edit tasks.yaml.")
+        sys.exit(1)
+    with open(TASKS_FILE) as f:
+        return yaml.safe_load(f) or {}