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.

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.

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 automatically; only the Markdown body is injected into the agent's system prompt.

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
                                     # truncated (and archived) when the conversation
                                     # approaches this size.
  max_total_tokens: 200000           # Optional. Cap on cumulative billed tokens across all
                                     # LLM calls in one run; the run stops (marked incomplete)
                                     # when reached. Unset means no cap.
  auto_compact: false                # Default. When true, dropped context is summarized with
                                     # an LLM call and injected back instead of a bare hint.
  max_compactions: 3                 # Default. Per-run cap on auto-compact calls. 0 disables.
  findings_ledger: true              # Default. Persist interim findings to a disk ledger and
                                     # merge them back before the final answer, so findings from
                                     # truncated iterations are never lost.
  timeout_secs: 300                  # Default. Max wall-clock time in seconds.
  max_iterations: 10                 # Default. Max agent loop iterations.
  shell_timeout_secs: 120            # Default. Per-command timeout for shell_exec.

  # Optional tool allowlist
  tool_allowlist:                    # Restrict shell commands to these argv prefixes.
    - git status                     # "git status" allows that subcommand tree only.
    - cargo test                     # A bare name (e.g. "git") allows all subcommands.
  shell_env_passthrough: []          # Default. Extra env vars forwarded to shell_exec
                                     # commands (exact names only; secret-looking names
                                     # like *_KEY / *_TOKEN are refused).

  # Safety
  ambiguity_policy: fail_closed      # "fail_closed" or "proceed_with_caution".
  on_incomplete: fail                # "fail" (exit 2, default) or "pass" (continue with
                                     # partial re