How tharunkumarra/avatar-os-v2 works
Avatar OS is a registry-driven personal operating system built from four independent Hermes profiles that use Discord and coordinate through shared durable state. The main workflow is an agent recording an observation through the profile-bound plugin; the runtime authenticates and validates it against registry capabilities and domain definitions, journals the event, and reconciles projections into snapshots and rendered views. The repository also defines scheduled workflows and supports registry extension, deployment previews, and generation recovery. Edges reflect README statements and shown calls; unsampled subsystem relationships are omitted where not documented.
Main entry points: avatar_os.py Avatar OS Runtime · __init__.py Avatar OS Plugin · system.json System Registry · profiles Hermes Profiles
Components 18
Agents and Integration
- Hermes Profiles
profiles - Roles and Skills
policy - Avatar OS Plugin
integrations/hermes/avatar-os/__init__.py - Profile Schedules
profiles
Registry and Domains
- System Registry
registry/system.json - Domain Manifests
registry/domains - Workflow Definitions
registry/workflows.json
State Runtime
- Avatar OS Runtime
shared/avatar-os/tools/avatar_os.py - Event Journal
shared/avatar-os - Projections and Views
shared/avatar-os - Shared State Resources
shared/avatar-os
Operations
- Schedule Renderer
scripts/render_workflows.py - Registry Scaffolder
scripts/scaffold.py - Deployment Preview
scripts/deployment_plan.py - Generation Recovery
scripts/avatar_ops.py
Other components
- User
- Discord
- Operator
Connections 18
- User → Discord: messages
README.md - Discord → Hermes Profiles: routes sessions
README.md - Hermes Profiles → Avatar OS Plugin: registers tools
README.md - Hermes Profiles → Roles and Skills: uses role policy
README.md - Avatar OS Plugin → Avatar OS Runtime: loads and handles
integrations/hermes/avatar-os/__init__.py - Avatar OS Plugin → System Registry: reads identity and capabilities
integrations/hermes/avatar-os/__init__.py - Avatar OS Plugin → Shared State Resources: reads or writes resources
integrations/hermes/avatar-os/__init__.py - Avatar OS Runtime → System Registry: compiles configuration
README.md - Avatar OS Runtime → Domain Manifests: validates event definitions
README.md - Avatar OS Runtime → Event Journal: appends events
README.md - Avatar OS Runtime → Projections and Views: projects and renders
README.md - Workflow Definitions → Schedule Renderer: defines schedules
README.md - Domain Manifests → Schedule Renderer: contributes close prompts
README.md - Schedule Renderer → Profile Schedules: renders jobs
README.md - Registry Scaffolder → System Registry: plans or creates entries
README.md - Operator → Deployment Preview: requests preview
README.md - Operator → Generation Recovery: inspects or rolls back
README.md - Generation Recovery → System Registry: activates generation
README.md