Personal-first AI assistant runtime
Telegram • Discord • WhatsApp

Explore setup guide »
Visit landing page »

Report Bug · Request Feature

yacb which stands for "yet another clawd bot", is a personal-first AI assistant runtime for day-to-day workflows. It focuses on predictable behavior across channels, reminders that actually fire, and a skills-first structure that keeps the core runtime straightforward.

• Scope 1 (Lean Reliability Plan) is completed as of 2026-02-23.
• Current routing model is deterministic tier_router (light / medium / heavy) with !tier override.
• Legacy !light, !heavy, !think are deprecated and replaced by !tier.
• WhatsApp integration is functional but still an active improvement area (self-chat/group behavior and access matching reliability).

yacb began as a de-bloating exercise on OpenClaw. The goal was to strip the complexity down for predictable personal use. Creating a personal AI companion has been a long-term goal, with earlier iterations built on LangChain before pivoting to a more modern, skills-first approach.

• OpenClaw ecosystem compatibility: skills and agent patterns can be reused across runtimes.
• Optional per-message tier routing (light / medium / heavy) with provider-aware auto selection of light/heavy models.
• Reminder confirmations are tied to actual cron registration (no success message if scheduling fails).
• Proactive updates support active-hour windows and empty-response suppression.
• Optional periodic security audits flag risky config states in runtime logs.
• Model fallback retries are limited to transient failures and stop on non-retryable errors.
• Multi-agent routing maps channel:chat_id to agent-specific behavior and workspace state.
• Session context now rehydrates from SQLite after runtime restarts.
• Prompt context is bounded for efficiency (history + memory/skills caps) to reduce token growth in long chats.

• Python 3.11+
• uv (runtime and dependency workflow)
• LiteLLM provider layer
• SQLite (FTS5) + file memory
• Telegram + Discord + WhatsApp channel adapters

OpenCode Zen note:

• Current opencode/* routing is designed for OpenAI-compatible /chat/completions models.
• Models that require /responses or /messages endpoints are not guaranteed with this adapter path.

1. Install dependencies: uv sync
2. Run setup: uv run yacb init
3. Start the bot: uv run yacb

Docker alternative:

1. Create config: cp config.yaml config.docker.yaml
2. Build image: docker compose build
3. Initialize config: docker compose run --rm yacb init config.docker.yaml
4. Start runtime: docker compose up -d (local CLI flow still uses config.local.yaml by default)

You can use OpenCode, OpenRouter or Google Gemini's free tier subscriptions by choosing them as providers rather than OpenAI or Anthropic.

• OpenCode Zen: pick one of the free-tier models.
• OpenRouter: pick a model tagged :free.
• Google Gemini: use the Gemini free tier from Google AI Studio.

In setup (uv run yacb init), choose one of these providers and select a free model in Step 3.

Tip: free models are great for onboarding testing, and casual day to day use. If you need more performance you can change models later without changing or affecting your workflow.

Full guide: SETUP.md
Command reference: COMMANDS.md

• Python 3.11+
• uv
• At least one provider API key
• At least one channel credential (Telegram, Discord, or WhatsApp)

1. Clone the repository.

   git clone https://github.com/zivhm/yacb.git
   cd yacb

2. Install base dependencies.

   uv sync

3. Optional extras.

   uv sync --extra dev

4. Run guided setup.

   uv run yacb init

5. Start runtime.

   uv run yacb

If needed use an explicit config path:

uv run yacb /path/to/config.local.yaml

1. Create config (first run only).

   cp config.yaml config.docker.yaml

   config.docker.yaml is the compose-specific config file. Keep using config.local.yaml for local uv run yacb ... workflows.

2. Build the container image.

   docker compose build

3. Run setup inside the container (interactive).

   docker compose run --rm yacb init config.docker.yaml

4. Start runtime.

   docker compose up -d

5. Follow logs / stop.

   docker compose logs -f yacb
   docker compose down

For full setup details, see SETUP.md.

# start setup
uv run yacb init

# run with default runtime config
# (prefers config.local.yaml, falls back to config.yaml)
uv run yacb

# run with explicit config path
uv run yacb /path/to/config.local.yaml

In chat:

hello
what's 2+2?
remind me in 20 minutes to stand up
what did we discuss about onboarding yesterday?

• Command reference: COMMANDS.md
• Setup/onboarding: SETUP.md
• Runtime details and changes: CHANGELOG.md
• Development and contribution workflow: CONTRIBUTING.md

• Improve observability around reminder/heartbeat delivery
• Add more operational docs and production hardening guides
• Expand container deployment hardening and production examples
• General prompt, logic, and performance optimizations based on usage patterns

See open issues for active proposals and known gaps:
https://github.com/zivhm/yacb/issues

Contributions are welcome.

• Read CONTRIBUTING.md
• Open a bug/feature issue first for larger changes
• Prefer skills-first additions when possible

• OpenClaw architecture patterns
• Implementation ideas inspired by other projects in the space
• Best README Template for structure inspiration
• Shields.io for badge assets

Distributed under the MIT License. See LICENSE.

This is a personal, work-in-progress project. It will probably grow based on my daily needs. Use it carefully and verify important actions before relying on them in real workflows. You are responsible for how you configure and use the runtime.