Open source · MIT · local-first
An agent identity is a stateful interface, not a profile image.
Orbsona separates a stable visual identity from live runtime state. The colors, relief, pattern, and seed remain recognizable while motion responds to what the agent is doing.
MIT licensed
The Studio and renderer are open source. You can use, modify, distribute, and ship them under the MIT License.
Local-first
Studio saves one working draft in browser storage. There is no Orbsona account, database, cloud sync, or analytics service.
Provider-neutral
The package exposes semantic states. It does not bundle or claim first-party adapters for voice or agent providers.
Public npm package · v0.1.0
Install the renderer
npm, pnpm, Yarn, and Bun install the same public @accidental-revenue/orbsona release. Choose the manager already used by your application.
npm
npm install @accidental-revenue/orbsonapnpm
pnpm add @accidental-revenue/orbsonaYarn
yarn add @accidental-revenue/orbsonaBun
bun add @accidental-revenue/orbsonaWhy agents need identity
Communicate state
A voice agent has long silent intervals. Motion shows whether it is listening, reasoning, speaking, using a tool, or waiting for help.
Preserve continuity
The same visual identity can follow an agent across a call screen, support widget, dashboard, and embedded workflow.
Support, do not replace, language
Animation is an ambient signal. Product UI still needs labels, announcements, and explicit error messages for accessibility.
Version 1
Runtime state contract
AgentStateidleAvailable and waitingconnectingEstablishing a live sessionlisteningReceiving user inputthinkingReasoning before respondingspeakingReturning voice outputworkingCalling a tool or completing a tasksuccessThe requested action completederrorThe session needs attentionReact 18+ · ESM
Component API
identityAvatarIdentityThe stable visual configuration.stateAgentStateThe agent's current semantic state.sizenumber | stringRendered width and height.energynumberGeneral signal level from 0 to 1.inputLevelnumberOptional microphone or listening level.outputLevelnumberOptional speech-output level.classNamestringClass name applied to the canvas wrapper.styleCSSPropertiesInline styles applied to the canvas wrapper.Portable identity file
{
"format": "orbsona.identity",
"version": 1,
"identity": {
"name": "Aster",
"background": "relief",
"rotateBackground": false,
"grain": false,
"animation": "field",
"palette": {
"id": "ion",
"name": "Ion",
"colors": ["#77c8ff", "#214bb4", "#e0f7ff"]
},
"seed": 2718
}
}Rendering guarantees
- Reduced motion. Movement becomes restrained when the operating system requests it.
- Bounded rendering. The canvas caps pixel density to avoid unnecessary GPU work.
- Semantic state. Provider events map to a small, stable set of agent states.
- Versioned files. Import validation can reject incompatible identities safely.
Ownership model
Your identity lives with your code.
Studio keeps one working draft in this browser so a refresh does not erase your work. Download the .orbsona.json file and commit it with your application. That file is the portable source of truth, and you can import it back into Studio whenever you want to edit it.
Create
Tune one browser draft in Studio.
Own
Download and version the identity file.
Run
Map your agent events to semantic states.
Included today
- Visual Studio with one browser-saved working draft
- Import and export for versioned identity JSON
- React canvas renderer and TypeScript contract
- PNG and WebM fallback exports
Deliberately not included
- User accounts, subscriptions, or a hosted backend
- Cloud identity storage or cross-device synchronization
- Analytics, telemetry, or identity uploads
- Provider-specific SDK adapters or hosted event relays
License
Build on it freely.
Orbsona is distributed under the MIT License, including the repository-level Studio and the @accidental-revenue/orbsona package. Keep the copyright and permission notice with copies or substantial portions of the software.