t-loop
自动化 Claude Code 任务运行器。用 YAML 定义任务,t-loop 按顺序执行,自带 git 安全保护。
安装
pip install tloop-cli # 从 PyPI 安装
pip install -e . # 本地开发安装
需要 Python >=3.9,唯一外部依赖:pyyaml。
快速开始
# 首次运行会创建 ~/.tloop/tasks.yaml 示例配置
tloop run
# 编辑任务后运行
tloop edit
tloop run
任务配置
编辑 ~/.tloop/tasks.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(跳过分支) |
use |
任务执行器:cybervisor(默认,多阶段复杂任务)或 claude(定向任务,支持循环) |
max_rounds |
use: claude 时生效,最大迭代次数(默认 5);到达上限前未收到 <promise>COMPLETE</promise> 信号则任务失败 |
用法
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 edit ~/proj/xxx # 快速添加一条完整任务(含 dir/branch/use/max_rounds),再打开编辑器
tloop archive # 列出归档记录
tloop archive --latest # 显示最近一次归档详情
tloop migrate # 迁移旧的项目本地数据到 ~/.tloop/
执行器
t-loop 支持两种任务执行器,通过 use 字段选择:
| 执行器 | 说明 | 适用场景 |
|---|---|---|
cybervisor |
默认,执行 cybervisor run,适合复杂多阶段任务 |
大型重构、多步骤分析 |
claude |
执行 claude -p --dangerously-skip-permissions,支持循环迭代 |
定向 bug 修复、明确目标的任务 |
ClaudeRunner 循环机制
use: claude 时,任务以多轮迭代方式执行:
- 每轮启动一次
claude -p --dangerously-skip-permissions,传入 prompt - 如果输出包含
<promise>COMPLETE</promise>,立即结束并标记成功 - 否则等待 2 秒,继续下一轮,直到达到
max_rounds(默认 5) max_rounds用尽仍未检测到完成信号,任务标记失败
使用示例:
tasks:
- name: 修复空指针 bug
dir: ~/proj
use: claude
max_rounds: 3
prompt_file: bugfix.md
在 prompt 文件中加入 <promise>COMPLETE</promise> 即可让 Claude 主动退出循环。
工作原理
每个任务的执行流程:
- 自动提交 — 如果工作目录有未提交的更改,t-loop 会用 Claude 先提交暂存区内容,再提交剩余更改。敏感文件(.env、密钥等)会被排除。
- 创建分支 — 创建任务分支(默认
feature-YYYYMMDD-NNN)隔离更改。 - 执行任务 — 在目标目录运行
cybervisor run <prompt>。 - 归档 — 已完成的任务移至
~/.tloop/archive/,并从tasks.yaml中移除。
文件位置
~/.tloop/
├── tasks.yaml # 任务定义
├── state.json # 运行时状态(任务状态)
├── logs/ # 执行日志
└── archive/ # 已完成任务的归档
开发
pip install -e .
python -m pytest test/ -v
许可证
MIT
Metadata
Release files for tloop-cli 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tloop_cli-1.0.0.tar.gz | 24.5 kB | Without provenance | Details for tloop_cli-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tloop_cli-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for tloop_cli-1.0.0-py3-none-any.whl |
Total release size: 43.7 kB
Release files / tloop_cli-1.0.0.tar.gz
| Download URL | tloop_cli-1.0.0.tar.gz |
|---|---|
| Size | 24.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
64ff62351c06a4e4df995ead6243430f7b3eedbb9bc1a4b78d5322c0ec425fb2
|
|
BLAKE2b-256 checksum How to use checksums |
ffda24dd01a4b62ddbba70a5b047c907fe468df2dbb83dbb4aafd06ca090ab59
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / tloop_cli-1.0.0-py3-none-any.whl
| Download URL | tloop_cli-1.0.0-py3-none-any.whl |
|---|---|
| Size | 19.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a206ec19860cc5c4ebf428054d766566f42c12e7c435d447a67fde0beac82132
|
|
BLAKE2b-256 checksum How to use checksums |
5bbc8b956648b04bd1c3f3c7be708c402e308524cbba8ca17ef62d283d82a7ba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for tloop-cli 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.