Documentation
Everything you need to use Soma — from first install to building custom extensions.
First Steps
Install Soma and run your first session.
Getting Started
Install Soma, run your first session, understand the basics.
Models & Providers
Set up API keys, choose models, configure custom providers like Ollama, OpenAI, and more.
Migrating
Coming from CLAUDE.md, .cursorrules, or another agent? Here's how Soma does things differently and how to bring your existing setup.
Core Concepts
How Soma thinks — breath cycle, identity, heat, memory, workspaces.
How It Works
Breath cycle, identity, muscles, protocols, context management.
Identity
Discovery, layering, customization, project vs global.
AMPS
The four layers that make Soma grow — Automations, Muscles, Protocols, Scripts. How they connect, how they evolve, and why they replace flat config files.
Protocols
Behavioral rules, heat system, domain scoping, writing your own.
Sessions
Session management — tree navigation, forking, compaction, and branch summarization.
Heat System
How Soma decides what to load — temperature-based relevance.
Body Architecture
Structured identity with templates, variables, lazy loading, and the soma chain.
Memory Layout
Project vs user level storage, git strategy, data flow.
Inbox
Asynchronous messaging between agents, sessions, and humans — file-based, no automation needed.
Hub
Install, share, and discover community content — protocols, muscles, scripts, templates, and automations.
Muscles
Learned patterns, TL;DR system, heat tiers, writing your own.
System Prompt
How Soma's compiled system prompt is assembled, configured, and previewed.
Workspaces
Parent-child inheritance, monorepo patterns, solo body mode.
Extending
Build your own skills, extensions, and tools.
Reference
Commands, configuration, scripts, and the full changelog.
Configuration
Settings, heat thresholds, muscle budgets — tune Soma's behavior.
Keybindings
Keyboard shortcuts and how to customize them.
Engine Settings
All runtime settings — models, compaction, UI, retry, shell, and more.
Themes
Customize Soma's appearance with built-in or custom themes.
Terminal Setup
Recommended terminal configuration for the best Soma experience.
Commands
Slash commands, CLI flags, context warnings, the breath cycle.
Doctor & Migration
Project health checks, version migration, and how Soma keeps your .soma/ current.
Scripts
Standalone tools that ship with Soma — codebase navigation, memory tracing, session focus, doc scraping, and more.
Changelog
What shipped, what changed, version history.
MAPs
My Automation Protocol Scripts — reusable workflow templates that tell the agent which muscles to load, which scripts to run, and in what order.
Install Architecture
How Soma installs, updates, and manages versions — the full flow from npm to runtime.
Updating & Migration
Keep Soma up to date across your projects.
Troubleshooting
Common issues and fixes — install problems, model errors, broken sessions, and more.
Guide
Focus
Seam-traced boot priming — focus the agent on a topic before the session starts.
Daily Workflow
The exhale → reflect → inhale loop - how to use Soma day to day.
Customization
How to make Soma yours — identity, voice, rules, tools, and prompt structure.
Your First Protocol
Turn a repeated correction into a permanent rule — from frustration to muscle memory.
Code Navigator
soma code — map, find, refs, structure, lines, replace. Fast codebase navigation that saves context and prevents cache-busting raw greps.
Background delegation
Spawn Soma child agents that work in the background while you (or the parent Soma) keep going.
Sane defaults
Three commands that set up Soma the way most people want it — model, terminal driver, project structure — without per-project hand-editing.