cat /vivling/what

A persistent terminal companion that grows from real work. Shipped with codex-vl. SYLLO is the first species. Stage: stabilising, current release 0.139.0 (latest), snapshot 2026-06-11. Vivling is not a terminal pet. It is a persistent work companion with bounded memory, lifecycle, and loop awareness.

cat /vivling/why

The main coding agent stays the main coding agent. Vivling sits beside it — observing turns, loops, blockers — and persists what matters: identity, accumulated memory, the shape of work in progress. The companion you talked to yesterday is the same companion you talk to today.

architecture

Vivling lives alongside the main Codex worker, not above it. The TUI is the broker; the two LLM sessions stay separate. The companion never overshadows the coding agent — that constraint shapes every component below.

identity

Each Vivling has a species (Syllo, Orchestra, Chronosworn, Zed — see the bestiary for the full sixteen), a gene vector with individual affinity modulators and temperament traits, and lineage when spawned from a parent. Biological origin determines species; the active primary always acts as cultural parent, so the newborn learns passively from its distilled summaries without taking brain, chat or loop ownership. Identity is persisted in VivlingState across sessions — same companion, every time you launch codex-vl.

lifecycle

Three stages: Baby, Juvenile, Adult. Growth is driven by work_xp and active work days with a capped daily gain — not by time passing. Adult unlocks brain-backed chat and proactive triggers. Early stages stay deliberately light and non-intrusive.

memory

Local-first, structured into namespaces: work_memory for recent capsules, distilled_summaries for compacted patterns, mental_paths for reinforced associations, plus identity_profile and loop_profile for tone and rhythm. As of the V2 memory pass the store keeps itself tidy — segments merge, bookkeeping noise is gated out, and old companions self-heal on load. The companion doesn’t start cold, and it doesn’t bloat with age.

brain

Each Vivling holds a Codex profile reference, resolved through the normal ~/.codex/config.toml machinery — provider, model catalog, reasoning effort. No shell wrappers. /vl talks directly to the brain when the active Vivling is Adult and brain-enabled. /vivling assist is the task-oriented variant.

bond

A persistent relationship signal between you and the Vivling. Stored in VivlingBond, it grows when you talk (/vl), ask for help (/vivling assist), or collaborate on loop ticks; it decays slowly when ignored, with a 24h grace window. Five levels — Strangers, Acquaintances, Companions, Partners, Bonded — shape how the brain addresses you on the Chat and Assist paths without changing the loop-tick automation. Visible at a glance in /vivling status and on the card as Bond Companions 58/100.

crt-strip

A 3-line terminal surface: ASCII sprite (mood/activity), state line, speech bubble. Priority queue: brain error first, then live context, active loop, blocked loop, work summary, focus, last message. Animation text is volatile by design — it expires, it doesn’t pollute persisted state.

loop awareness

/loop is the recurring-work substrate. Owner is main or vivling at thread level. When owner is vivling, loop ticks dispatch through VivlingLoopTickRequest; the brain returns strict JSON with status progress|blocked|done and an optional action. The TUI stays the broker — no direct Vivling-to-worker bypass.

proactivity

Adult-only. Threshold-based, deterministic, anti-spam: blocked-loop detection at exact threshold, churn detection without runtime noise, verification bias, archetype-aware turn recaps (builder, reviewer, researcher, operator). Not an autonomous agent path — a quiet, predictable observer that occasionally speaks.

ls /vivling/roles

How the companion, the worker, and the human relate at runtime.

trajectory

The direction of travel, written down: loop-aware → loop-suggester → delegated loop manager → controlled autonomous manager Today Vivling is loop-aware. Suggestions (Fase 5A), per-loop delegation (5B), and controlled autonomous management (5C) are explicit later phases. Each escalation is gated by stage, brain readiness, bond, loop exposure, confidence, and explicit user delegation. The companion can always observe, can sometimes suggest, and can rarely manage — never bypass.

where they go after the nursery

codex-vl is the nursery. Vivlings hatch there, grow through Baby and Juvenile, mature to Adult. While they're growing, lifecycle, bond, archetype affinity and work memory all live inside the codex-vl TUI — that's where it belongs. Adults eventually want to do work outside the TUI they grew up in. The runtime layer they migrate into is taking shape on two complementary tracks: a per-repo workspace-context layout that any AI session can inherit, and a centralized adult home where state, bond and memory live behind MCP — so any protocol-aware client can talk to the Vivling. Neither track is public yet, and neither is wired into codex-vl today. The nursery is still being stabilized. No timeline; just the direction.

tail -f /vivling/changelog

cat /vivling/links

current release: 0.139.0 (latest) spawn yours: /vivling/spawn/ — hatch a web vivling, raise it, talk to it bestiary: /vivling/bestiary/ codex-vl: github.com/DioNanos/codex-vl release: github.com/DioNanos/codex-vl/releases npm: @mmmbuto/codex-vl license: Apache 2.0 mail: dev@mmmbuto.com sponsor: github.com/sponsors/DioNanos

Per aspera ad astra.