cli README

项目的 README,来自 github.com/taskless/cli。合并为一个 markdown 文件:README.md。

Taskless

Taskless turns the corrections you give your coding agent into rules that run on every change. Correct once. Enforced forever.

What Taskless is

When you correct your coding agent, Taskless captures that correction as a rule: a real file in your repo, enforced by ast-grep, Vale, or a runtime check (which needs an account). The same rules run in your editor, for every agent, and in CI, with one command and one exit code. You can start without an account.

Get started

1. Install the skill. In a repository with a coding agent configured (a .claude/, .cursor/, .opencode/, or .agents/ directory), run the installer:

npx @taskless/cli

It detects your agent tools and installs the Taskless skill into each of them. pnpm dlx, bun x, and yarn dlx work too.

2. Get onboarded. Ask your agent to help you get started with Taskless. It reviews your codebase and history and helps you turn the strongest candidates into rules.

3. Create a rule. Describe it in plain language:

Create a taskless rule that catches direct fetch() calls without error handling.

Rules are authored and validated locally, with no account and no API calls. Your agent tells you before it uses the Taskless service.

4. Check your code. Ask your agent to run taskless check, or run it yourself through the project launcher the installer writes:

./.taskless/bin/cli.mjs check

Matches are reported with file, line, severity, and message. The command exits 1 on error-severity matches, so it drops straight into CI. Ask your agent to "add taskless to CI" to wire it into the CI system you already use.

A free Taskless account adds AI-powered rule generation with validation and test cases, plus a GitHub integration that turns PR comments and issues into rules. It's also what lets runtime rules run; see Privacy and accounts. See the Taskless docs for the full guide, including tips for writing better rules.

Privacy and accounts

Telemetry

The CLI sends anonymous usage events. They hold the CLI version, your OS, the languages your repository uses, counts (rules run, matches found, how long a command took), the GitHub owner name from your git remote, and hashed workspace and repository ids. They never hold your code, your rule content, or what your rules matched.

Any one of these turns telemetry off:

The onboarding report

Onboarding ends by publishing a report: an unlisted page on tskl.es at a random URL. Anyone with the link can read it. It holds your rules, their fixtures, and what they found. A page is a lot easier to read than terminal output, and easy to share with your team.

Before publishing, the CLI scans everything in the report for anything that looks like a secret or contact detail (API keys, tokens, private keys, email addresses, host names, IP addresses, phone numbers) and withholds whatever matches. taskless report --delete <record> takes the page down, where <record> is its file in .taskless/reports/.

Accounts

You can start without an account, and that's the point. The CLI doesn't log in by default, and onboarding never logs in. ast-grep rules, Vale rules, rules written into your own linter, check, CI, and the report all work with no account.

Runtime rules, the ones that look across files, are the exception. A runtime rule is a program that runs with your permissions and lives in your repository, so anyone who can open a pull request can change it. When you're logged in, check hashes each rule file and runs a runtime rule only when the Taskless service confirms it issued that exact file. Logged out, check still runs your ast-grep and Vale rules and skips runtime rules, saying which ones and why.

What's in this repository

This repository is the source for three things that ship together:

  1. The Taskless CLI, published to npm as @taskless/cli.
  2. The Vale platform packages, @taskless/vale-*: the Vale executable for each supported OS and CPU, wrapped in an npm package so the CLI can run it with no download step.
  3. The canonical Taskless skill, the SKILL.md that agents (Claude Code and others) load to work with Taskless, plus the recipes it routes to.

All of them publish from GitHub Actions through npm trusted publishing (OIDC). No npm token is stored anywhere in this repository.

packages/
  cli/                       # @taskless/cli
    src/agent/               # recipes served by `taskless agent <topic>`
  vale-<os>-<cpu>/           # @taskless/vale-* platform packages (six of them)
skills/
  taskless/SKILL.md          # the canonical Taskless skill
.claude-plugin/              # Claude Code Plugin Marketplace manifest
.github/
  scripts/vale-manifest.json # pinned Vale release and its SHA256 digests
  workflows/                 # release, nightly, Vale, and validation pipelines
scripts/                     # version, changelog, and skill-metadata helpers
openspec/                    # specs and in-flight change proposals

1. The Taskless CLI

@taskless/cli creates, checks, and manages Taskless rules in a project, for agents and for people. The installer pins the CLI version in .taskless/taskless.json and writes a launcher, ./.taskless/bin/cli.mjs, that runs exactly that version. Run every command through the launcher. Any other CLI version refuses to run in the project.

See packages/cli/README.md for the full command reference.

Releases

Releases are automated with Changesets:

  1. A pull request that changes the CLI adds a changeset (pnpm changeset).
  2. On merge to main, release-cli-changeset.yml maintains a Version Packages pull request that folds pending changesets into the version and CHANGELOG.md.
  3. Merging that pull request triggers release-cli.yml, which publishes @taskless/cli with provenance over OIDC and tags the released commit (vX.Y.Z).

Tagging started at v0.9.0; earlier releases weren't tagged.

Nightly builds

Everything merged to main publishes as @taskless/cli-nightly, so you can try unreleased changes without waiting for a release:

npx @taskless/cli-nightly@latest --version

The nightly's executable is also taskless, so it replaces the release when installed. Installing both globally collides on that binary, so install one or the other.

See CONTRIBUTING.md for how nightlies are versioned and published, and for how to test against one without disturbing a release you already have installed.

2. The Vale platform packages

Taskless runs prose rules with Vale. The CLI lists one npm package per platform as an optional dependency, and the package manager installs only the one matching the host. Nothing downloads at install time.

Package Platform
@taskless/vale-darwin-arm64 macOS, Apple silicon
@taskless/vale-darwin-x64 macOS, Intel
@taskless/vale-linux-arm64 Linux, 64-bit ARM
@taskless/vale-linux-x64 Linux, x86-64
@taskless/vale-win32-arm64 Windows, 64-bit ARM
@taskless/vale-win32-x64 Windows, x86-64

Each package holds the upstream vale binary, its MIT LICENSE, a README, and package.json. It has no JavaScript and no install script, so it works under package managers that refuse dependency build scripts.

The binaries aren't committed. The pipeline works in two halves:

The Vale packages are versioned outside Changesets, and publishing them changes nothing for a CLI user until the CLI's pins move. Each package's README covers versioning and provenance in detail.

3. The Taskless skill

skills/taskless/SKILL.md is the canonical Taskless agent skill. It's a small router. For any Taskless action (create, improve, or delete a rule, run checks, authenticate, wire CI), it fetches the matching recipe with taskless agent <topic> and follows it. taskless agent with no topic lists every topic.

The recipes themselves live in packages/cli/src/agent/ and are embedded into the CLI bundle at build time, so a recipe always matches the CLI version that serves it.

The skill reaches agents through these channels:

The skill's metadata.version tracks the CLI version. pnpm bump syncs it, and the CLI build fails if the two disagree.

Adding a new topic recipe

Agent-facing instructions are recipes served by the one skill. To add a topic:

  1. Create packages/cli/src/agent/<topic>.md following the template the existing recipes use (Goal / Preconditions / Steps / Input schema / Errors / See Also).
  2. For a topic with a substantively different local-only flow, add <topic>.anonymous.md. The agent command looks up the variant automatically.
  3. Update the topic table in skills/taskless/SKILL.md so agents can discover the new topic.

Local development

See CONTRIBUTING.md for setup, checks, and the pull request process.

The CLI bakes its own invocation string into the skill, command, and recipe content it installs. The build target picks that string through the TASKLESS_BUILD_TARGET env var and Vite define, from the same source files. Each target writes to its own gitignored directory, so the builds never overwrite each other:

Command Output dir Baked invocation Use for
pnpm build dist/ npx @taskless/cli Production / published builds (default).
pnpm build:self dist-self/ node packages/cli/dist-self/index.js Dogfooding in this repo (path is repo-root-relative; run the CLI from the root).

pnpm build:self builds the CLI with the relative invocation and then runs taskless init --no-interactive to install into this repo, so .claude gets real reference stubs that delegate to the canonical .taskless/ content, exactly like any other install.

The self invocation is a local path and must never be published: only pnpm build produces a release artifact. It's also relative to this repo root, so no build target here yields a CLI you can run from another repository. Use a published nightly for that.

Running the local build

The root package.json defines a cli script pointing at ./packages/cli/dist/index.js. That script runs the CLI built from this working tree instead of a published release, which is what AGENTS.md points contributors and agents at while they're working in this repo. Nothing rebuilds dist/ for you, so run pnpm build first when you want current behavior.

License

MIT. See LICENSE. The Vale binaries carry Vale's own MIT license, shipped unmodified in each platform package.

cli (taskless/cli)

正在搜索数据库…

128 ·GitHub
这是什么?Taskless 把你对编码智能体的纠正转化为强制执行的规则:你修正某个问题后,它会在你的仓库中生成一个真正的规则文件,每次改动都会运行该规则,并由 ast-grep、Vale 或运行时检查来校验。
这是命令行工具,还是运行在我的编码智能体内部的东西?两者都是:它以 @taskless/cli npm 包加上一个标准智能体技能(SKILL.md)的形式发布,Claude Code 等智能体会加载该技能。因此同一套规则可以在你的编辑器中为每个智能体运行,也能通过一条命令在 CI 中运行。
我如何安装并开始使用?在已配置编码智能体(.claude/、.cursor/、.opencode/ 或 .agents/)的仓库中,通过 npx、pnpm dlx、bun x 或 yarn dlx 运行安装程序;它会检测你的智能体工具,并将 Taskless 技能安装到每一个工具中。
我需要先配置好编码智能体,这东西才有用吗?是的,Taskless 需要通过你的编码智能体(Claude Code 或类似工具)来运行;安装程序会查找 .claude/、.cursor/、.opencode/ 或 .agents/ 目录,并将技能接入它找到的智能体中。
创建和运行规则需要账号吗?不需要,无需账号即可开始:规则在本地编写和校验,不调用任何 API。免费账号只会解锁一些额外功能,例如基于 AI 生成带测试用例的规则,以及 GitHub PR/Issue 集成。
它支持哪些操作系统?它附带预编译的 Vale 二进制文件,支持 macOS(Apple 芯片和 Intel)、Linux(ARM64 和 x64)以及 Windows(ARM64 和 x64),会作为对应的可选 npm 依赖自动安装。
检查实际如何运行,又会报告什么?运行 taskless check(直接运行或通过已安装的项目启动器运行)会报告匹配项,包括文件、行号、严重级别和消息;遇到 error 级别的匹配时以退出码 1 结束,因此可以直接接入 CI。
正式发布前,我能试用未发布的改动吗?可以,main 分支的每次合并都会发布为 @taskless/cli-nightly,但它的二进制文件同样名为 taskless,因此如果全局同时安装 nightly 版和正式版会发生冲突,你应只选其一。
究竟是哪些底层工具在执行规则?代码模式规则由 ast-grep 执行,文本规则由 Vale 执行,或由运行时检查执行;Taskless 内置了针对各平台的 Vale 二进制文件,因此无需另行下载。
我如何添加新的规则生成方案类型?在 packages/cli/src/agent/ 下新建一个 Markdown 文件,遵循 Goal/Preconditions/Steps/Input schema/Errors/See Also 模板,然后在 skills/taskless/SKILL.md 中列出新主题,以便智能体能够发现它。
作者
taskless
大小
9.5 MB
星标
128
更新
提交Nov 17
时长
8个月
提交 · 90 天