AIOSON

AI operating framework for hyper-personalized software.

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) | aioson-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

npm install -g @jaimevalasek/aioson
# then use:
aioson init my-project

# one-off execution without global install
npx @jaimevalasek/aioson init my-project
# or
npx @jaimevalasek/aioson install

Legacy projects and custom stacks

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

# inside an existing project
npx @jaimevalasek/aioson install .
aioson 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 aioson-models.json with your API key
aioson scan:project

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

The npm package is scoped as @jaimevalasek/aioson, but the installed CLI commands remain aioson and aios.

Commands

Setup and install

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

Agents

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

Tracked live sessions for external AI clients

• aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<agent> [--plan=<file>] [--no-launch]
• aioson runtime:emit [path] --agent=<agent> --type=task_started|task_completed|milestone|correction|block|plan_checkpoint --summary="..."
• aioson live:handoff [path] --agent=<agent> --to=<next-agent> --reason="..."
• aioson live:status [path] [--agent=<agent>] [--watch=2] [--json]
• aioson live:close [path] [--agent=<agent>] [--status=completed|failed] --summary="..."

Locale

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

Parallel orchestration

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

MCP

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

Browser QA (Playwright)

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

Testing and validation (CI / contributors)

• aioson test:smoke [workspace-path] [--lang=en|pt-BR|es|fr] [--web3=ethereum|solana|cardano] [--profile=standard|mixed|parallel] [--keep] [--json]
• aioson 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

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

Tracked live session flow

• aioson live:start . --tool=codex --agent=deyvin --plan=plan.md --no-launch — open a tracked session envelope before the AI client starts working
• aioson runtime:emit . --agent=deyvin --type=task_started --title="Fix stock modal" — mark the start of a visible work slice
• aioson runtime:emit . --agent=deyvin --type=task_completed --summary="Stock modal fixed" --refs="src/app.js,src/styles.css" — register a completed slice
• aioson live:handoff . --agent=deyvin --to=product --reason="Scope needs product decision" — keep the same live session and switch active AIOSON agent
• aioson live:status . --agent=product --watch=2 — monitor status, active agent, plan progress, and process liveness
• aioson live:close . --agent=product --summary="Session closed" — finish the session and generate summary.md

Setup and locale

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

Maintenance

• aioson doctor --fix — restore any missing managed files

Parallel orchestration

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

MCP

• aioson mcp:init --dry-run
• aioson mcp:doctor --strict-env

Browser QA

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

Integration tests (CI)

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

Default planning includes @product → UI/UX (@ux-ui) for SMALL/MEDIUM projects.

JSON output for CI

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

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

aioson 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
• AI clients guide (PT-BR) — tracked usage with Codex, Claude, Gemini, and OpenCode
• Runtime observability (PT-BR) — live:start, runtime:emit, live:handoff, live:status, live:close, and dashboard projections

Release (internal)

• Release guide
• Release flow
• Release notes template

Portuguese guides

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

MCP bootstrap

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

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

mcp:init generates:

• .aioson/mcp/servers.local.json (project MCP plan)
• .aioson/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