AiraCode

Iran-native agentic coding CLI with persistent cognitive memory.

Built for Iranian developers. Works through Iran's internet restrictions — no extra setup needed. Top up your wallet with a domestic Rial card. Persistent memory through CogX so you never re-explain your project twice.

curl -fsSL https://airacode.ir/install.sh | bash
aira login
aira

Why AiraCode

• 🇮🇷 Works through Iran's internet restrictions. The CLI talks to app.airachat.ir, an in-country edge that handles routing to global model providers on your behalf. When the wider network is slow or blocked, AiraCode still answers.
• 🧠 Persistent cognitive memory. Aira remembers your projects, decisions, codebase quirks across sessions, devices, and weeks. Walk away for a month, come back — she already knows. No flag to flip, no opt-in.
• 💵 Rial payment, AiraCredit unit. Top up your AiraChat wallet from a domestic Shetab card. Spend in AiraCredits (AC) — Aira's transparent in-house unit. Every turn shows the AC cost.
• 🎯 Task-based model selection. Pick by what you're doing — Code, Deep Think, Docs, Fast — not by aira-gpt5 or aira-opus. Underlying provider is hidden by default.
• 💬 Developer-native CLI. Works cleanly in English terminals, supports AiraChat identity, and keeps project memory available across sessions.
• 🌐 Sessions in the browser too. Long-running agent runs at app.airachat.ir/airacode so your terminal stays free.

Install

One-liner:

curl -fsSL https://airacode.ir/install.sh | bash

Auto-detects macOS/Linux shells and installs a standalone AiraCode binary by default, with no Node, npm, or Bun runtime required. If the binary path is unavailable, or you request --bun / --version, the installer falls back to Bun plus the npm package. On Windows, use the native PowerShell installer:

irm https://airacode.ir/install.ps1 | iex

Or with npm directly if Bun is already on PATH:

npm install -g @airachat/airacode

The npm package's aira binary is Bun-targeted. For Node-only machines, use the one-line installer above so you get the standalone binary.

Verify:

aira --version
# → 0.1.x (AiraCode)
aira update --dry-run  # check the update path without changing files

First-run

aira login           # opens app.airachat.ir OAuth in your browser
aira                 # start an interactive session

The first aira login connects your AiraChat account — that's your billing identity, Rial wallet, and persistent memory. Already an airachat.ir user? You're already signed up.

Everyday use

aira                                  # interactive REPL
aira -p "explain this codebase"       # one-shot prompt
aira --model aira-deep -p "refactor"  # pick a heavier level for one turn
aira balance                          # AC balance + plan + budget
aira credits 7                        # 7-day AC usage breakdown
aira topup                            # open the topup page

Inside the REPL:

/balance          # AC balance + plan
/credits 30       # 30-day usage
/topup            # open top-up
/model            # choose a model lane
/memory           # project memory

Aira Levels (task-based model selection)

--model <alias> accepts any of these task-based levels. Pick by what you're doing, not by which underlying model. AiraCode smart-routes each aira-* lane behind the scenes.

| Level | Badge | Best for | |---|---|---| | aira-balanced (default) | Recommended | day-to-day coding, balanced quality / speed / cost | | aira-deep | Pro | complex reasoning, architecture, strategic planning | | aira-code | Pro | refactoring, debugging, agentic tool use | | aira-docs | Pro | long context, PDFs, image / file analysis | | aira-fast | Fast | quick answers, titles, summaries, intent detection | | aira-lite | Economy | classification, extraction, high-volume light work | | aira-max | Flagship | top quality, multi-pass reasoning, deepest recall |

Each level bundles model + recall depth + thinking budget + chat context — not just a model choice. Custom dial available in app.airachat.ir/settings/level.

Full catalog inside any session: /model. Power users can also pin any live OpenRouter provider/model id from the gateway catalog, or type one directly.

Useful catalog filters:

/model list --code kimi      # coding-tuned Kimi options
/model list --free           # currently free OpenRouter models
/model list --vision --long  # multimodal long-context models
/model list --cheap qwen     # low-cost Qwen choices
/model list --all            # show the full live catalog

Import Settings

Moving from another agent CLI should not mean rebuilding your setup by hand. AiraCode can import compatible settings, MCP servers, memory files, commands, agents, skills, rules, and trusted projects:

/import-settings --dry-run      # preview everything first
/import-settings all            # import Claude Code + Codex compatible settings
/import-settings codex          # import only Codex config
/import-settings claude         # import only Claude Code config

External model nicknames are converted to Aira-native lanes where possible: Opus-class names become aira-opus, Sonnet-class names become aira-sonnet, coding models like Kimi/Qwen become aira-code, and exact OpenRouter provider/model IDs stay direct. MCP OAuth client IDs and callback metadata are portable; client secrets are never copied. Dangerous permission defaults are skipped unless you explicitly pass --include-dangerous.

Agent quality gates

AiraCode ships with a real temp-repo benchmark harness. Each task creates a small repository, asks the CLI to change files, then verifies the result with local tests. The gates are meant for release checks and regression hunting, not synthetic prompt demos.

cd apps/airacode

# No model spend: validates every benchmark fixture, scope audit, and budget/check logic.
bun run bench:agents:offline

# No model spend: validates that known-bad fixtures are rejected by every
# verifier, and that unexpected stray edits are rejected by the scope auditor.
bun run bench:agents:verifiers

# No model spend: validates UI fixtures in a real browser when Playwright is
# available to the benchmark harness.
bun run bench:agents:browser

# No model spend: validates browser-only negative controls. These start from
# oracle-good UI and inject near-miss runtime bugs that static checks miss.
bun run bench:agents:verifiers:browser

# Live Aira run across all release fixtures.
AIRA_BENCH_BIN=aira AIRA_BENCH_MODEL=aira-code bun run bench:agents:aira

# Live Aira UI run: page/dashboard tasks must render in Chrome and pass runtime
# interaction checks, not only static file checks.
AIRA_BENCH_BIN=aira AIRA_BENCH_MODEL=aira-code bun run bench:agents:aira-browser

# Live user-facing default path: normal `aira -p` with no forced --tools.
bun run bench:agents:aira-default

# Optional side-by-side invoice fixture against Codex, with Aira required to
# be fastest, lowest-token, and at least 10x lower-token on successful runs.
AIRA_BENCH_BIN=aira AIRA_BENCH_MODEL=aira-code bun run bench:agents:codex

# Optional competitor run across invoice + static page, with unavailable
# competitors classified separately from functional failures.
AIRA_BENCH_BIN=aira AIRA_BENCH_MODEL=aira-code bun run bench:agents:compare

# Optional arena verdict run across invoice + page + dashboard. It writes a
# compact arena JSON artifact for Aira-vs-competitor review.
AIRA_BENCH_BIN=aira AIRA_BENCH_MODEL=aira-code bun run bench:agents:arena

# Heavier proof run: three trials per task, aggregate Aira-vs-competitor gates.
AIRA_BENCH_BIN=aira AIRA_BENCH_MODEL=aira-code bun run bench:agents:compare:repeat

The full Aira gate covers invoice math, async cache semantics, CLI parsing, authenticated API routing, static page editing, dashboard UI, and audited subagent delegation. Subagent fixtures are checked from stream-json events: the benchmark fails unless the parent uses Agent and the child uses Read. Each result now gets a failure class, quality score, normalized efficiency score, total score, changed-file count, diff-line count, task winners, per-task/per-agent aggregates, and an overall leaderboard. Use --repeat <n> when a single run is too noisy; Aira comparison gates evaluate aggregate pass rate, average total score, seconds/pass, and tokens/pass per task. Use --leaderboard-json <path> to save a small machine-readable leaderboard next to the full --out result file.

Arena verdicts turn the leaderboard into an explicit competitive claim. Pass --arena to print an Arena Verdict, and --arena-json <path> to write a compact artifact with per-task rankings. The weighted arena score prioritizes pass rate and total score, then token use, speed, edit-scope pass rate, and cost. --require-aira-arena-win and --min-aira-arena-win-rate <ratio> let CI fail when Aira does not actually beat selected competitors. --from-results can replay arena scoring from a saved benchmark JSON without rerunning agents.

Edit hygiene is checked after every run. The harness initializes each fixture as a temporary git repo, records a baseline commit, then audits the final diff against the task's expected changed-file list. A run that passes tests but touches an unrelated config, lockfile, fixture, or generated artifact fails as edit_scope_failed. Reports include scope, changed, and diff columns; --max-changed-files and --max-diff-lines let release scripts fail oversized fixes even when the file set is technically allowed.

Evidence bundles make benchmark claims inspectable after the temp repositories are deleted. When --out /tmp/bench.json is used, the harness automatically writes /tmp/bench-evidence/<agent-task>/ with patch.diff, changed-files.txt, unexpected-files.txt, git status/name-only/numstat, full agent stdout/stderr, verifier stdout/stderr, final.txt, and summary.json. Use --evidence-dir <path> when CI should publish artifacts to a fixed directory. Result rows include evidenceDir and evidenceFiles, so a leaderboard entry can be traced back to the exact patch that passed.

Responsiveness is measured separately from final success. Agent runs use a silence watchdog (--silence-timeout-ms, defaulting to the lower of 120s or the outer timeout) so a stalled CLI is classified as silence_timeout instead of a generic failure. The report also records time to first and last observable output, and --max-first-output-ms can fail a release when Aira or a competitor sits silent too long before streaming progress.

UI quality can be verified in a real browser with --browser-check. The page fixture renders at desktop and mobile widths, checks visible install CTAs, and fails on console/page errors or horizontal overflow. The dashboard fixture also loads linked CSS/JS, exercises the queue search/status filters, verifies aria-live count updates, and checks the mobile layout. The browser check is explicit so the default package stays light; when enabled, the harness resolves Playwright from its own environment and can use system Chrome via PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH.

Verifier integrity is checked with --self-test-verifiers. The no-browser mode runs every task verifier against untouched broken fixtures and passes only when each verifier rejects the bad state. It also runs an edit-scope negative control per task by applying the oracle fix, adding an unexpected file, and requiring the scope auditor to reject it. With --browser-check, page and dashboard use browser-only near misses: an overflow page and a dashboard whose static code still looks valid but whose filters no longer change rendered rows.

Saved benchmark JSON can be replayed against stricter budgets without spending tokens again:

node scripts/agent-bench.mjs \
  --from-results /tmp/airacode-agent-bench-aira-full-preset.json \
  --budget-agents aira \
  --max-tokens-per-task 30000 \
  --max-total-tokens 100000 \
  --max-changed-files 3 \
  --max-diff-lines 300 \
  --min-score 95 \
  --leaderboard-json /tmp/airacode-agent-bench-leaderboard.json

Strict replay with aggregate Aira gates:

node scripts/agent-bench.mjs \
  --from-results /tmp/airacode-agent-bench-compare.json \
  --budget-agents aira \
  --require-aira-best-total \
  --require-aira-fastest \
  --require-aira-lowest-tokens \
  --min-aira-pass-rate 1 \
  --min-aira-token-win-ratio 10

Strict replay with arena gates:

node scripts/agent-bench.mjs \
  --from-results /tmp/airacode-agent-bench-compare.json \
  --arena \
  --require-aira-arena-win \
  --min-aira-arena-win-rate 1 \
  --arena-json /tmp/airacode-agent-bench-arena.json

Baseline regression replay:

node scripts/agent-bench.mjs \
  --from-results /tmp/airacode-agent-bench-current.json \
  --baseline-results /tmp/airacode-agent-bench-baseline-leaderboard.json \
  --baseline-agents aira \
  --max-token-regression-ratio 1.10 \
  --max-speed-regression-ratio 1.25 \
  --min-score-delta -5 \
  --min-pass-rate-delta 0

When --baseline-results is set, the default guard already uses those values: no pass-rate drop, at most a 5 point average-total drop, at most 10% token/pass regression, and at most 25% seconds/pass regression.

Latest local proof on this checkout with built 0.1.97: verifier self-test passed 7/7 known-bad fixtures and 7/7 edit-scope negative controls; browser verifier self-test passed page/dashboard 2/2 with browser-only negative controls and scope negative controls. The full offline oracle preset passed 7/7 fixtures with total score 100, 2,800 fixture tokens, zero model cost, scope=yes on every row, max changed files 3, and max diff 168 lines under the shipped --max-changed-files 3 --max-diff-lines 300 budgets. Browser oracle passed page/dashboard 2/2 in Chrome with total score 100, scope=yes, max changed files 3, and max diff 168 lines. The offline --out run also wrote per-fixture evidence bundles with patch, git, verifier, agent-output, final-text, and summary artifacts, and the full JSON includes arena plus aggregate edit hygiene fields. Arena replay positive control passed strict --require-aira-arena-win at 7/7; the negative control without an Aira row exited 1 with arena verdict missing-aira. Live installed 0.1.97 focused invoice proof passed with scope=yes, changed files 1, diff 10, no timeout or silence timeout, first output at 23.1s, 7,695 tokens, $0.049295, and the full 14-file evidence bundle. Live installed Aira browser proof passed page/dashboard 2/2: page at 4,522 tokens / 29.4s / first output 2.2s, dashboard at 11,097 tokens / 69.5s / first output 2.1s, both with browser-rendered runtime verification and no silence timeout. The synthetic silent runner is classified as silence_timeout in about 0.3s with silence=yes, and --max-first-output-ms fails it as an observable-output budget breach. Repeat-mode oracle passed invoice/page 4/4 over --repeat 2 with aggregate task-agent rows. Focused live repeat evidence against the rebuilt 0.1.90 CLI passed invoice 2/2 with average total score 98.5, 2,132 tokens/pass, 18.3s/pass, and $0.022047/pass. Targeted live Aira runs also passed invoice at 1,948 tokens / 16.6s / $0.018960, static page at 2,043 tokens / 21.6s / $0.020595, and audited subagent delegation at 9,798 tokens / 39.3s / $0.082745. Baseline validation passed when replaying the invoice comparison against itself with same-or-better gates, and failed clearly under an intentionally impossible token regression threshold.

Latest same-machine competitor proof on invoice and static page: Aira, Codex, and Claude Code all passed the same local verifiers. On invoice, Aira used 1,948 tokens in 16.6s; Codex used 201,204 tokens in 44.6s; Claude Code used 134,356 tokens in 34.7s. On static page, Aira used 2,043 tokens in 21.6s; Codex used 165,117 tokens in 52.5s; Claude Code used 135,293 tokens in 24.6s. Aira won fastest, lowest-token, and lowest reported cost in both targeted comparisons.

BYOK — Bring Your Own Key

If you'd rather pay inference cost directly to your own provider account and use AiraCode purely as the memory + cognition layer:

export OPENROUTER_API_KEY="sk-or-v1-..."       # or AIRA_BYOK_OPENAI / AIRA_BYOK_ANTHROPIC
aira                                           # AiraCode now routes inference via your key

Only memory operations (recall, save) consume AiraCredits. Token costs go directly to the provider. Configure persistent BYOK in app.airachat.ir/settings/level.

Pricing

Pay in AiraCredits (AC) — Aira's in-house unit, topped up with Rial via Shetab card (Zibal, IDPay, ZarinPal).

Plans:

• Free — memory plus light thinking, with a limited daily quota.
• Doost — monthly Rial subscription, monthly AC grant, soft unlimited usage, voice and TTS.
• Rafiq — Rial subscription, larger monthly AC grant, unlimited messages, deeper memory, priority support.
• Yaar — high-volume monthly AC grant, Aira Max access, and experimental features.
• PAYG — no subscription; usage spends only AC from your wallet.

Top-up packs: 100K / 500K / 1M / 5M / 10M toman. They convert to AC and lock the exchange rate at purchase time.

Live pricing + AC quotes: app.airachat.ir/settings/billing.

Docs & support

• Getting started: airacode.ir/docs/getting-started
• Memory (CogX): airacode.ir/docs/memory
• Aira models: airacode.ir/docs/models
• Gateway / BYOK: airacode.ir/docs/gateway
• Connecting MCP servers: airacode.ir/docs/mcp
• OAuth / API keys: app.airachat.ir/developer/keys
• Web sessions: app.airachat.ir/airacode
• Developer console: app.airachat.ir/developer
• Issues: github.com/airachat/airacode/issues
• Email: [email protected]

License

Apache 2.0. AiraCode is a substantially-modified Iranian product. Full attribution in LICENSE.