AIOS Forge

Lightweight AI agent framework for software projects.

Requirements

Core

| Requirement | Version | Notes | |-------------|---------|-------| | Node.js | ≥ 18.0.0 | Required by the CLI itself | | An AI CLI tool | — | At least one: Claude Code, Codex CLI, Gemini CLI, or OpenCode |

Optional — by feature

| Feature | Extra requirement | |---------|-------------------| | scan:project (brownfield scanner) | aios-forge-models.json with a cheap LLM API key (DeepSeek, OpenAI, Gemini, Groq, Together, Mistral, or Anthropic) | | qa:run / qa:scan (browser QA) | Playwright + Chromium: npm install -g playwright && npx playwright install chromium | | mcp:init / mcp:doctor | MCP-compatible tool (Claude Code, Gemini CLI, OpenCode, or Codex CLI with MCP support) | | Web3 support | Project must use a supported chain toolchain (Hardhat, Foundry, Anchor, etc.) |

Install

npx aios-forge init my-project
# or
npx aios-forge install

Legacy projects and custom stacks

You can run AIOS Forge on existing/legacy projects (not only new projects).

# inside an existing project
npx aios-forge install .
aios-forge setup:context . --defaults --framework="CodeIgniter 3" --backend="CodeIgniter 3" --database="MySQL"

# generate discovery.md + skeleton-system.md using a cheap LLM (saves tokens in your AI session)
# requires aios-forge-models.json with your API key
aios-forge scan:project

If your stack is not listed in menus, use free-text values via --framework, --backend, --frontend, --database, --auth, and --uiux.

Commands

Setup and install

• aios-forge init <project-name> [--lang=en|pt-BR|es|fr] [--tool=codex|claude|gemini|opencode]
• aios-forge install [path] [--lang=en|pt-BR|es|fr] [--tool=codex|claude|gemini|opencode]
• aios-forge update [path] [--lang=en|pt-BR|es|fr]
• aios-forge info [path] [--json]
• aios-forge doctor [path] [--fix] [--dry-run] [--json]
• aios-forge setup:context [path] [--defaults] [--framework=<name>] [--lang=en|pt-BR|es|fr]
• aios-forge context:validate [path] [--json]
• aios-forge scan:project [path] [--provider=<name>] [--dry-run] [--json]

Agents

• aios-forge agents
• aios-forge agent:prompt <agent> [--tool=codex|claude|gemini|opencode]
• aios-forge workflow:plan [path] [--classification=MICRO|SMALL|MEDIUM] [--json]

Locale

• aios-forge i18n:add <locale>
• aios-forge locale:apply [path] [--lang=en|pt-BR|es|fr]

Parallel orchestration

• aios-forge parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json]
• aios-forge parallel:assign [path] [--source=auto|prd|architecture|discovery|<file>] [--workers=2..6] [--force] [--dry-run] [--json]
• aios-forge parallel:status [path] [--json]
• aios-forge parallel:doctor [path] [--workers=2..6] [--fix] [--force] [--dry-run] [--json]

MCP

• aios-forge mcp:init [path] [--tool=claude|codex|gemini|opencode] [--dry-run] [--json]
• aios-forge mcp:doctor [path] [--strict-env] [--json]

Browser QA (Playwright)

• aios-forge qa:init [path] [--url=<app-url>] [--dry-run] [--json]
• aios-forge qa:doctor [path] [--json]
• aios-forge qa:run [path] [--url=<app-url>] [--persona=naive|hacker|power|mobile] [--headed] [--html] [--json]
• aios-forge qa:scan [path] [--url=<app-url>] [--depth=3] [--max-pages=50] [--headed] [--html] [--json]
• aios-forge qa:report [path] [--html] [--json]

Testing and validation (CI / contributors)

• aios-forge test:smoke [workspace-path] [--lang=en|pt-BR|es|fr] [--web3=ethereum|solana|cardano] [--profile=standard|mixed|parallel] [--keep] [--json]
• aios-forge test:package [source-path] [--keep] [--dry-run] [--json]

Agent usage helper

If your AI CLI does not show a visual agent picker, these commands let you interact with agents directly from the terminal. See the CLI reference for full docs on each.

Discover agents

• aios-forge agents — list all agents and their paths
• aios-forge agent:prompt setup --tool=codex — get activation prompt for any agent
• aios-forge workflow:plan --classification=SMALL — see the recommended agent sequence

Setup and locale

• aios-forge init my-project --lang=pt-BR --tool=codex
• aios-forge install --lang=es --tool=claude
• aios-forge update --lang=fr
• aios-forge locale:apply --lang=pt-BR

Maintenance

• aios-forge doctor --fix — restore any missing managed files

Parallel orchestration

• aios-forge parallel:init --workers=3
• aios-forge parallel:assign --source=architecture --workers=3
• aios-forge parallel:status
• aios-forge parallel:doctor --fix --dry-run

MCP

• aios-forge mcp:init --dry-run
• aios-forge mcp:doctor --strict-env

Browser QA

• aios-forge qa:init --url=http://localhost:3000
• aios-forge qa:doctor
• aios-forge qa:run --persona=hacker
• aios-forge qa:run --html — visual HTML report in reports/
• aios-forge qa:scan --depth=2 --max-pages=30
• aios-forge qa:report --html — retroactive HTML from last run
• aios-forge qa:report

Integration tests (CI)

• aios-forge test:smoke --lang=pt-BR
• aios-forge test:smoke --web3=ethereum
• aios-forge test:smoke --profile=parallel
• aios-forge test:package --dry-run

Default planning includes @product → @ux-ui for SMALL/MEDIUM projects.

JSON output for CI

Use --json on selected commands. See JSON schemas for output contracts.

• aios-forge init <project-name> --json
• aios-forge install [path] --json
• aios-forge update [path] --json
• aios-forge agents [path] --json
• aios-forge agent:prompt <agent> [path] --json
• aios-forge locale:apply [path] --json
• aios-forge setup:context [path] --defaults --json
• aios-forge i18n:add <locale> --dry-run --json
• aios-forge info --json
• aios-forge doctor --json
• aios-forge context:validate --json
• aios-forge test:smoke --json
• aios-forge parallel:init --json
• aios-forge parallel:assign --json
• aios-forge parallel:status --json
• aios-forge parallel:doctor --json
• aios-forge mcp:doctor --json
• aios-forge qa:run --json
• aios-forge qa:scan --json
• aios-forge qa:doctor --json
• aios-forge qa:report --json
• aios-forge scan:project --json

i18n

CLI localization is supported with:

• --locale=<code>
• AIOS_LITE_LOCALE=<code>

Built-in locales: en, pt-BR, es, fr. Default locale is en. pt, pt_br, and pt-BR resolve to the same Portuguese dictionary. es-* resolves to es, and fr-* resolves to fr. Localized agent packs are built-in for en, pt-BR, es, and fr.

Generate a new locale scaffold:

aios-forge i18n:add fr

Multi-IDE support

• Claude Code (CLAUDE.md)
• Codex CLI (AGENTS.md)
• Gemini CLI (.gemini/GEMINI.md)
• OpenCode (OPENCODE.md)

Web3 support

See the Web3 guide for the full reference.

• project_type=dapp is supported in context validation and setup.
• Framework detection now includes:
  • Ethereum: Hardhat, Foundry, Truffle
  • Solana: Anchor, Solana Web3
  • Cardano: Cardano (Aiken/Cardano SDK signals)
• setup:context supports Web3 fields:
  • --web3-enabled=true|false
  • --web3-networks=ethereum,solana
  • --contract-framework=Hardhat
  • --wallet-provider=wagmi
  • --indexer=The Graph
  • --rpc-provider=Alchemy

Docs

CLI reference

• CLI reference — init, install, update, info, doctor, setup:context, context:validate, agents, agent:prompt, workflow:plan, test:smoke, test:package

Feature guides

• i18n guide — i18n:add, locale:apply, locale resolution
• Parallel orchestration — parallel:init, parallel:assign, parallel:status, parallel:doctor
• MCP guide — mcp:init, mcp:doctor
• Browser QA guide — qa:init, qa:doctor, qa:run, qa:scan, qa:report
• Web3 guide — project_type=dapp, framework detection, Web3 context fields
• JSON schemas — --json output contracts for all commands

Release (internal)

• Release guide
• Release flow
• Release notes template

Portuguese guides

• Início rápido
• Guia de agentes
• Squad e Genoma
• Cenários de uso
• Clientes AI
• Guia do engenheiro

MCP bootstrap

Generate a local MCP server recommendation file from project.context.md:

aios-forge mcp:init
aios-forge mcp:init --dry-run
aios-forge mcp:init --tool=codex
aios-forge mcp:doctor
aios-forge mcp:doctor --strict-env

mcp:init generates:

• .aios-forge/mcp/servers.local.json (project MCP plan)
• .aios-forge/mcp/presets/<tool>.json (tool-specific preset templates)
• Context7/Database presets in remote-endpoint mode (mcp-remote) using:
  • CONTEXT7_MCP_URL
  • DATABASE_MCP_URL (when database MCP is enabled)

mcp:doctor validates:

• core MCP servers (filesystem, context7)
• preset coverage
• required env vars from enabled servers
• context compatibility for database and Web3 (chain-rpc)

License

MIT