Ayni

This repository has moved. Active development now lives in the ayni-oss/ayni. This repository is retained as a historical reference and will no longer receive feature work. Please open issues and contribute changes in the new project.

Ayni is a local quality protocol for repositories that use AI agents. Maintainers commit policy, Ayni runs repository tools in a reproducible managed environment, and agents receive scoped, actionable evidence.

Ayni is intentionally forge-neutral and deterministic. It does not generate probabilistic review commentary; it normalizes real repository-tool outcomes into evidence that humans and AI agents can reproduce.

Documentation: Installation · Quickstart · How Ayni works · Security model

Why

AI agents increase delivery speed, but they also increase change volume beyond what humans can reliably review line by line.

Ayni shifts quality control from "inspect every diff" to "measure local behavior and structural health". Repositories define explicit expectations in .ayni.toml; agents respond to those expectations with measurable repairs.

Ayni does not generate code or replace your test and analysis tools. It orchestrates them, normalizes their output, and turns failures into structured repair targets.

What Ayni Does

• can create or update its marked agent-facing guidance in AGENTS.md with an explicit command
• defines the repository-agent quality contract in .ayni.toml
• models test, coverage, size, complexity, deps, and mutation evidence, with explicit adapter capability tiers
• runs language-specific tooling through adapters in locked managed environments
• writes machine-readable artifacts under .ayni/
• prints terminal or Markdown reports for local workflows and AI repair loops

Install

macOS and Linux

Install the latest published release:

curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/gdurandvadas/ayni/main/install.sh | sh

The installer detects the current platform, installs ayni into ~/.local/bin by default, and requires sha256sum or shasum to verify the release checksum before installation. A piped install is non-interactive and prints the required PATH line when needed; download and run install.sh directly if you want its interactive prompts.

Pin a specific release:

curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/gdurandvadas/ayni/main/install.sh | VERSION=ayni-v0.10.0 sh

Choose a custom install directory:

curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/gdurandvadas/ayni/main/install.sh | INSTALL_DIR="$HOME/bin" sh

For supported targets, direct release downloads, checksum verification, upgrades, and uninstall instructions, see the installation guide.

From source

Build and install directly from this repository:

cargo install --locked --path cli

Quick Start

Ayni keeps the repository's quality policy separate from its execution environment:

.ayni.toml + .ayni.lock / OCI image → check / verify / impact
 policy          exact runtime          measured evidence

Preview a minimal test-only policy before writing anything, create it explicitly, then inspect the validated contract:

ayni init --dry-run
ayni init --write
ayni contract show

For a supported repository, resolve and build the managed environment before running the complete repository contract:

ayni env show
ayni env lock
ayni env build
ayni env doctor
ayni check

Inspect managed-environment storage before reclaiming it. Pruning is a dry run by default; --current explicitly resets the current repository's derived state, which Ayni recreates from the lock on the next managed command:

ayni env storage
ayni env prune
ayni env prune --apply --current

check, verify, and impact run launch managed execution directly. The explicit --host mode is useful for evaluation and compatibility, but its runtime and tool versions are not locked. Supported project shapes and the complete lifecycle are documented in the quickstart and managed environment guide.

Use focused verification for the inner repair loop:

ayni verify test --language rust --package my-crate --name test_filter
ayni verify coverage --language node --root apps/web

Focused evidence is written to .ayni/verify/last/signals.json and never replaces the repository result at .ayni/last/signals.json. Human and Markdown reports omit rerun commands; those commands remain structured finding evidence in the JSON artifact. Print the exact, deduplicated commands explicitly with:

ayni verify list
ayni verify list --artifact .ayni/verify/last/signals.json

Copy these artifact-supplied commands rather than broadening them by hand. Signal availability and selector support are adapter-specific and documented in the capability matrix and adapter guides.

Use impact planning for a conservative change-scoped loop against an explicit Git base:

ayni impact show --base main
ayni impact run --base main

Impact evidence is change-scoped and never claims repository completion; run an unscoped ayni check at the caller's completion boundary. See the impact contract for workspace mapping and uncertainty rules.

Run ayni agents sync explicitly when you want the managed guidance block created or refreshed. It points agents to the repository policy and exact finding commands without replacing repository-specific instructions.

Generate Markdown or current schema-v4 JSON output:

ayni check --output markdown
ayni check --output json

Compare two already-produced complete current-schema artifacts explicitly:

ayni results compare --baseline before.json --candidate after.json

For command details, advanced env shell/env run access, output behavior, and result comparison semantics, see the CLI reference, configuration reference, and conceptual guide.

Signals

Ayni emits a closed signal vocabulary shared across language adapters.

Signal	Purpose
test	Test execution health and failures
coverage	Coverage depth and weak or uncovered areas
size	Module and file growth against line-count budgets
complexity	Function-level complexity against thresholds
deps	Forbidden architectural dependency edges
mutation	Test effectiveness against simulated behavioral change

For the canonical vocabulary and version selection, see docs/product/signals.md; the current self-contained JSON envelope is schema v4. Availability is adapter-specific: see the capability tiers. Historical schemas remain archived but are not part of primary navigation.

Configuration

.ayni.toml is the handoff point between humans and agents: which languages and roots are in scope, which signals run, and which limits define healthy code.

[checks]
test = true
coverage = true
size = true
complexity = true
deps = true
mutation = false

[languages]
enabled = ["rust"]

[rust.size]
"*.rs" = { warn = 400, fail = 700, exclude = ["target/**", ".ayni/**"] }

[rust.complexity]
fn_cyclomatic = { warn = 10, fail = 20 }

For the full configuration reference, see docs/product/config.md.

Size and complexity are maximums: at warn or higher they warn, and at fail or higher they fail. Coverage is a minimum: below warn it warns and below fail it fails. Thus { warn = 400, fail = 700 } warns at 400 lines and fails at 700, while { warn = 80, fail = 70 } warns below 80% coverage and fails below 70%. Warnings remain visible but do not make a row fail.

How It Fits Together

The platform keeps product semantics, language integrations, and CLI behavior separate:

core  <-  adapters/common  <-  adapters/<language>  <-  cli
core  <-  adapters/common  <-  environment          <-  cli

Language adapters own ecosystem-specific discovery, tool invocation, impact mapping, and normalization. Core owns typed product contracts. The environment backend consumes validated locks and preparation plans without interpreting language manifests. The CLI owns orchestration and output.

For layer boundaries and change rules, see ARCHITECTURE.md.

Documentation

• CLI reference
• Configuration reference
• Managed environments
• Security and trust model and vulnerability reporting policy
• Signal contract index and current schema v4
• Adapter capability tiers
• Runtime and setup rules
• Architecture
• Language adapters: Rust, Go, Node, Python, Kotlin

Contributing

Developer workflow, architecture constraints, and repository checks live in CONTRIBUTING.md.

License

Copyright (C) 2026 Gastón Durand Vadas.

Ayni is licensed under the GNU Affero General Public License, version 3 only (AGPL-3.0-only). See LICENSE for the full license text and NOTICE for the repository copyright notice.