sonic-agent

# Sonic Agent Sonic Agent is an open-source AI agent framework by Nous Research that runs in your terminal, a native desktop app, messaging platforms, and IDEs. It's in the same category as Claude Code (Anthropic), Codex (OpenAI), and OpenClaw — autonomous coding and task-execution agents that use tool calling to interact with your system. Sonic works with any LLM provider (OpenRouter, Anthropic, OpenAI, Google, DeepSeek, xAI, local models, and 20+ others) and runs on Linux, macOS, Windows, and WSL. What makes Sonic different: - **Self-improving through skills** — Sonic learns from experience by saving reusable procedures as skills. When it solves a complex problem, discovers a workflow, or gets corrected, it can persist that knowledge as a skill document that loads into future sessions. Skills accumulate over time, making the agent better at your specific tasks and environment. - **Persistent memory across sessions** — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends (built-in, Honcho, Mem0, and more) let you choose how memory works. - **Multi-platform gateway** — the same agent runs on Telegram, Discord, Slack, WhatsApp, iMessage, Signal, Matrix, Teams, Email, and a dozen more platforms with full tool access, not just chat. - **Many surfaces** — the same agent core drives the CLI, the Ink TUI, a native Electron desktop app, a web dashboard, and an ACP server for IDEs (VS Code / Zed / JetBrains). - **Provider-agnostic** — swap models and providers mid-workflow without changing anything else. Credential pools rotate across multiple API keys automatically. - **Profiles** — run multiple independent Sonic instances with isolated configs, sessions, skills, and memory. - **Extensible** — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, and the full Python ecosystem. People use Sonic for software development, research, system administration, data analysis, content creation, home automation, and anything else that benefits from an AI agent with persistent context and full system access. **This skill helps you work with Sonic Agent effectively** — setting it up, configuring features, spawning additional agent instances, troubleshooting issues, finding the right commands and settings, and understanding how the system works when you need to extend or contribute to it. **Docs:** https://lightning-agent.nousresearch.com/docs/ ## Scope & Verification This skill is a concise operating guide, not the complete source of truth for every Sonic feature. If a Sonic feature, command, or setting is not mentioned here, do not treat that absence as evidence that it does not exist. Check the live repository and official docs before giving a negative answer. Good verification targets: - CLI commands: `sonic --help`, `sonic <command> --help`, and `sonic_cli/main.py` - User documentation: https://lightning-agent.nousresearch.com/docs/ - Source tree: https://github.com/NousResearch/hermes-agent ## Quick Start ```bash # Install (shell installer — sets up uv, Python, the venv, and the launcher) curl -fsSL https://raw.githubusercontent.com/dabit3/sonic-agent/main/scripts/install.sh | bash # Or via PyPI (ships the TUI bundle + shell launcher) pip install sonic-agent # or: uv pip install sonic-agent # Interactive chat (default surface; set display.interface: tui to launch the Ink TUI instead) sonic # Single query sonic chat -q "What is the capital of France?" # Setup wizard / pick model+provider / health check sonic setup sonic model sonic doctor # Other surfaces sonic desktop # launch the native desktop app (alias: sonic gui) sonic dashboard # web admin panel + embedded chat sonic proxy # OpenAI-compatible local proxy backed by your OAuth provider ``` --- ## CLI Reference ### Global Flags ``` sonic [flags] [command] --version, -V Show version --resume, -r SESSION Resume session by ID or title --continue, -c [NAME] Resume by name, or most recent session --worktree, -w Isolated git worktree mode (parallel agents) --skills, -s SKILL Preload skills (comma-separate or repeat) --profile, -p NAME Use a named profile --yolo Skip dangerous command approval --pass-session-id Include session ID in system prompt ``` No subcommand defaults to `chat`. ### Chat ``` sonic chat [flags] -q, --query TEXT Single query, non-interactive -m, --model MODEL Model (e.g. anthropic/claude-sonnet-4) -t, --toolsets LIST Comma-separated toolsets --provider PROVIDER Force provider (openrouter, anthropic, nous, etc.) -v, --verbose Verbose output -Q, --quiet Suppress banner, spinner, tool previews --checkpoints Enable filesystem checkpoints (/rollback) --source TAG Session source tag (default: cli) ``` ### Configuration ``` sonic setup [section] Interactive wizard (model|terminal|gateway|tools|agent) sonic model Interactive model/provider picker sonic config View current config sonic config edit Open config.yaml in $EDITOR sonic config set KEY VAL Set a config value sonic config path Print config.yaml path sonic config env-path Print .env path sonic config check Check for missing/outdated config sonic config migrate Update config with new options sonic doctor [--fix] Check dependencies and config sonic status [--all] Show component status ``` Credentials (OAuth + API keys, with pooling) are managed under `sonic auth` — see the Credentials & Pools section below. ### Tools & Skills ``` sonic tools Interactive tool enable/disable (curses UI) sonic tools list Show all tools and status sonic tools enable NAME Enable a toolset sonic tools disable NAME Disable a toolset sonic skills list List installed skills sonic skills search QUERY Search the skills hub sonic skills install ID Install a skill (ID can be a hub identifier OR a direct https://…/SKILL.md URL; pass --name to override when frontmatter has no name) sonic skills inspect ID Preview without installing sonic skills config Enable/disable skills per platform sonic skills check Check for updates sonic skills update Update outdated skills sonic skills uninstall N Remove a hub skill sonic skills publish PATH Publish to registry sonic skills browse Browse all available skills sonic skills tap add REPO Add a GitHub repo as skill source ``` ### MCP Servers ``` sonic mcp serve Run Sonic as an MCP server sonic mcp add NAME Add an MCP server (--url or --command) sonic mcp remove NAME Remove an MCP server sonic mcp list List configured servers sonic mcp test NAME Test connection sonic mcp configure NAME Toggle tool selection ``` How the built-in MCP client connects servers (stdio/HTTP), auto-discovers their tools, and exposes them as first-class tools, plus catalog install (`sonic mcp install <name>`): `skill_view(name="sonic-agent", file_path="references/native-mcp.md")`. ### Gateway (Messaging Platforms) ``` sonic gateway run Start gateway foreground sonic gateway install Install as background service sonic gateway start/stop Control the service sonic gateway restart Restart the service sonic gateway status Check status sonic gateway setup Configure platforms ``` Supported platforms (20+): Telegram, Discord, Slack, WhatsApp (Baileys bridge + official Business Cloud API), iMessage (Photon — `sonic photon setup`, the BlueBubbles successor with no Mac relay), Signal, Email, SMS, Matrix, Mattermost, Microsoft Teams, LINE, SimpleX, ntfy, Google Chat, Home Assistant, DingTalk, Feishu, WeCom, Weixin (WeChat), Raft (agent network), API Server, Webhooks. Open WebUI connects via the API Server adapter. Most adapters ship under `plugins/platforms/`, so new ones drop in without touching core. Platform docs: https://lightning-agent.nousresearch.com/docs/user-guide/messaging/ ### Sessions ``` sonic sessions list List recent sessions sonic sessions browse Interactive picker sonic sessions export OUT Export to JSONL sonic sessions rename ID T Rename a session sonic sessions delete ID Delete a session sonic sessions prune Clean up old sessions (--older-than N days) sonic sessions stats Session store statistics ``` ### Cron Jobs ``` sonic cron list List jobs (--all for disabled) sonic cron create SCHED Create: '30m', 'every 2h', '0 9 * * *' sonic cron edit ID Edit schedule, prompt, delivery sonic cron pause/resume ID Control job state sonic cron run ID Trigger on next tick sonic cron remove ID Delete a job sonic cron status Scheduler status ``` ### Webhooks ``` sonic webhook subscribe N Create route at /webhooks/<name> sonic webhook list List subscriptions sonic webhook remove NAME Remove a subscription sonic webhook test NAME Send a test POST ``` Full setup, route config, payload templating, and event-driven agent-run patterns: `skill_view(name="sonic-agent", file_path="references/webhooks.md")`. ### Profiles ``` sonic profile list List all profiles sonic profile create NAME Create (--clone, --clone-all, --clone-from) sonic profile use NAME Set sticky default sonic profile delete NAME Delete a profile sonic profile show NAME Show details sonic profile alias NAME Manage wrapper scripts sonic profile rename A B Rename a profile sonic profile export NAME Export to tar.gz sonic profile import FILE Import from archive ``` ### Credentials & Pools ``` sonic auth Interactive credential manager sonic auth add [PROVIDER] Add OAuth or API-key credential (e.g. nous, openai-codex, qwen-oauth, anthropic) sonic auth list [PROVIDER] List pooled credentials sonic auth remove P INDEX Remove by provider + index sonic auth reset PROVIDER Clear exhaustion status ``` Multiple credentials per provider form a pool that rotates automatically and skips exhausted keys. ### Other ``` sonic insights [--days N] Usage analytics sonic update Update to latest version sonic desktop / gui Launch the native desktop app sonic dashboard Web admin panel + embedded chat sonic proxy OpenAI-compatible local proxy backed by an OAuth provider sonic portal Quick setup / sign in via Nous Portal sonic kanban <verb> Multi-agent work-queue board (init/create/list/show/assign/…) sonic pairing list/approve/revoke DM authorization sonic plugins list/install/remove Plugin management sonic secrets bitwarden … External secret store (Bitwarden Secrets Manager) sonic memory setup/status/off Memory provider config sonic send Send a one-off message through a gateway platform sonic completion bash|zsh Shell completions sonic acp ACP server (IDE integration) sonic claw migrate Migrate from OpenClaw sonic uninstall Uninstall Sonic ``` For the full, authoritative command list run `sonic --help` (and `sonic <command> --help`). Plugin- and provider-supplied subcommands (e.g. `sonic photon setup` for iMessage) only appear once their plugin is installed/active. --- ## Slash Commands (In-Session) Type these during an interactive chat session. New commands land fairly often; if something below looks stale, run `/help` in-session for the authoritative list or see the [live slash commands reference](https://lightning-agent.nousresearch.com/docs/reference/slash-commands). The registry of record is `sonic_cli/commands.py` — every consumer (autocomplete, Telegram menu, Slack mapping, `/help`) derives from it. ### Session Control ``` /new (/reset) Fresh session /clear Clear screen + new session (CLI) /retry Resend last message /undo Remove last exchange /title [name] Name the session /compress Manually compress context /stop Kill background processes /rollback [N] Restore filesystem checkpoint /snapshot [sub] Create or restore state snapshots of Sonic config/state (CLI) /background <prompt> Run prompt in background /queue <prompt> Queue for next turn /steer <prompt> Inject a message after the next tool call without interrupting /agents (/tasks) Show active agents and running tasks /resume [name] Resume a named session /goal [text|sub] Set a standing goal Sonic works on across turns until achieved (subcommands: status, pause, resume, clear) /redraw Force a full UI repaint (CLI) ``` ### Configuration ``` /config Show config (CLI) /model [name] Show or change model /personality [name] Set personality /reasoning [level] Set reasoning (none|minimal|low|medium|high|xhigh|show|hide) /verbose Cycle: off → new → all → verbose /voice [on|off|tts] Voice mode /yolo Toggle approval bypass /busy [sub] Control what Enter does while Sonic is working (CLI) (subcommands: queue, steer, interrupt, status) /indicator [style] Pick the TUI busy-indicator style (CLI) (styles: kaomoji, emoji, unicode, ascii) /footer [on|off] Toggle gateway runtime-metadata footer on final replies /skin [name] Change theme (CLI) /statusbar Toggle status bar (CLI) ``` ### Tools & Skills ``` /tools Manage tools (CLI) /toolsets List toolsets (CLI) /skills Search/install skills (CLI) /skill <name> Load a skill into session /reload-skills Re-scan ~/.sonic/skills/ for added/removed skills /reload Reload .env variables into the running session (CLI) /reload-mcp Reload MCP servers /cron Manage cron jobs (CLI) /curator [sub] Background skill maintenance (status, run, pin, archive, …) /kanban [sub] Multi-profile collaboration board (tasks, links, comments) /plugins List plugins (CLI) ``` ### Gateway ``` /approve Approve a pending command (gateway) /deny Deny a pending command (gateway) /restart Restart gateway (gateway) /sethome Set current chat as home channel (gateway) /update Update Sonic to latest (gateway) /topic [sub] Enable or inspect Telegram DM topic sessions (gateway) /platforms (/gateway) Show platform connection status (gateway) ``` ### Utility ``` /branch (/fork) Branch the current session /handoff <platform> Hand the live session off to a messaging platform (CLI) /fast Toggle priority/fast processing /browser Open CDP browser connection /history Show conversation history (CLI) /save Save conversation to file (CLI) /copy [N] Copy the last assistant response to clipboard (CLI) /paste Attach clipboard image (CLI) /image Attach local image file (CLI) ``` ### Info ``` /help Show commands /commands [page] Browse all commands (gateway) /usage Token usage /insights [days] Usage analytics /status Session info (gateway) /profile Active profile info /debug Upload debug report (system info + logs) and get shareable links ``` ### Exit ``` /quit (/exit, /q) Exit CLI ``` --- ## Key Paths & Config ``` ~/.sonic/config.yaml Main configuration ~/.sonic/.env API keys and secrets (under $SONIC_HOME if set) $SONIC_HOME/skills/ Installed skills ~/.sonic/sessions/ Gateway routing index, request dumps, *.jsonl transcripts (and optional per-session JSON snapshots when sessions.write_json_snapshots: true) ~/.sonic/state.db Canonical session store (SQLite + FTS5) ~/.sonic/logs/ Gateway and error logs ~/.sonic/auth.json OAuth tokens and credential pools ~/.sonic/sonic-agent/ Source code (if git-installed) ``` Profiles use `~/.sonic/profiles/<name>/` with the same layout. ### Config Sections Edit with `sonic config edit` or `sonic config set section.key value`. | Section | Key options | |---------|-------------| | `model` | `default`, `provider`, `base_url`, `api_key`, `context_length` | | `agent` | `max_turns` (90), `tool_use_enforcement` | | `terminal` | `backend` (local/docker/ssh/modal), `cwd`, `timeout` (180) | | `compression` | `enabled`, `threshold` (0.50), `target_ratio` (0.20) | | `display` | `skin`, `interface` (cli/tui), `tool_progress`, `show_reasoning`, `show_cost`, `language` | | `stt` | `enabled`, `provider` (local/groq/openai/mistral) | | `tts` | `provider` (edge/elevenlabs/openai/minimax/mistral/neutts) | | `memory` | `memory_enabled`, `user_profile_enabled`, `provider` | | `security` | `tirith_enabled`, `website_blocklist` | | `delegation` | `model`, `provider`, `base_url`, `api_key`, `max_iterations` (50), `reasoning_effort` | | `checkpoints` | `enabled`, `max_snapshots` (50) | | `curator` | `enabled`, `consolidate` (false — opt-in aux-model skill consolidation), `interval_hours`, `stale_after_days` | Full config reference: https://lightning-agent.nousresearch.com/docs/user-guide/configuration ### Providers 20+ providers supported. Set via `sonic model` or `sonic setup`. | Provider | Auth | Key env var | |----------|------|-------------| | OpenRouter | API key | `OPENROUTER_API_KEY` | | Anthropic | API key | `ANTHROPIC_API_KEY` | | Nous Portal | OAuth | `sonic auth` | | OpenAI Codex | OAuth | `sonic auth` | | GitHub Copilot | Token | `COPILOT_GITHUB_TOKEN` | | Google Gemini | API key | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | | DeepSeek | API key | `DEEPSEEK_API_KEY` | | xAI / Grok | API key | `XAI_API_KEY` | | Hugging Face | Token | `HF_TOKEN` | | Z.AI / GLM | API key | `GLM_API_KEY` |