https://github.com/caesar0301/soothe
♨ᎪᏞᏢᎻᎪ🍷「 ✦ Soothe ✦ 」An autonomous expert system engineered to orchestrate complex workflows and execute long-duration tasks with precision and persistence.
https://github.com/caesar0301/soothe
agent-harness agentic-researcher autonomous-agents scientific-agents
Last synced: 2 months ago
JSON representation
♨ᎪᏞᏢᎻᎪ🍷「 ✦ Soothe ✦ 」An autonomous expert system engineered to orchestrate complex workflows and execute long-duration tasks with precision and persistence.
- Host: GitHub
- URL: https://github.com/caesar0301/soothe
- Owner: caesar0301
- License: mit
- Created: 2026-03-12T03:52:53.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-16T10:28:51.000Z (2 months ago)
- Last Synced: 2026-04-16T10:29:29.968Z (2 months ago)
- Topics: agent-harness, agentic-researcher, autonomous-agents, scientific-agents
- Language: Python
- Homepage:
- Size: 13 MB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ✨ Soothe — Beyond Yet-Another Agent
#
[](https://pypi.org/project/soothe/)
[](https://pypi.org/project/soothe/)
[](https://pypi.org/project/soothe-sdk/)
[](https://pypi.org/project/soothe-cli/)
[](https://pypi.org/project/soothe-community/)
[](https://github.com/caesar0301/Soothe/blob/main/LICENSE)
[](https://github.com/caesar0301/Soothe)
[](https://deepwiki.com/caesar0301/Soothe)
Soothe is **not** another Claude Code / OpenClaw clone.
Its ambition is to become an **agent-harnessing framework**, an *Agentic OS*, designed to push humans **out of the execution loop**.
After months of real-world "vibe coding" with coding agents, a clear pain emerged:
humans are still responsible for holding everything together, driving agents across sessions, verifying intermediate results, recovering lost context, re-aligning goals, and manually relaying critical information between tools and skills. This constant supervision creates a heavy cognitive burden.
**Soothe was built to eliminate that loop.**
Instead of treating agents as isolated executors, Soothe introduces a higher-order orchestration layer. Built on top of LangChain / DeepAgents, it adds a persistent **agentic loop** and **goal engine** that can:
- maintain context across sessions
- sustain and recover long-running goals
- coordinate multiple objectives simultaneously
- autonomously steer complex, long-horizon tasks
In short, Soothe shifts the paradigm from *human-in-the-loop* to **agent-in-the-loop** systems—where humans define intent, and the system handles execution, continuity, and adaptation.
---
## 🚀 Key Features
- ✨ **Thinks Ahead** — Plans multi-step workflows and adapts dynamically based on outcomes
- 🚀 **Acts Autonomously** — Executes tasks across research, coding, file ops, and browser automation
- 🧠 **Learns & Remembers** — Persistent memory across sessions—no more repeating yourself
- 🔒 **Stays Secure** — Enforces least-privilege access and keeps data under your control
- 🔌 **Extends Easily** — Plugin system for custom tools and specialized sub-agents
- 🌐 **Works Anywhere** — Multi-transport daemon (Unix, WebSocket, HTTP REST)
## Architecture
## Design Philosophy
**Plan → Execute**: Autonomous execution loop that plans, acts, evaluates, and adapts without manual intervention.
**Persistent Memory**: Sessions accumulate knowledge. Resume threads, recall context, and track long-running goals across conversations.
**Security First**: Local execution with least-privilege policies. Your infrastructure, your data, your control.
**Plugin Architecture**: Built-in tools for web search, code execution, and browser automation. Extend with custom plugins via decorator APIs.
## What Can Soothe Do?
**Deep Research**: Multi-source web search, academic papers, document analysis with automatic synthesis and citations.
**Autonomous Execution**: Multi-step workflows with automatic planning, file operations, code execution, and browser automation.
**Long-Running Operations**: Background daemon mode with thread management, persistent state, and resume capabilities.
**Custom Plugins**: Extend with decorator-based tools, specialized subagents, and MCP server integration.
## Milestones
- ✅ **Single-Session Autonomy** — Solve a complex goal end-to-end within a single session, fully out of the human loop
- ⏳ **Cross-Session Continuity** — Sustain and complete complex tasks across multiple sessions with persistent context
- ⏳ **Multi-Goal Orchestration** — Handle multiple interdependent goals over long-horizon workflows
- ⏳ **Benchmark Reproduction** — Reproduce the Anthropic C Compiler [experiment](https://github.com/anthropics/claudes-c-compiler)
## Getting Started
### Installation
Soothe is published as a monorepo with multiple packages:
- **`soothe`** — Core functionalities with daemon
- **`soothe-cli`** — Standalone WebSocket client
- **`soothe-sdk`** — Shared SDK for custom clients
- **`soothe-community`** — Optional community plugins
Install the main package:
```bash
pip install -U 'soothe[all]'
```
### Quick Start
**1. Configure your LLM provider**:
```bash
# Create config directory
mkdir -p ~/.soothe/config
# Copy minimal config template
cp config/config.minimal.yml ~/.soothe/config/config.yml
# Set your API key
export OPENAI_API_KEY="sk-..."
# or export ANTHROPIC_API_KEY="sk-ant-..."
# or export DASHSCOPE_API_KEY="sk-..."
# Edit config with your preferred models (optional)
vim ~/.soothe/config/config.yml
```
The minimal config contains just essentials: provider settings and model router. All other settings use sensible defaults.
**2. Run Soothe**:
**CLI Side**:
```bash
# Interactive TUI
soothe
# Single prompt
soothe -p "Research the top 5 Python web frameworks and create a comparison table"
```
**Daemon Side**:
```bash
# Start daemon server
soothe-daemon start
# Check daemon status
soothe-daemon status
# Stop daemon
soothe-daemon stop
```
**Command Reference**:
- `soothe` — Interactive client (TUI by default)
- `soothe -p "query"` — Single-prompt execution
- `soothe --help` — View all options
- `soothe-daemon start|stop|status|logs` — Daemon management
- `soothe-daemon doctor` — Health diagnostics
## Learn More
### 📚 Documentation
- **[Wiki](docs/wiki/)** - End-user guides organized by topic
- [Getting Started](docs/wiki/getting-started.md) - Installation and first steps
- [CLI Reference](docs/wiki/cli-reference.md) - Complete command documentation
- [Configuration](docs/wiki/configuration.md) - Environment variables and YAML config
- [Troubleshooting](docs/wiki/troubleshooting.md) - Common issues and solutions
- **[User Guide](docs/user_guide.md)** - Comprehensive usage guide with examples
- **[RFCs & Specs](docs/specs/)** - Technical specifications and architecture design
- [RFC-000](docs/specs/RFC-000-system-conceptual-design.md) - System conceptual design
- [RFC-200](docs/specs/RFC-200-agentic-goal-execution.md) - Execution architecture
- [RFC-600](docs/specs/RFC-600-plugin-extension-system.md) - Plugin system design
### 🛠️ For Developers
- **[CLAUDE.md](CLAUDE.md)** - Development guide for AI agents
- **[Implementation Guides](docs/impl/)** - Detailed implementation documentation
## License
MIT