Quickstart

Install

The AFA engine (which provides the afa CLI) is distributed as source under BSL-1.1. Clone the repository and install with Poetry:

git clone https://github.com/undercurrentai/afa.git
cd afa
poetry install

This installs the afa CLI, nine quantitative gates, four analyzers, and the three LLM provider adapters (Anthropic, OpenAI, Google).

Looking for the hosted API instead? The afa-client Python SDK (Apache 2.0) is the right choice if you want to call the hosted AFA API from your own application without running the engine locally.

Set up a provider

AFA needs an LLM API key. Set one of these environment variables:

# Pick one:
export ANTHROPIC_API_KEY="sk-ant-..."    # Anthropic (default)
export OPENAI_API_KEY="sk-..."           # OpenAI
export GOOGLE_API_KEY="AIza..."          # Google Gemini

Run your first analysis

afa analyze src/

AFA parses every function using tree-sitter, then runs four analysis agents (security, performance, maintainability, documentation) against each function.

Output formats

AFA supports three output formats:

# Human-readable table (default)
afa analyze src/

# Machine-readable JSON
afa --format json analyze src/

# SARIF 2.1.0 (for IDE and CI integration)
afa --format sarif analyze src/

Choose a provider

# Use Gemini instead of the default (Anthropic)
afa --provider gemini analyze src/

# Use OpenAI
afa --provider openai analyze src/

Run an enhancement (dry run)

See what AFA would change without actually modifying files:

afa enhance src/ --dry-run

This runs the full enhancement loop -- analyze, generate candidates, evaluate through all nine gates -- but skips the commit step. You'll see the proposed changes and gate results.

Run a real enhancement

When you're ready to let AFA commit improvements:

afa enhance src/

AFA creates enhancement branches prefixed with afa/ using git worktrees. Changes never land directly on your main branch.

Configuration (optional)

Create a .afa.yaml in your project root to customize behavior:

version: "1.0"

model:
  provider: anthropic
  model: claude-sonnet-4-6

analysis:
  languages:
    - python
    - typescript
  exclude:
    - "tests/**"
    - "vendor/**"

enhancement:
  max_candidates: 3
  auto_commit: false
  branch_prefix: "afa/"

See Configuration for the full reference.

Next steps

• CLI Reference -- all commands and flags
• GitHub App -- automated PR checks
• Nine Gates -- understand what AFA checks