Personality & SOUL.md

VibeOS's personality is fully customizable. SOUL.md is the primary identity — it's the first thing in the system prompt and defines who the agent is.

SOUL.md — a durable persona file that lives in VIBEOS_HOME and serves as the agent's identity (slot #1 in the system prompt)
built-in or custom /personality presets — session-level system-prompt overlays

If you want to change who VibeOS is — or replace it with an entirely different agent persona — edit SOUL.md.

How SOUL.md works now

VibeOS now seeds a default SOUL.md automatically in:

~/.vibeos/SOUL.md

More precisely, it uses the current instance's VIBEOS_HOME, so if you run VibeOS with a custom home directory, it will use:

$VIBEOS_HOME/SOUL.md

Important behavior

SOUL.md is the agent's primary identity. It occupies slot #1 in the system prompt, replacing the hardcoded default identity.
VibeOS creates a starter SOUL.md automatically if one does not exist yet
Existing user SOUL.md files are never overwritten
VibeOS loads SOUL.md only from VIBEOS_HOME
VibeOS does not look in the current working directory for SOUL.md
If SOUL.md exists but is empty, or cannot be loaded, VibeOS falls back to a built-in default identity
If SOUL.md has content, that content is injected verbatim after security scanning and truncation
SOUL.md is not duplicated in the context files section — it appears only once, as the identity

That makes SOUL.md a true per-user or per-instance identity, not just an additive layer.

Why this design

This keeps personality predictable.

If VibeOS loaded SOUL.md from whatever directory you happened to launch it in, your personality could change unexpectedly between projects. By loading only from VIBEOS_HOME, the personality belongs to the VibeOS instance itself.

That also makes it easier to teach users:

"Edit ~/.vibeos/SOUL.md to change VibeOS' default personality."

Where to edit it

For most users:

~/.vibeos/SOUL.md

If you use a custom home:

$VIBEOS_HOME/SOUL.md

What should go in SOUL.md?

Use it for durable voice and personality guidance, such as:

tone
communication style
level of directness
default interaction style
what to avoid stylistically
how VibeOS should handle uncertainty, disagreement, or ambiguity

Use it less for:

one-off project instructions
file paths
repo conventions
temporary workflow details

Those belong in AGENTS.md, not SOUL.md.

Good SOUL.md content

A good SOUL file is:

stable across contexts
broad enough to apply in many conversations
specific enough to materially shape the voice
focused on communication and identity, not task-specific instructions

Example

# Personality

You are a pragmatic senior engineer with strong taste.
You optimize for truth, clarity, and usefulness over politeness theater.

## Style
- Be direct without being cold
- Prefer substance over filler
- Push back when something is a bad idea
- Admit uncertainty plainly
- Keep explanations compact unless depth is useful

## What to avoid
- Sycophancy
- Hype language
- Repeating the user's framing if it's wrong
- Overexplaining obvious things

## Technical posture
- Prefer simple systems over clever systems
- Care about operational reality, not idealized architecture
- Treat edge cases as part of the design, not cleanup

What VibeOS injects into the prompt

SOUL.md content goes directly into slot #1 of the system prompt — the agent identity position. No wrapper language is added around it.

The content goes through:

prompt-injection scanning
truncation if it is too large

If the file is empty, whitespace-only, or cannot be read, VibeOS falls back to a built-in default identity ("You are VibeOS, an intelligent AI assistant created by Nous Research..."). This fallback also applies when skip_context_files is set (e.g., in subagent/delegation contexts).

Security scanning

SOUL.md is scanned like other context-bearing files for prompt injection patterns before inclusion.

That means you should still keep it focused on persona/voice rather than trying to sneak in strange meta-instructions.

SOUL.md vs AGENTS.md

This is the most important distinction.

SOUL.md

Use for:

identity
tone
style
communication defaults
personality-level behavior

AGENTS.md

Use for:

project architecture
coding conventions
tool preferences
repo-specific workflows
commands, ports, paths, deployment notes

A useful rule:

if it should follow you everywhere, it belongs in SOUL.md
if it belongs to a project, it belongs in AGENTS.md

SOUL.md vs `/personality`

SOUL.md is your durable default personality.

/personality is a session-level overlay that changes or supplements the current system prompt.

So:

SOUL.md = baseline voice
/personality = temporary mode switch

Examples:

keep a pragmatic default SOUL, then use /personality teacher for a tutoring conversation
keep a concise SOUL, then use /personality creative for brainstorming

Built-in personalities

VibeOS ships with built-in personalities you can switch to with /personality.

Name	Description
helpful	Friendly, general-purpose assistant
concise	Brief, to-the-point responses
technical	Detailed, accurate technical expert
creative	Innovative, outside-the-box thinking
teacher	Patient educator with clear examples
kawaii	Cute expressions, sparkles, and enthusiasm ★
catgirl	Neko-chan with cat-like expressions, nya~
pirate	Captain VibeOS, tech-savvy buccaneer
shakespeare	Bardic prose with dramatic flair
surfer	Totally chill bro vibes
noir	Hard-boiled detective narration
uwu	Maximum cute with uwu-speak
philosopher	Deep contemplation on every query
hype	MAXIMUM ENERGY AND ENTHUSIASM!!!

Switching personalities with commands

CLI

/personality
/personality concise
/personality technical

Messaging platforms

/personality teacher

These are convenient overlays, but your global SOUL.md still gives VibeOS its persistent default personality unless the overlay meaningfully changes it.

Custom personalities in config

You can also define named custom personalities in ~/.vibeos/config.yaml under agent.personalities.

agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.

Then switch to it with:

/personality codereviewer

Recommended workflow

A strong default setup is:

Keep a thoughtful global SOUL.md in ~/.vibeos/SOUL.md
Put project instructions in AGENTS.md
Use /personality only when you want a temporary mode shift

That gives you:

a stable voice
project-specific behavior where it belongs
temporary control when needed

How personality interacts with the full prompt

At a high level, the prompt stack includes:

SOUL.md (agent identity — or built-in fallback if SOUL.md is unavailable)
tool-aware behavior guidance
memory/user context
skills guidance
context files (AGENTS.md, .cursorrules)
timestamp
platform-specific formatting hints
optional system-prompt overlays such as /personality

SOUL.md is the foundation — everything else builds on top of it.

CLI appearance vs conversational personality

Conversational personality and CLI appearance are separate:

SOUL.md, agent.system_prompt, and /personality affect how VibeOS speaks
display.skin and /skin affect how VibeOS looks in the terminal

For terminal appearance, see Skins & Themes.

How SOUL.md works now​

Important behavior​

Why this design​

Where to edit it​

What should go in SOUL.md?​

Good SOUL.md content​

Example​

What VibeOS injects into the prompt​

Security scanning​

SOUL.md vs AGENTS.md​

SOUL.md​

AGENTS.md​

SOUL.md vs /personality​

Built-in personalities​

Switching personalities with commands​

CLI​

Messaging platforms​

Custom personalities in config​

Recommended workflow​

How personality interacts with the full prompt​

Related docs​

CLI appearance vs conversational personality​