Dcumentation
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.
Body Architecture
Structured identity with templates, variables, lazy loading, and the soma chain.
Heat System
How Soma decides what to load — temperature-based relevance.
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.
Reference
Commands, configuration, scripts, and the full changelog.
What's New for Soma
Agent-facing changelog: 'what NEW capabilities can I use, with just enough detail to use them.' Distinct from the technical CHANGELOG.md — this is action-oriented, dense, version-tagged, and tells YOU (the agent) which tools just landed and how to invoke them.
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.
MAPs
My Automation Protocol Scripts — reusable workflow templates that tell the agent which muscles to load, which scripts to run, and in what order.
Changelog
What shipped, what changed — the full version history of Soma.
CLI Tools: How Soma Surfaces Tools to the Agent
The three patterns for adding a tool. Pattern 1 (commands/.sh drop-in) is the answer most of the time. Decision flow ladder + reload semantics.
Dev Tools — the dev:* Meta-Tool
The dev:* namespace: caps that ship with the Soma development tree, not with user installs. Audit, hub, issue, kanban families.
Pro Tools — the _pro/ Tier
Scripts and capabilities that ship in the soma-beta tarball (PRO) but not the public npm package. Tier model, distribution, and graceful degrade pattern.
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.
Extending
Build your own skills, extensions, and tools.
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, blast, structure, lines, replace, stats, files, types. Agent-first codebase navigator with auto-detect, progressive scan, hard timeouts, and 12-language map support.
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.
General
Anthropic Long-Context (1M) Billing
How Sonnet 4.6's 1M context tier works under OAuth, and what to enable on the account vs the client.
Bridge Setup for Soma
Configure the local Somaverse bridge daemon — lifecycle, config, connectivity
Browser Setup for Soma
Configure Soma to drive a browser via CDP — Chrome, Brave, Edge, Arc, Chromium, Firefox
Tools
Soma tools — registration, configuration via _tools.md, and the bundled set