somora 🐨

Your AI team. Shared memory. Your choice of models.

Run personal AI agents on your own machine, switch between Claude, ChatGPT, Grok and local models in the middle of a conversation, and let the agents turn what they learn into a shared long-term wiki while they sleep. Run. Rest. Dream.

Install

curl -fsSL https://somora.ai/install.sh | bash

Linux or macOS, as a normal user. Brings everything that is missing (Node.js included), registers the background service and walks you through models, your first agent, memory and HTTPS — details under Quickstart. Update later: somora update.

One line (recommended)	curl -fsSL https://somora.ai/install.sh | bash
npm — you already have Node ≥22.22.2	docs/setup.md → Install by hand (npm 12 needs one extra flag)
From source — you want to work on somora itself	docs/setup.md → Develop from a checkout

See it

Browser desktop in dark and light, terminal, and installable phone app — all talking to the same local server, the same agents, the same memory.

Why somora

• A personal agent team. Configure as many agents as you want, each with its own character, private memory, model preferences, and tool permissions. A team.yaml tells every agent who reports to whom. Agents delegate to each other: one spawns a sub-agent for a task, another asks a colleague a question mid-turn, and an answer that arrives after the turn ended still reaches the one who asked.
• Knowledge that compounds. Agents notice facts while you chat, keep them privately, and a background dream cycle promotes stable knowledge into a shared Obsidian wiki — with your approval where it matters. What one agent learns today, another can use next week.
• Any model, one conversation. Flip between Claude (your Claude subscription), ChatGPT (your ChatGPT subscription), Grok, or any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, OpenRouter) with a slash command. History and tools carry over; the same tool registry feeds all four engines.
• Yours. Config, agent memory, sessions and attachments live in ~/.somora/; the shared wiki lives in your Obsidian vault; workspace files and generated media in your configured workspace. Which models and which external services your agents talk to is your configuration, not a default.

What is somora?

A small server you run on your machine that hosts your agents. You chat with them from the terminal, the browser, or your phone; they remember things across sessions; they use the same typed tools — memory, files (numbered reads, tolerant patches, filtered search), web, shell, tmux, attachments, sub-agents — regardless of which LLM you point them at. Everything an agent is asked to do — a question from you, a question from another agent, a sub-agent, a scheduled trigger, a voice call — goes through one queue per session that you can see and take back from in every client.

Two kinds of agents

Every agent is one of two kinds, chosen when it is created and never changed. Most of your agents are chat agents. A builder is the one you give a repository to.

	Chat agent	Builder
What it is for	Talking, thinking, remembering, orchestrating: the assistant you ask, the analyst, the coordinator	Building software in a repository: plan, edit, run, test, report
Its prompt	Its persona (AGENTS.md, SOUL.md, USER.md), your team, the wiki map, memory recall	Harness rules, an environment block, the repository's own AGENTS.md/CLAUDE.md; no persona, no memory recall
Tools	The whole programme, gated per agent	A short coding set: files, shell, task list, questions, helpers, colleagues, search
Turns	A few rounds; on an OpenAI-compatible model the loop stops at 30 tool calls (the CLI engines run their own loop)	Hours; hundreds of rounds, compaction mid-turn, a task list you watch
Memory	Notices facts, dreams them into notes and the wiki	Reads memory, never writes it; does not dream
Works in	Its workspace	The pinned project's folder, and folders an order allows besides it
Window	Chat	Chat plus a task panel, in the web client and on the phone: mode, plan → Go, tasks, acceptance list, questions, running time
Made how	somora setup agent, or a folder with an AGENTS.md and an agent.yaml	A folder whose agent.yaml says kind: builder — fixed for life

You can talk to a builder directly — describe the project, let it plan, press Go — or let a chat agent hand it the order in one call and be woken with the report. The hand-over procedure ships as a skill. Details in docs/builder.md; chat agents in docs/agents.md.

On top of chat and memory, each optional and off until configured:

• Skills — Markdown how-tos an agent can activate, with declared binaries and secrets that somora checks and injects (docs/skills.md).
• Media generation — point somora at an image or video endpoint and both you and your agents can make pictures and film; results land in your workspace and in one gallery (docs/imagegen.md, docs/videogen.md).
• Shared browser — a real Chromium per agent that the agent drives and you can watch and take over in the web client: sign in, pass a 2FA prompt, hand back, and the agent continues in the same tab (docs/browser.md).
• Talking to an agent — a standing, interruptible voice call in the web client or on the phone: a realtime model does the talking, the agent does the knowing, and a long answer is read out when it lands (docs/realtime-voice.md). Separate from dictation and spoken replies (docs/voice.md).
• Projects — bind a session to a real-world thing via a manifest of pointers the agent sees in its prompt (docs/projects.md).
• Sentinel — triggers that wake an agent on a schedule (at / every / daily / weekly / cron) or when a small check script sees something happen; a decision model can judge what the script fetched, such as "a new mail that needs an answer today" (docs/sentinel.md).
• External agents — bring an OpenClaw or Hermes agent into somora: you chat with it in its own window, and your agents hand it work over A2A, images and files included. Other systems reach your agents the same way, and an editor talks to them through somora acp (docs/external-agents.md, docs/a2a.md, docs/acp.md).
• External MCP servers — one config entry, all engines see the tools, gateable per agent (docs/mcp.md).
• Language servers — with one installed, every file a builder writes comes back with the compiler's errors for that file, so it fixes them in the same step (docs/lsp.md).
• Steering — type into a running turn instead of behind it: the model reads your message at its next step and changes course. Works on every engine (docs/api.md → Steering).
• Decision models — agents ask a System One decision model (such as a self-hosted Clef) typed yes/no, choice and score questions about text or images, and get probabilities back. Scripts and other programs ask through POST /decisions/evaluate (docs/decisions.md).

Requirements

Hard:

• Node ≥22.22.2 — the memory database uses better-sqlite3 with sqlite-vec, both prebuilt. On an older Node every somora command stops with the upgrade steps.
• macOS, or Linux with glibc ≥2.34 — Debian 12, Ubuntu 22.04, RHEL 9, Fedora 35 or newer. The memory database ships prebuilt for these.
• About 1.6 GB of disk on Linux, 1.4 GB on macOS, mostly the bundled Codex, Claude and Grok engines.
• A current browser for the web and mobile clients: Chrome or Edge 111, Firefox 114, Safari 16.4 (iOS and iPadOS 16.4) or newer.
• tmux — for the tmux tool (long-lived terminal sessions for agents) and the web tmux app.
• At least one LLM backend: a Claude subscription (engine claude-cli — Claude Code is bundled, somora claude login); a ChatGPT subscription (engine codex-cli — Codex is bundled, somora codex login); a SuperGrok or Premium subscription (engine grok-cli — the Grok CLI is bundled, somora grok login); or any OpenAI-compatible HTTP server (Ollama, LM Studio, vLLM, oMLX, OpenRouter, …).

Optional: an Obsidian vault for the shared wiki and read-only vault recall; Tailscale for HTTPS to the web and mobile clients (tailscale cert, needed for HTTP/2 and the microphone, screen-share and clipboard APIs); ripgrep for file_search; Chromium or Chrome for the shared browser.

somora makes one request of its own: once a day it asks somora.ai whether a newer version exists (version, OS, Node version and CPU in the User-Agent, nothing else; somora.ai counts installations from its server log). DO_NOT_TRACK=1 or updateCheck.enabled: false switches it off — docs/setup.md → The daily update check.

docs/setup.md is the full install walkthrough, docs/models.md lists the models known to run with somora and their tested config blocks.

Quickstart

curl -fsSL https://somora.ai/install.sh | bash

One line, as a normal user (not root), on Linux or macOS. The installer checks for tmux, ripgrep, git and a compiler and installs what is missing (it asks before using admin rights), brings Node.js if yours is missing or too old, installs somora from npm, registers the background service, and then starts the setup assistant:

somora setup
  1  Models        connect a Claude, ChatGPT or Grok subscription, or your own model server
  2  Web search    a Brave Search API key, so agents can search the web
  3  First agent   name, language, model and a backup model
  4  Memory        REM, Deep and Lucid — and where the shared wiki lives
  5  Team          who is who, once there is more than one agent
  6  Access        HTTPS through Tailscale, so phone and laptop can reach it
  7  Start + test  starts the service and sends your agent a real message

Every step first looks at what is already there, so somora setup is safe to run again — as a whole or one step (somora setup access). Update later with somora update.

Already have Node ≥22.22.2 and the tools from Requirements? Then follow Install by hand: one npm command, then somora setup.

Already using a coding agent? Let it set up somora.

If you already run Claude Code, Codex CLI or another AI agent with terminal access to your machine, hand it the setup. It reads the docs, does the install and configuration below, and gets you a complete instance — model providers, agents, a team, memory, skills, resources — not just a running server. Copy this into your agent:

Set up somora for me from the official repository:
https://github.com/thenaxon/somora_agent

Read the current README, then docs/setup.md, docs/models.md,
docs/agents.md, docs/team.md, docs/resources.md and docs/skills.md.
Inspect my environment, then install somora with the installer from the
README (`curl -fsSL https://somora.ai/install.sh | bash -s -- --no-setup`)
and configure it yourself instead of the interactive `somora setup`.

Aim for a complete, useful setup, not just a running server:
- Help me choose model providers and connect the CLI logins or API
  access I already have. Use the documented model configurations
  (engine, reasoning mapping, context window, capabilities, sampling,
  fallback) from docs/models.md — don't guess model IDs.
- Set up my agents and a coherent team with clear roles and
  delegation rules (docs/agents.md, docs/team.md), including one
  builder agent for coding work if I have a repository to work in
  (docs/builder.md).
- Configure the features that fit me: memory and the dream phases,
  skills, projects, scheduled tasks (sentinel), the shared browser, and
  image, video or voice generation where I have a backend for it. Explain
  optional features and what they need rather than silently skipping them.
- Connect the machines and services I want as resources
  (docs/resources.md).
- Ask concise questions for missing preferences, credentials or
  decisions.
- Verify: the server is healthy, a chat turn answers on the
  configured model, tools run, and every integration you set up
  works. Summarise what works and what still needs my input.

Preserve unrelated services and configuration. Ask before making
disruptive changes. Never invent model IDs, credentials, resources or
configuration options that the docs don't describe.

By hand

# 1. Prereqs (see docs/setup.md for details per OS)
sudo apt install tmux ripgrep git build-essential python3   # Debian/Ubuntu
# brew install tmux ripgrep git                             # macOS (plus Xcode command line tools)

# 2. Install somora (npm older than 11.16: leave out the --allow-scripts line)
ONNXRUNTIME_NODE_INSTALL=skip npm install -g somora \
  --allow-scripts=cpu-features,esbuild,fsevents,node-pty,onnxruntime-node,protobufjs,somora,ssh2

# 3. Log in to at least one LLM backend (pick one or more)
somora claude login                         # Claude subscription; Claude Code is bundled
somora codex login                        # ChatGPT subscription; Codex is bundled
somora grok login                         # SuperGrok or Premium subscription; the Grok CLI is bundled
# local models: run Ollama / LM Studio / oMLX and add the endpoint to
# ~/.somora/config.yaml after step 4

# 4. First-run setup + start
somora init                    # creates ~/.somora/ and registers the background service
somora server start            # starts it (and from then on at boot / login); the default agent is created on first start
somora tui                     # chat in the terminal
somora key link                # sign the web client in (link + QR code for the phone)

Once you have more than one agent, somora team init --principal "<your name>" writes ~/.somora/team.yaml so every agent knows who is who — or arrange it in the team tile of the web client (docs/team.md). The web client, providers and Tailscale HTTPS are in docs/setup.md; hacking on somora itself in its contributor section.

What works where

Every engine gets the same feature set:

Capability	claude-cli	codex-cli	grok-cli	openai-compatible
Chat (streaming)	✓	✓	✓	✓
Memory auto-injection	✓	✓	✓	✓
Memory tools (read + write)	✓ via MCP	✓ dynamic tools	✓ via MCP	✓ in-process
Wiki layer (shared)	✓	✓	✓	✓
Three-phase dreams	✓	✓	✓	✓
Tool surface	✓ via MCP	✓ dynamic tools	✓ via MCP	✓ in-process
Skills (markdown how-tos)	✓	✓	✓	✓
Multimodal attachments (image, PDF)	✓ native	✓ image native, PDF rasterized	✓ image native, PDF rasterized	✓ image; PDF native or rasterized per provider
Image + video generation¹	✓ via MCP	✓ dynamic tools	✓ via MCP	✓ in-process
Sub-agents, agent-to-agent questions, follow-ups	✓	✓	✓	✓
SSH-resource exec	✓	✓	✓	✓

¹ Off until an imageGen / videoGen block exists in config.yaml.

Architecture at a glance

   you (terminal · browser · phone)   another agent   a voice call   a timer
                    │                       │              │            │
        TUI / Web / Mobile PWA           agent_ask     realtime      sentinel
                    │                       │              │            │
                    └──── HTTP + SSE · WebSocket ──────────┴────────────┘
                                          ▼
   somora-server
   │
   ├─ Turn dispatch — one entry for every turn, whoever started it
   │    one queue per session, first come first served · Stop reaches every turn
   │    work ledger: what runs, what waits, what is arriving · wakes when
   │    late results land · follow-ups to whoever asked · visible in every client
   │
   ├─ Engines           claude-cli · codex-cli · grok-cli · openai-compatible
   │    one tool registry for all four (in-process · MCP child · Codex dynamic tools)
   │
   ├─ Tools             memory · dream · wiki · file · exec + tmux · web · agents
   │                    skills · sentinel · browser · image · video · media · projects
   │                    + external MCP servers — every tool gateable per agent
   │
   ├─ Memory            ~/.somora/agents/<name>/memory/*.md   per agent, private
   │  Wiki              <obsidian-vault>/<wiki-subfolder>/    shared, long-term
   │  Vault             the rest of the vault                 read-only context
   │                    hybrid retrieval (SQLite + sqlite-vec + FTS5), one index per source
   │
   ├─ Dream system      REM  session → memory   ·   Deep  memory → wiki   ·   Lucid  wiki review
   │
   ├─ Sentinel          ~/.somora/sentinel/triggers.json — time and check-script fires as agent turns
   │
   ├─ Optional          realtime voice call · Chromium per agent · image + video generation
   │
   └─ Storage           sessions as JSONL · attachments content-addressed · config.yaml
                        all under ~/.somora/

Clients

Three first-party clients, all hitting the same local server:

Client	Launch	What you get
TUI	somora tui	Terminal multi-agent chat with full keyboard control, the session's queue (/queue), memory and tool detail toggles.
Web	https://<host>.<tailnet>.ts.net:18737/web/	A browser desktop: one window per agent, drag-and-drop attachments and screenshots, tmux app and shell terminal, Wiki Explorer with link graph, Media gallery, Sessions browser, the agent's Chromium window, server log, an inbox for updates and things that need you, a light or dark theme plus the bundled Ocean theme, or themes of your own (colours and wallpaper, docs/web.md#themes), Abilities matrix (which tools and skills each agent may use), Team and Agent windows, a queue badge per session (what runs, what waits, what is arriving — take back or stop from there), dictation and spoken replies, and a voice window for a live call. HTTPS recommended (needed from other devices and for the microphone); sign in once with the server's key (somora key link). docs/web.md
Mobile (PWA)	…:18737/mobile/, then "Add to Home Screen"	The phone app: avatar row to switch agent, a sheet in the header to switch session and model or restore an archived session, the same queue sheet with steering, the thinking level per session, a tools switch that shows a turn's tool calls, a builder's panel (mode, phase, Go, task and acceptance lists), voice input and spoken replies, a live voice call with an agent, photo/PDF attachments via the native picker. Signs in once by scanning the QR code from somora key link. docs/mobile.md

Anything else can talk to the server the same way the clients do, with the server's key in an Authorization: Bearer header: docs/api.md is the HTTP + SSE + WebSocket reference.

Documentation

Start at docs/index.md: what somora is, which page to read for which goal, and every concept in one sentence. The same pages, rendered and searchable: docs.somora.ai.

• Get running: setup · models · agents · team · security
• Memory and knowledge: memory · wiki · dream phases · compaction · cache strategy
• What agents can do: tools · builders · language servers · files · tmux · resources · skills · MCP servers · projects · sentinel · browser · image generation · video generation · decision models · image handling · external agents · A2A
• Clients and API: web · mobile · TUI display · voice · realtime voice · editors (ACP) · API
• Models in detail: thinking · sampling

Contributing

Contributions are welcome. CONTRIBUTING.md says how to report bugs, propose ideas and send pull requests. Security problems are reported privately: SECURITY.md. What changed in each version is in the release notes.

License

MIT.

---

🐨 somora — patient, slow, with very good memory.