Seraph

The AI agent that audits itself.

v0.5.4 — Gateway feature completion: streaming, dynamic provider plugins, hot-reload, remote-device nodes, OAuth PKCE, sandbox execution, canvas surfaces, companion pairing.

Self-improving, self-auditing, multi-channel AI agent platform. 45 tools, 23 channels, runs everywhere.

---

Fastest path to first message — local CLI (60 seconds)

No bot tokens. No platform setup. Just clone, install, run, type.

git clone https://github.com/bosskalash/seraph.git
cd seraph
pip install -e .
python seraph_cli.py

You land at a > prompt. Type a message, press Enter, and Seraph replies in the same terminal — routed through the full shared V2 reasoning core (tools, failover, verifier, memory, outcome recording). Exit with /exit, quit, Ctrl+C, or Ctrl+D.

Slash commands inside the CLI:

/help       — show this help
/status     — show channel/session/model status
/new        — clear the current conversation
/model      — view or change the active LLM model
/channels   — list registered channels in the registry
/exit       — exit the REPL (also: /quit, exit, quit)

What you need first: an LLM API key in ~/.seraph/.env (or your shell environment). See Configuration. If you want a richer setup — Telegram, Discord, Slack, and 19 other channels — see Other channels.

Why this is the recommended path: the CLI is a first-class IChannelAdapter on the shared V2 core — the exact same reasoning pipeline Telegram and Discord use. See docs/ARCHITECTURE.md and docs/PLUGIN_QUICKSTART.md.

---

Why Seraph?

	Legacy Agent	Hermes	Seraph
Self-improving	No	Yes	Yes
Self-auditing	No	No	Yes
Anti-dilution	No	No	Yes
Windows native	Clunky	No (WSL)	Yes
Channels	22	16	23
Tools	~30	48	45
Models	~10	200+	200+
Memory	SQLite	SQLite+FTS5	SQLite+FTS5
Skills guard	No	Regex	Regex + trust scoring
Smart routing	No	Yes	Yes + failover + pool
Canvas	Electron	No	Web (any browser)
Companion app	Native	No	PWA (all platforms)

---

Install

From PyPI:

pip install seraph-agent
seraph configure   # interactive setup wizard
seraph run         # foreground
# or: seraph start   # background

From source (for development):

git clone https://github.com/bosskalash/seraph.git
cd seraph
pip install -e .
python seraph_cli.py

Docker (for running the full multi-channel deployment):

git clone https://github.com/bosskalash/seraph.git
cd seraph
cp .env.example .env  # edit with your keys
docker compose up -d

---

Configuration

Seraph reads config from ~/.seraph/.env (and your process environment). The CLI launcher loads this file automatically on startup.

Minimum for the CLI path:

SERAPH_PROVIDER=openai
SERAPH_MODEL=gpt-4o-mini
OPENAI_API_KEY=your-key-here

Or any provider Seraph supports — Anthropic, Google, OpenRouter, MiniMax, Mistral, DeepSeek, Groq, Fireworks, Together, xAI, Cerebras, etc.

Supported Models

• OpenAI: gpt-5.4, gpt-4.1, gpt-4o, gpt-4o-mini
• Anthropic: claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5
• OpenRouter: 200+ models via one API key

YAML config (~/.seraph/config.yaml)

model: gpt-5.4
provider: openai
memory:
  enabled: true
skills:
  auto_generate: true
audit:
  enabled: true
  max_rounds: 5

Identity (~/.seraph/SOUL.md)

Customize who your agent is. Injected into every prompt.

MCP Servers (~/.seraph/mcp.json)

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

---

Other channels

The CLI is the fastest local path. For real-world deployments you can run any of the other 22 channels instead — they all share the same reasoning core.

Telegram (the historic default):

1. Get a bot token from @BotFather.
2. Add to ~/.seraph/.env:

   SERAPH_TELEGRAM_TOKEN=your-bot-token
   SERAPH_ALLOWED_USERS=your-telegram-id
   

3. Run python run.py — this boots the full multi-channel stack (Telegram + Discord + Slack + WhatsApp + any channel with credentials).
4. Message your bot on Telegram.

Discord, Slack, WhatsApp, Signal, Matrix, ... — set the matching env vars in ~/.seraph/.env and they start automatically when run.py boots. See the full channel list below, and docs/PLUGIN_QUICKSTART.md for how to add a new one.

---

45 Built-in Tools

Category	Tools
Core	terminal, read_file, write_file, list_files, clipboard
Web	web_search, web_fetch, browse (headless)
Code	run_code (sandbox), apply_patch, audit_file, audit_directory
AI	describe_image (vision), mixture_of_agents, delegate_task, verify_claim
Media	generate_image (DALL-E), text_to_speech, transcribe, voice_respond
Comms	send_email, notify, manage_webhook, send_notification
Data	query_sqlite, export_conversation, export_html, search_sessions
DevOps	ssh, git, git_clone, import_api (OpenAPI), health_check
Smart Home	homeassistant
Workflow	todo, checkpoint, clarify, request_approval, interrupt, progress
Skills	skills_hub (install/search/sync), fuzzy_find, mcp (Model Context Protocol)
Meta	canvas (visual workspace), qr_code, usage_stats

23 Channels

Channel	Protocol	Status
CLI	stdin/stdout	Production — fastest local path
Telegram	Bot API	Production
Discord	Gateway WS	Ready
Slack	Socket Mode	Ready
WhatsApp	Cloud API	Ready
Signal	signal-cli REST	Ready
Matrix	Client-Server	Ready
Email	IMAP + SMTP	Ready
SMS	Twilio	Ready
IRC	Raw socket	Ready
MS Teams	Bot Framework	Ready
Google Chat	Webhook API	Ready
LINE	Messaging API	Ready
Mattermost	REST API	Ready
Twitch	IRC over SSL	Ready
Nostr	Relay protocol	Ready
DingTalk	Robot API	Ready
Feishu/Lark	Open API	Ready
iMessage	BlueBubbles	Ready
WebChat	HTTP server	Ready
Canvas	Visual workspace	Ready
Voice Wake	Mic + wake word	Ready
PWA	Progressive Web App	Ready

40+ Slash Commands (Telegram/Discord/Slack)

/new         Fresh conversation         /improve     Self-improvement cycle
/model       View or change model       /cron        Manage scheduled jobs
/status      System status              /heartbeat   Health monitor
/tools       List available tools       /doctor      Run diagnostics
/exec        Run a shell command        /approve     DM pairing approval
/search      Search the web             /think       Set reasoning level
/read        Read a file                /insights    Conversation analytics
/files       List workspace files       /update      Pull latest from git
/memory      Memory status              /restart     Restart the bot
/remember    Save a fact                /backup      Backup all data
/forget      Remove a fact              /logs        View recent logs
/recall      Search past conversations  /budget      Daily spending limit
/persona     Switch personality         /template    Prompt templates
/raw         Direct LLM (zero overhead) /config      View/change settings
/sandbox     Run Python code            /compress    Smart compress
/branch      Fork conversation          /retry       Retry last response
/undo        Undo last exchange         /send        Send a file
/checkpoint  Save conversation state    /id          Show Telegram ID
/restore     Restore a checkpoint       /help        Show all commands

The CLI channel supports a smaller built-in set (/help, /status, /channels, /exit); other slash commands still dispatch through to the shared core when typed.

Architecture

User (on one of 23 channels: CLI, Telegram, Discord, Slack, ...)
  |
  v
Channel adapter (IChannelAdapter — thin, delivery-only)
  |
  v
seraph_core/orchestrator.py  — shared V2 reasoning core
  |  ProviderRegistry | ToolRegistry | SeraphSettings
  |  FailoverEngine | ToolLoop | ResponseDiscipline
  |  OutcomeRecorder | ShadowEvalRunner | PromptBuilder
  |
  v
LLM provider (OpenAI / Anthropic / Google / OpenRouter / ...)
  |
  v
SQLite — memory (FTS5), sessions, skills, rules

Every channel — CLI included — goes through the same core. See docs/ARCHITECTURE.md.

What Makes Seraph Different

Anti-Dilution Engine

Other platforms waste 30-50% of context on bloated system prompts. Seraph has:

• Smart tool filtering -- only sends relevant tools per message
• Prompt compiler -- minifies, deduplicates, strips decorations
• Context budget -- system overhead capped at 20%
• Lazy injection -- memory only loaded when conversation needs it
• /raw mode -- zero injection, direct LLM access

Self-Improvement Loop

The agent improves itself over time:

• Reviews conversations for user corrections
• Stores lessons in active memory
• Auto-generates reusable skills from complex tasks
• Self-audits its own code for bugs
• Runs on cron (every 6h) or manual (/improve)

Skills Guard

Every external skill is security-scanned before installation:

• 30+ threat patterns (exfiltration, injection, destructive, credential theft)
• Trust scoring (0-100)
• Install policy by source (builtin/trusted/community)

Canvas

Live visual workspace at http://localhost:18803/canvas. The agent can push HTML, code, tables, charts, and run JavaScript in your browser.

Model Router

• Smart routing -- simple questions use cheap model, complex use strong
• Failover chain -- auto-switch when a model is down
• Credential pool -- rotate API keys with exponential backoff

Testing

pip install -e ".[dev]"
python -m pytest tests/ -v

Report a bug / Ask for help

• Bug? Open an issue — the form asks for seraph doctor output, version, and repro steps so we can act on it: github.com/bosskalash/seraph/issues/new/choose.
• Security vulnerability? Do NOT file a public issue. Use GitHub's private advisory flow — github.com/bosskalash/seraph/security/advisories/new — and see SECURITY.md for scope and disclosure timeline.
• Setup question? Run seraph doctor first — it prints actionable next-step hints for every failed check.

Contributing

See CONTRIBUTING.md and docs/PLUGIN_QUICKSTART.md for the 5-minute guide to writing a tool, provider, channel, or memory backend.

License

MIT — see LICENSE.