Guide AI coding agents with tailored software development best practices.

Actual CLI establishes guardrails for AI coding agents by delivering Architecture Decision Records (ADRs) — short documents that capture software development best practices and design guidance — tailored to your specific codebase using an LLM. This catches edge cases and guides agents toward correct decisions. The output is written to context files (CLAUDE.md, AGENTS.md, or Cursor rules) that agents read automatically.

The Actual API is free and requires no account or API key. You only need a configured AI runner (Claude Code, Anthropic API, OpenAI API, etc.) for the tailoring step.

1. Install

   brew install actual-software/actual/actual

2. Configure a runner (Claude Code CLI is the default)

   claude auth login

3. Run it from inside any git repo

   actual adr-bot

This analyzes your repo, fetches relevant ADRs, tailors them to your codebase, and writes the result to CLAUDE.md.

Preview before writing anything:

actual adr-bot --dry-run

brew install actual-software/actual/actual

npm install -g @actualai/actual

Download the binary for your platform from the releases repository (binaries are published separately from source), then:

chmod +x ./actual
sudo mv ./actual /usr/local/bin/actual

macOS only: remove quarantine before running:

xattr -dr com.apple.quarantine /usr/local/bin/actual

Requires a C compiler (for tree-sitter native dependencies):

# macOS: Xcode command-line tools (usually already installed)
xcode-select --install

# Debian/Ubuntu:
sudo apt-get install build-essential

# Then:
cargo install --git https://github.com/actual-software/actual-cli.git

Windows is not currently supported.

By default, actual adr-bot writes to CLAUDE.md. Content is wrapped in managed markers so future runs update cleanly without touching anything you've written yourself.

actual adr-bot        # analyze repo & write AI context files
actual status         # check output file state (managed markers, staleness)
actual auth           # verify authentication
actual config show    # view current configuration
actual config set     # set a config value
actual config path    # print config file location
actual runners        # list available AI backend runners
actual models         # list known model names grouped by runner
actual cache clear    # clear local analysis and tailoring caches

Config lives at ~/.actualai/actual/config.yaml and is created automatically on first run. See Getting Started for the full reference including all flags, runner configuration, and environment variable overrides.

Actual CLI collects minimal, anonymous telemetry (aggregate counters only — no PII, source code, or file paths). Telemetry can be disabled via environment variable (ACTUAL_NO_TELEMETRY=1), config file, or compile-time feature flag. See PRIVACY.md for full details.

Contributions are welcome. See CONTRIBUTING.md for build instructions, coding standards, and PR guidelines.

To report a vulnerability, do not open a public issue. See SECURITY.md for responsible disclosure instructions.

MIT