Cast Codes
Portable intent grammar for routing familiar work across CastCodes, CLI/TUI, OpenClaw, and chat clients.
Cast Codes
Cast Codes are OpenCoven's portable intent grammar. They give humans, agents, and clients a compact way to express routing intent without making any client the authority boundary.
Cast Codes are intent, not enforcement. A client or Cast Agent can parse a Cast Code into a Coven request, but the Rust daemon still validates project roots, working directories, harness ids, live-session state, and action ids before anything sensitive happens.
Current Posture
The grammar is being documented as product language and client intent syntax. Treat examples as draft unless a command or endpoint is explicitly documented as shipped.
| Layer | Status | Meaning |
|---|---|---|
| Portable syntax | Direction | The grammar should be usable in CastCodes, CLI/TUI, OpenClaw, chat clients, and future clients. |
| Client parsing | Client-owned | A client can parse visible intent and submit a structured request. |
| Daemon enforcement | Shipped boundary | Coven daemon validation remains the only authority for sensitive runtime behavior. |
| Handoff and orchestration commands | Planned | Document as roadmap behavior until parser/API support exists. |
Example Glossolalia
| Code | Intent | Runtime mapping | Status |
|---|---|---|---|
~>sage | Switch familiar | Select Sage as the active familiar or lane. | Draft syntax |
~cody: review this diff | Delegate task | Create a task for Cody with the quoted prompt. | Draft syntax |
~* "new constraint: local-only" | Broadcast context | Fan out a shared constraint to active familiars or sessions. | Draft syntax |
~? | Status | Read active familiar/session status. | Nearest to shipped session/status behavior |
~^sage | Resume | Resume Sage or the matching prior lane. | Draft syntax |
~<echo | Handoff request | Request a handoff packet for Echo or from Echo. | Planned orchestration |
Where Cast Codes Can Appear
| Surface | Role | Boundary |
|---|---|---|
| CastCodes | First-party workspace | Render and parse Cast Codes as native workspace commands. |
coven CLI/TUI | Command surface | Accept typed intent and translate to daemon requests when supported. |
| OpenClaw plugin | Bridge | Submit structured Coven requests without bypassing daemon validation. |
| Telegram, Discord, or chat clients | Channel | Let familiar lanes receive portable routing intent. |
| Future clients | Extension point | Speak the same grammar without depending on one app implementation. |
CastCodes Demo Loop
This is the public demo path a new technical user should be able to follow: CastCodes captures intent, Coven launches and records the harness session, CastCodes keeps the work visible, and the user reviews the result before any merge or cleanup.
| Step | User action | Runtime path | Status |
|---|---|---|---|
| 1. Open project | Open a repository or worktree in CastCodes. | Client selects a visible project context. | CastCodes-owned UI |
| 2. Express intent | Type a Cast Code or task such as ~cody: fix failing tests. | Cast Agent parses intent into a structured launch request. | Grammar direction |
| 3. Launch session | Choose Codex or Claude Code, or let the client map the intent to a supported harness. | POST /api/v1/sessions with explicit project root, cwd, harness, prompt, and optional title. | Coven shipped API |
| 4. Watch work | Keep the session visible in a pane/session row. | GET /api/v1/sessions plus GET /api/v1/events?sessionId=...; live attach/input only after daemon liveness checks. | Coven shipped API, client UI stabilizing |
| 5. Review output | Inspect changed files, terminal output, and diffs before accepting anything. | Client reads repo state and event history; Coven remains the session source of truth. | CastCodes-owned review UI |
| 6. Finish explicitly | Merge locally, open a PR, archive the session, summon it later, or sacrifice it when logs should be deleted. | Client commands plus daemon-backed archive/summon/sacrifice lifecycle. | Mixed: client workflow plus Coven session lifecycle |
The demo should not hide unavailable states. If Coven is missing, point to Install Coven. If the daemon is stopped, suggest coven daemon start. If a harness is missing or unauthenticated, show coven doctor and the provider-owned setup step. If the session has completed, failed, been killed, archived, or orphaned, show logs and diffs instead of live input controls.
What is shipped today:
- Coven CLI, daemon,
coven.daemon.v1local API, Codex and Claude Code harness ids, sessions, events, input, kill, archive, summon, and sacrifice. - Cast Agent as the CastCodes-side substrate and session backend shape.
- CastCodes as the first-party workspace direction for visible panes, files, diffs, and review.
What is still roadmap or hardening work:
- Treating every Cast Code example as stable syntax.
- Broad OpenClaw plugin usage before compatibility tests and API versioning gates stay green.
- Hosted, remote, browser, or mobile access to the raw daemon socket.
Authority Rule
Cast Codes should never be documented as permission to bypass the daemon.
- Who parses user intent? A client, Cast Agent, or future parser can parse Cast Codes.
- Who decides whether a session may launch? The Coven daemon validates project root, cwd, and harness id.
- Who decides whether live input or kill is allowed? The Coven daemon validates session id and liveness.
- Who owns external action approvals? The daemon/control-plane policy layer must own approval requirements.
- Can a client treat Cast Code syntax as permission? No. Syntax is intent; daemon validation is authority.
Last updated on