JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 1365
  • Score
    100M100P100Q111938F
  • License MIT

AI operating framework for hyper-personalized software.

Package Exports

  • @jaimevalasek/aioson
  • @jaimevalasek/aioson/src/cli.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@jaimevalasek/aioson) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

Agents

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

Parallel orchestration

MCP

Browser QA (Playwright)

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

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

Maintenance

Parallel orchestration

MCP

Browser QA

Integration tests (CI)

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

Release (internal)

Portuguese guides

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