Soleclaw

A self-evolving personal AI assistant. Instead of shipping fixed tools, soleclaw forges its own — the agent identifies what it needs, generates the code, and integrates it into its toolkit permanently.

Inspired by nanobot and openclaw. Built on claude-agent-sdk.

Why

Most agent frameworks extend capabilities through markdown skills that teach the agent how to chain built-in tools. Every invocation requires LLM reasoning through the same chain. Skills are knowledge, not capability.

Soleclaw's forge generates real executable code registered as first-class tools. The LLM's role shifts from multi-step orchestrator to single-step dispatcher — pick the right tool, pass the right arguments, done. All logic lives in the generated tool's code, not in the LLM's reasoning chain.

The tool library is model-agnostic. Swap Claude for another model and every tool, every piece of data continues to work.

Architecture

User (Telegram / Slack / CLI)
  → Channel Layer
    → SoleclawBridge
      ├── ContextBuilder → system prompt (identity, memory, skills, tools)
      ├── @tool functions → in-process MCP server
      └── ClaudeSDKClient → LLM calls + tool execution loop
    → Bus (OutboundMessage)
  → Channel → User

soleclaw/
├── core/           Bridge, context builder, bootstrap
├── tools/          MCP tool definitions + user tool library
├── forge/          Tool generation engine
├── memory/         Local backend + OpenViking (optional)
├── cron/           Scheduled tasks (cron/every/at)
├── skills/         SKILL.md loader
├── channels/       Telegram, Slack, CLI
├── bus/            Async message routing
├── config/         Pydantic config schema
└── cli/            CLI commands (typer)

~2900 lines of core code, 39 source files.

Setup

Requires Python 3.11+.

pip install soleclaw

# Configure (interactive wizard)
soleclaw configure

From source (requires uv):

git clone <repo-url> && cd soleclaw
uv sync --all-extras

Usage

# Run as gateway (Telegram, Slack, or both)
soleclaw gateway start

# Interactive CLI chat
soleclaw agent
soleclaw agent "hello"

See docs/Commands.md for the full command reference.

Channels

Telegram — bot listens for messages, replies in chat.

soleclaw configure telegram

Slack — watch channels via Socket Mode, reply in threads, react with emoji.

soleclaw configure slack

Requires a Slack app with Socket Mode enabled. The configure command prints a setup guide.

Forge — Tool Generation

When the agent identifies a missing capability, it invokes the forge:

1. Agent proposes a tool to the user
2. User confirms
3. forge_tool spawns a ClaudeSDKClient sub-session to generate code
4. Generated tool lands in ~/.soleclaw/tool-library/<name>/
5. Tool is immediately available via run_user_tool

Tool library structure:

tool-library/
  └── <tool-name>/
      ├── manifest.json    # name, description, parameters
      └── tool.py          # async def execute(args: dict) -> dict

All tool data is stored in a shared SQLite database (~/.soleclaw/data/store.db), so tools can cross-reference each other's data.

Roadmap

• OpenViking memory — Replace keyword-based memory search with OpenViking vector search. The backend code exists (memory/viking.py) but requires an ~/.openviking/ov.conf with embedding and VLM API keys. Once configured, memory_search upgrades from substring matching to semantic retrieval with auto-extraction from conversations.
• Memory consolidation — Periodic cron job to review daily logs and curate MEMORY.md (long-term facts the agent always sees in context).
• Multi-channel — Discord, WeChat channels.
• Tool sharing — Export/import tools between soleclaw instances.