Clausura

CI-native agent CLI tool for deterministic pipeline gating.

Overview

Clausura is a platform-agnostic agent CLI tool built for CI/CD pipelines. It runs bounded LLM agent tasks against your codebase, extracts structured findings, evaluates them against deterministic gating rules, and exits with a clear pass/fail signal. No mid-process questions, no human in the loop.

Key philosophy: closed-loop execution with deterministic gating. The LLM finds issues. The rule engine decides if they matter. Your pipeline gets a binary answer.

Clausura vs. generic agent harnesses

General-purpose agent harnesses (DeepSeek Harness, Claude Code, Codex and similar) optimize for open-ended interactive work: flexible plugin stacks, long-lived sessions, sub-agent orchestration, and human-in-the-loop approvals. They deliberately leave verdicts, structured output and resource bounds to the caller — their "success" means "the agent stopped", not "the task is done".

Clausura occupies the other side of the same problem and is deliberately not a general harness:

If you are building an interactive coding agent, use a generic harness. If you need a deterministic gate in CI — an agent that must finish within bounds and produce a pass/fail answer a pipeline can trust — that is what Clausura is for.

Use cases

• Code review gating -- flag violations in pull requests before merge
• Cross-repo consistency checks -- enforce conventions across multiple repositories
• Smart gating -- fail the pipeline only when findings exceed configured thresholds
• i18n extraction and translation -- scan source files and validate locale coverage
• Architecture compliance -- verify code structure against project conventions

Installation

Shell script (Linux, macOS, WSL)

curl -fsSL https://raw.githubusercontent.com/liuyanghejerry/Clausura/main/install.sh | bash

The script detects your OS and architecture, downloads the latest release from GitHub, verifies the tarball against the release's checksums.txt (SHA256), and installs it to /usr/local/bin or ~/.local/bin.

Cargo

cargo install clausura-cli

Docker

docker pull ghcr.io/liuyanghejerry/clausura
docker run --rm -v $(pwd):/workspace ghcr.io/liuyanghejerry/clausura run

From source

git clone https://github.com/liuyanghejerry/Clausura.git
cd clausura
cargo build --release --package clausura-cli
# binary at target/release/clausura

Verify

clausura --version
# clausura 1.0.0 (commit: abc1234, built: 2026-05-23)

Supported LLM Providers

Clausura supports three vendor categories out of the box:

1. OpenAI-compatible

Any LLM that exposes an OpenAI-compatible /chat/completions endpoint:

vendor: deepseek   # shorthand
# or full config:
vendor:
  type: openai_compatible
  base_url: "https://api.mistral.ai/v1"

2. Anthropic-compatible

Claude models via Anthropic's native Messages API:

vendor: anthropic
model: claude-sonnet-4-20250514

Uses Anthropic's native Messages API (/v1/messages) with x-api-key auth and anthropic-version: 2023-06-01.

3. Custom

For enterprise-internal LLMs with non-standard authentication:

vendor:
  type: custom
  base_url: "https://llm.internal.company.com/v1"
  auth_header: "X-API-Key"
  api_key_env: "INTERNAL_LLM_KEY"

Uses the OpenAI-compatible API format (/chat/completions) with configurable base URL and auth header. The auth_header defaults to Authorization; the api_key_env defaults to CLAUSURA_API_KEY.

Quick Start

1. Create a configuration file

Create .clausura.yaml (or .clausura.yml) in your project root:

version: "1"
task:
  name: code-review
  model: gpt-4o
  vendor: openai
  prompt_template: "Review the git diff and return findings as JSON."
  token_budget: 16000
  timeout_secs: 120
  ambiguity_policy: fail_closed
  gating:
    - rule: no-critical
      description: Block on any critical error
      min_severity: error
      max_findings: 0
      action: fail
    - rule: warn-on-warnings
      description: Warn on excessive warnings
      min_severity: warning
      max_findings: 10
      action: warn

2. Set your API key

export CLAUSURA_API_KEY=sk-...

The API key is never read from the YAML config file. It must come from this environment variable or the --api-key CLI flag.

3. Run the task

clausura run

4. Validate config without running

clausura run --validate-config
clausura run --dry-run  # show the execution plan

Exit codes

Using Skills

Clausura 1.2.0+ can reuse community skill files (Markdown) as review prompts. Skills answer "what and how to review", while gating rules answer "how many findings is too many" — the two are cleanly separated.

Skills use progressive disclosure: only a catalog (name + one-line description per skill) is inlined into the system prompt. The agent loads a skill's full body on demand via the read_skill tool, which saves token budget for the review itself instead of spending it on instructions up front.

Skill file format

A skill is a Markdown file, optionally with YAML frontmatter:

---
name: security-review
description: 检查 SQL 注入、XSS、硬编码密钥
---

# 安全代码审查

## SQL 注入
- 任何字符串拼接构造的 SQL 查询
- rule_id: `sql-injection`
- severity: `error`

The frontmatter is stripped from the body; name and description feed the catalog. Without frontmatter, the name falls back to the reference's basename and the description to the first body line.

Referencing skills

task:
  skill_prompts:
    # Local file (relative to workspace or absolute)
    - ./skills/security-review.md

    # Named skill (looks in .clausura/skills/<name>/SKILL.md,
    # then ~/.clausura/skills/<name>/SKILL.md)
    - security-review
    - team/vue-best-practices

  # Optional: append your own extra instructions
  prompt_template: |
    另外检查：禁止 console.log

  gating:
    - rule: sql-injection
      max_findings: 0
      action: fail

Installing community skills

# Project-level (only this repo)
mkdir -p .clausura/skills/security-review
cp ~/Downloads/security-review-SKILL.md .clausura/skills/security-review/SKILL.md

# User-level (available to all your projects)
mkdir -p ~/.clausura/skills/team/vue-check
cp ~/Downloads/vue-check-SKILL.md ~/.clausura/skills/team/vue-check/SKILL.md

See examples/ for ready-to-use skill files and a sample configuration.

Configuration Reference

YAML schema

All fields for .clausura.yaml:

version: "1"                         # Required. Schema version.
task:
  name: my-task                      # Required. Task name.

  # LLM provider
  model: gpt-4o                      # Required (or set CLAUSURA_MODEL).
  vendor: openai                     # Shorthand (backward compatible).
  # Or with full config:
  vendor:
    type: openai_compatible          # openai_compatible | anthropic_compatible | custom
    base_url: "https://api.deepseek.com/v1"  # Optional. Override API endpoint.
    auth_header: "X-API-Key"         # Optional. For custom auth (default: Authorization).
    api_key_env: "MY_SECRET_KEY"     # Optional. Env var for API key (default: CLAUSURA_API_KEY).

  # Prompt
  prompt_template: "{{task_description}}"  # Default. The agent's system prompt.
  skill_prompts: []                           # Optional. Reuse community skill files.
                                               # Supports local paths, named references,
                                               # and remote URLs.

  # Limits
  token_budget: 32000                # Default. Context-window budget: older messages are
                                     # trunc