agens

A multi-model, multi-modal agent harness built on the GitHub Copilot SDK.

agens generates HTML artifacts (websites, slides, SVG art, 3D scenes, games, word-like docs, mini-applications), renders them with the built-in Playwright MCP server, and runs a self-critique loop using an independent vision model so the artifact actually gets good — not just generated.

Install

One-line installer (handles Node version):

bash install.sh

This downloads a private Node ≥ 24 into ~/.local/node if your system Node is older, then installs the bundled agens-*.tgz globally.

Manual (you already have Node ≥ 24):

npm install -g ./agens-0.4.0.tgz

From npm (when published):

npm install -g agens

Dev mode (working on agens itself):

bash install.sh --link

Usage

agens                              # interactive REPL
agens "build a smiling-sun SVG landing page"
agens --skill three-d-scene "solar system, draggable camera"
agens skills                       # list built-in skills
agens config show                  # see effective config
agens --no-playwright              # disable browser MCP
agens -m gpt-5.2                   # override model for this run

Built-in skills

| Skill | Trigger keywords | | --------------- | ------------------------------------------- | | html-artisan | website, landing, page, app — the umbrella | | slide-deck-pro| slide, deck, pitch, presentation | | three-d-scene | 3d, scene, three.js, WebGL, shader | | game-builder | game, arcade, puzzle, platformer | | gpt-image | image, poster, reference edit, inpaint | | critic | rubric, score, evaluate, feedback |

Skills live in skills/<name>/SKILL.md. Drop a new folder and it's auto-discovered. Set AGENS_SKILLS_DIR=/your/dir to add a second root.

Built-in tools (injected into every session)

• critique — sends prompt + screenshot to an independent judge model (Gemini 3.1 Pro by default), returns structured rubric (rubrics[], overallScore, passed, suggestions[]). Used by the iterate loop.
• a11y_audit — runs axe-core against any rendered URL, returns a list of accessibility violations with selectors and fix hints.
• gpt_image — calls the configured Images API directly, writes PNG/JPEG/WebP assets to disk, and returns structured output paths for generated or edited images.

Configuration

Precedence (highest wins): CLI flag → env var → ~/.agens/config.json → built-in defaults.

| What | env | flag | config path | | -------------------- | ------------------------- | ----------------- | ---------------------------- | | Builder model | AGENS_MODEL | -m, --model | model | | Builder endpoint | AGENS_BASE_URL | --base-url | provider.baseUrl | | Builder key | AGENS_API_KEY | --api-key | provider.apiKey | | Judge model | AGENS_JUDGE_MODEL | --judge-model | judge.model | | Judge endpoint | AGENS_JUDGE_BASE_URL | --judge-base-url| judge.provider.baseUrl | | Judge key | AGENS_JUDGE_API_KEY | --judge-api-key | judge.provider.apiKey | | Image endpoint | AGENS_IMAGE_BASE_URL | | image.baseUrl | | Image key | AGENS_IMAGE_API_KEY | | image.apiKey | | Image bearer token | AGENS_IMAGE_BEARER_TOKEN| | image.bearerToken | | Image model | AGENS_IMAGE_MODEL | | image.model |

Judge fields fall back to builder fields when omitted, so the simplest config is just builder credentials.

agens config init                                # template at ~/.agens/config.json
agens config set provider.baseUrl http://...
agens config set provider.apiKey  ...
agens config set judge.model      gemini-2.5-pro
agens config show                                # secrets redacted

Image generation uses a separate Images API config so it does not depend on the builder model endpoint:

agens config set image.baseUrl http://ig.office-cli.onl/v1
agens config set image.bearerToken none
agens config set image.model gpt-image-2
agens config set image.size 1024x1024
agens config set image.quality low
agens config set image.outputFormat png

Default endpoint

Out of the box agens points at an internal multi-model gateway (http://20.9.234.247:8080/v1) running Claude Sonnet 4.6 (builder) and Gemini 3.1 Pro (judge). Override with config set or env vars if you have your own.

Architecture

┌─────────────────────────────┐     ┌──────────────────────────┐
│ Builder agent               │     │ Judge (critique tool)    │
│  Copilot SDK runtime        │ ──→ │  Independent model call  │
│  + skills (html-artisan…)   │     │  Vision input + JSON     │
│  + Playwright MCP           │     │  schema output           │
│  + tools (critique, a11y)   │     └──────────────────────────┘
└─────────────────────────────┘
        ↑                                   ↓
        └──── rubric + suggestions ─────────┘
                  iterate ≤ 5×

Repo layout

agens/
├── src/
│   ├── cli.ts             # commander entrypoint + subcommands
│   ├── config.ts          # SessionConfig builder (Playwright MCP, tools, skills)
│   ├── userconfig.ts      # 3-layer config: file + env + defaults
│   ├── repl.ts            # interactive mode
│   ├── oneshot.ts         # `agens "prompt"` one-shot mode
│   ├── skills.ts          # skill discovery + resolution
│   └── tools/
│       ├── critique.ts    # screenshot → judge model → rubric
│       └── a11y.ts        # axe-core via Playwright
├── skills/
│   ├── html-artisan/
│   ├── critic/
│   ├── slide-deck-pro/
│   ├── three-d-scene/
│   └── game-builder/
├── install.sh             # one-line installer (Node + tarball)
├── package.json
└── README.md

Requirements

• Node ≥ 24 (Copilot SDK runtime uses node:sqlite). Use install.sh if your distro is behind.
• Chromium (auto-installed by Playwright MCP on first run, ~120 MB).

License

ISC