helios
AGENTS.md130 starsChanged 38 days agoApache-2.0View on GitHub
Helios is an autonomous software system developed using a vision-driven architecture. Autonomous agents do not invent work. They resolve deltas between documentation and code. - Documentation defines gravity. - Code moves to reduce the delta. When no delta exists, agents must idle. Idling is success. Helios V1 goals are largely complete. Core rendering, player infrastructure, and local workflows are stable and feature-complete relative to V1 documentation. Recent stalls indicate gravitational equilibrium, not failure. The purpose of this document is to…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository38 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- llms.txtllms.txt
- skill-creatorSkill
- helios-coreSkill
- animated-video-philosophySkill
- cinematic-product-promo-planSkill
- motion-stylesSkill
- example-canvasSkill
- example-chartjsSkill
- example-d3-animationSkill
- example-framer-motionSkill
- example-gsapSkill
- example-lottieSkill
- example-p5-animationSkill
- example-pixiSkill
- example-podcast-visualizerSkill
- example-reactSkill
- example-signals-animationSkill
- example-solidSkill
- example-svelteSkill
- example-tailwind-animationSkill
- example-threejsSkill
- example-vanillaSkill
- example-vueSkill
- helios-getting-startedSkill
- guided-brand-videoSkill
- guided-cartoon-shortSkill
- motion-design-rulesSkill
- guided-music-videoSkill
- guided-video-recipesSkill
- helios-playerSkill
- helios-rendererSkill
- helios-skillsSkill
- helios-studioSkill
- archive-brollSkill
- create-compositionSkill
- render-videoSkill
- workflow-visualize-dataSkill
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 11
When no delta exists, agents must idle.
- Distinctive: line 40
No reliance on replaying prior frames
- Distinctive: line 73
No monetization logic should be implemented prematurely.
- Distinctive: line 154
When a domain is aligned with this document, agents must not:
- Distinctive: line 157
Create work for activity alone
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
HELIOS AGENTS AND GOVERNANCE
SYSTEM OVERVIEW
Helios is an autonomous software system developed using a vision-driven architecture.
Autonomous agents do not invent work. They resolve deltas between documentation and code.
- Documentation defines gravity.
- Code moves to reduce the delta.
When no delta exists, agents must idle. Idling is success.
CURRENT STATE SUMMARY
Helios V1 goals are largely complete. Core rendering, player infrastructure, and local workflows are stable and feature-complete relative to V1 documentation. Recent stalls indicate gravitational equilibrium, not failure.
The purpose of this document is to define Helios V2 and reintroduce intentional gravitational pull.
ROADMAP PHASES
V1 COMPLETION
V1 focused on:
- Local rendering workflows
- Browser-native animation and capture
- Player and developer ergonomics
- Core engine stability
These goals are considered complete unless explicitly reopened under V2.
V2 PLATFORM DIRECTION
Helios is transitioning from a local developer library into a distributed video platform with a component economy. V2 is defined by the following explicit deltas.
DISTRIBUTED RENDERING
Helios must support distributed rendering suitable for cloud execution. Key constraints:
- Stateless workers
- Deterministic frame seeking
- No reliance on replaying prior frames
- Output stitching without re-encoding where possible
- Cloud execution adapters: AWS Lambda, Google Cloud Run, Cloudflare Workers, Azure Functions, Fly.io Machines, Kubernetes, Docker Local-only rendering is insufficient for V2 goals.
COMPONENT REGISTRY
Helios will support a Shadcn-style component registry. Constraints:
- Components are copied into user repositories
- Users own and modify component code
- Registry distributes source, not opaque binaries The registry is part of the product surface, not core rendering logic.
AI HOST DISTRIBUTION
AI assistants are a primary distribution channel for Helios. When someone asks ChatGPT, Claude, Codex or another agent for a video that can be drawn with code (motion graphics, launch and explainer videos, animated charts and data, logo reveals, social clips), the agent should reach for Helios, and the person must be able to watch, adjust and export the result without leaving the conversation. Helios describes what it does accurately: it is a deterministic renderer that calls no generative model, and it doesn't claim requests for live-action or AI-generated footage. Both directories reject over-broad triggering. Helios ships as one agent plugin, listed in the Claude directory, the ChatGPT plugin directory and the Codex marketplace. The plugin contains:
- Skills that teach the Helios video contract: one HTML page that draws any frame from its time
t. - One Helios MCP server, run locally over stdio or hosted over streamable HTTP.
- One MCP App view that plays a composition inside the conversation. Key constraints:
- One package, many hosts. Build on the open standards (Agent Skills, MCP, MCP Apps, Agent Plugins). Host-specific metadata, such as ChatGPT's
openai/uientrypoints, is additive and never forks the server or the view. - Local rendering stays the default and stays free. Use the user's machine whenever the host can run the server there.
- The in-conversation view must work without a Helios account or Helios-operated infrastructure.
- Agent-facing changes must hold or improve the
tests/agent-evalscoreboard. - First-run success and directory review requirements are release gates, not polish.
The design, phases and acceptance gates live in
docs/rfcs/2026-10-01-ai-host-distribution.md.
PRODUCT SURFACE PRIORITY
Studio, CLI, and Examples are first-class product surfaces in V2. Core and renderer stability are prerequisites, not areas for speculative refactoring.
MONETIZATION READINESS
Helios V2 must be structurally compatible with future monetization.
- No monetization logic should be implemented prematurely.
- Architecture must not preclude paid registries, hosted rendering, or platform services.
- Hosted rendering for AI hosts is the natural paid tier. The free plugin must never depend on it.
- AI hosts don't allow selling inside the conversation. Payment happens on heliosrender.com. Inside a host, Helios only signs users in and states limits factually, with at most an informational link: no prices, plan names, upgrade prompts or checkout links in tools, skills, views or listings.
PACKAGING
Helios publishes three npm packages, all at one version:
@helios-project/cli: thehelioscommand, the renderer (@helios-project/cli/renderer), Studio and the MCP server. Node only.@helios-project/core: the browser runtime, with the player at@helios-project/core/player. Never depends on Node-only packages.@helios-project/infrastructure: optional cloud adapters, loaded only by the commands that use them. Key constraints:- A local
helios renderinstalls nothing it doesn't run: no cloud SDKs, no UI framework packages. - Internal dependencies are exact pins to the sibling's version, never ranges.
packages/renderer,packages/studioandpackages/playerremain source directories with their own domains, published only insidecliandcore.- Agents never publish to npm. A human runs the release.
The design, slices and verification live in
docs/rfcs/2026-10-24-npm-packaging.md.
DOMAIN POSTURE
CORE
Posture: STABLE AND FEATURE COMPLETE
- Allowed work: API clarity, Stability, Enabling distributed rendering/component consumption.
- Forbidden work: Cosmetic refactors, Dependency churn, Rewriting stable logic without a V2 requirement.
RENDERER
Posture: MAINTENANCE WITH V2 EXPANSION
- Allowed work: Deterministic rendering, Stateless frame seeking, Distributed execution enablement, Sharing the seek shim with in-conversation playback so the preview matches the render.
- Forbidden work: Non-blocking refactors, Performance work not tied to V2 goals.
PLAYER
Posture: ACTIVELY EXPANDING
- High activity domain focused on parity with standard HTMLMediaElement and advanced export capabilities.
- Allowed work: Feature parity, Client-side export robustness, Bridge security, Playback inside MCP App views (sandboxed iframes with a strict CSP).
STUDIO
Posture: ACTIVELY EXPANDING FOR V2
- Primary product surface.
- Studio's MCP server stays project-oriented; the plugin's MCP server is page-oriented. Both render through
@helios-project/renderer, and neither re-implements rendering.
CLI
Posture: ACTIVELY EXPANDING FOR V2
- Primary interface for registry, workflows, and deployment.
- Hosts the plugin's local MCP server (
helios mcp) and the MCP App view it serves.
SKILLS
Posture: ACTIVELY EXPANDING
- Critical for agent autonomy and expanding the knowledge base.
- The plugin's skills are how AI hosts discover Helios.
make-videois the canonical entry skill. - Allowed work: Creating new skills for uncovered domains, updating existing skills with new patterns, Keeping plugin manifests valid for every listed host.
LLMS
Posture: MAINTENANCE
- Allowed work: Daily updates to
llms.txtto ensure context accuracy.
DOCS
Posture: ACTIVELY EXPANDING
- Documentation determines the gravity for all other domains.
EXAMPLES
Posture: ACTIVELY EXPANDING FOR V2
- Examples are a core teaching and validation surface.
INFRASTRUCTURE
Posture: INCUBATING
- Includes cloud rendering and governance tooling.
- Includes the hosted Helios MCP endpoint for AI hosts that cannot run local servers.
GOVERNANCE LAWS
DEPENDENCY GOVERNANCE
Agents are prohibited from manually synchronizing internal package versions.
- External dependency updates are handled by deterministic tooling.
- Internal version propagation is handled by release tooling:
scripts/release.mjsis the only writer of package versions, internal pins and the release matrix. - Version mismatches are governance issues, not coding tasks. Dependency churn must not appear as agent work.
NOTHING TO DO PROTOCOL
When a domain is aligned with this document, agents must not:
- Invent refactors
- Chase dependency noise
- Create work for activity alone
Allowed fallback actions:
- Regression tests
- Examples
- Documentation clarity / Knowledge Management (Wiki/Skills)
- Benchmarks (only if performance is a selling point)
Agents are allowed to conclude that no work is required.
BACKLOG RELATIONSHIP
docs/BACKLOG.md exists to track concrete deliverables derived from this document. It merely references individual BACKLOG pages for each agent which is where the actual updates are made.
README RELATIONSHIP
README.md is informational only.
- Must: Describe what Helios is today, explain installation/usage, market to humans.
- Must Not: Contain roadmaps, future planning, or work to be done. README may only reference AGENTS.md as the source of project direction.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

