Get Started Install and first session How It Works The breath cycle Configuration All settings Workspaces Monorepo patterns

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.

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.

Statusline & Notices

The three-line footer, every indicator, and the toast notices Soma shows you — including the preload lifecycle.

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.

Meta-Workflow

The operating cadence — how work flows through a project across many sessions. Three nested loops, a self-amending workflow, and how to adopt it in an existing project.

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.

Meta Dev-Tools

The dev:* namespace: caps that ship with the dev tree, not user installs.

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.

Extending Soma

Skills, extensions, events, APIs — build on top of Soma.

Prompt Templates

Create reusable prompt templates that expand with /name in the editor.

Skills

Install and create skills — self-contained capability packages loaded on demand.