Cybos — custom AI personalities

A Cybo is a reusable AI identity defined by a cybo.json and a soul.md, runnable standalone or inside a workspace.

A Cybo is a customized AI agent with its own identity, personality, and model preferences. It's just two files:

  • cybo.json — identity + provider/model (name, slug, description, role, avatar, provider, model).
  • soul.md — the personality / system prompt.

Cybos are PI agents under the hood: the cybo CLI spawns PI in RPC mode with --append-system-prompt, and PI handles providers, tools, sessions, and auth. A Cybo can run standalone (cybo "prompt") or be spawned into a Cyborg7 workspace (cyborg cybo:spawn).

cybo.json

{
  "slug": "atlas",
  "name": "Atlas",
  "role": "Research & Project Assistant",
  "description": "Plans work and keeps the team unblocked.",
  "avatar": "🗺️",
  "provider": "claude",
  "model": "claude-opus-4-8",
  "soul": "soul.md"
}

:::note[provider / model] The model id above is just an example. Valid ids are provider-specific and change over time — run cybo model list to see what your installed providers expose, or omit model entirely to use the provider's default. :::

The soul field is either an inline string or a path ending in .md — when it ends in .md, the file's contents are read from the Cybo's directory and used as the system prompt.

How the soul reaches the model

When a Cybo is spawned, Cyborg7 builds a system prompt from its identity and soul, then passes it to the provider:

cybo.json + soul.md
      │  buildCyboPrompt()  → "You are {name}, a {role}.\n{description}\n\n{soul}"
      ▼
  createAgent({ systemPrompt, model, … })
      ▼
  PI runtime → --append-system-prompt "<system prompt>"

The exact same mechanism powers the standalone cybo CLI and the in-workspace spawn — so a Cybo behaves identically in both worlds.

Standalone CLI

cybo init                       # create cybo.json + soul.md
cybo link                       # register in ~/.cybo/agents/
cybo list                       # list registered cybos
cybo doctor                     # check PI, auth, model
cybo model set <provider/model> # update cybo.json
cybo "review this PR"           # one-shot (auto-detect from cwd)

Two sources of truth (no back-sync)

  • Disk is the source of truth for the standalone CLI (~/.cybo/agents/<slug>/).
  • The database is the source of truth for a workspace (the cybos table stores soul as a column).

You can import a local cybo into a workspace (a one-way snapshot, disk → DB) to edit it in-app. There is no automatic two-way sync — editing the soul in the workspace does not rewrite soul.md, and vice-versa.