yodacode
ProvanceMedia/yodacode
Personal Claude-Code-powered chat agent for Slack, WhatsApp, and beyond
Instalação
npx convez-ai ProvanceMedia/yodacode1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
██╗ ██╗ ██████╗ ██████╗ █████╗ ██████╗ ██████╗ ██████╗ ███████╗
╚██╗ ██╔╝██╔═══██╗██╔══██╗██╔══██╗██╔════╝██╔═══██╗██╔══██╗██╔════╝
╚████╔╝ ██║ ██║██║ ██║███████║██║ ██║ ██║██║ ██║█████╗
╚██╔╝ ██║ ██║██║ ██║██╔══██║██║ ██║ ██║██║ ██║██╔══╝
██║ ╚██████╔╝██████╔╝██║ ██║╚██████╗╚██████╔╝██████╔╝███████╗
╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝
Your own Claude-powered assistant for Slack, running on your server.
Runs on your Claude subscription (Max recommended) — no API key, no per-request billing. One guided command installs everything; DM your bot a few minutes later.
What is this?
YodaCode is a self-hosted personal AI agent that lives on your own server and replies to you in
Slack. Every reply runs through Claude Code (claude -p), so the agent has real tools: Read,
Write, Edit, web search, browser automation, subagents, and a full Bash shell. It runs as two
Docker containers — a broker that holds your API keys, and the agent itself, which never
sees them (see Security).
It also remembers. A structured file-based memory system with daily consolidation and full-text search means the agent builds up context over time instead of starting cold every conversation. The full feature list is in the table below.
What you need
- A small always-on Linux server — a cheap VPS, cloud droplet, or home server. (A laptop that sleeps won't do; the bot needs to stay connected.) 1 GB RAM is enough; that's it for specs.
- Docker — if it's missing, the installer offers to install it for you.
- A Claude subscription — Max recommended, Pro works with tighter limits. The installer signs you in; no API key.
- A Slack workspace where you can add an app — the installer walks you through creating it.
You do not need Node, systemd, or any other tooling on the host — everything the bot needs is baked into the Docker image. Outbound HTTPS only; Slack runs over Socket Mode, so no inbound ports and nothing exposed to the internet.
Quickstart
git clone https://github.com/ProvanceMedia/yodacode.git
cd yodacode
./quickstart.sh
quickstart.sh is a fully guided, 6-step installer — no config files to edit, no prior tooling.
It installs Docker if missing, builds the image, signs you in to Claude (open a URL on your
laptop), lets you name your assistant and tell it about yourself, walks you through creating
the Slack app click-by-click (verifying each token live as you paste it), writes the config for
you, launches the stack, and prints your assistant introducing itself so you can see it working.
A few minutes later, DM your bot in Slack.
Adding API keys is optional and explained at the end. Re-running ./quickstart.sh offers
start-or-reconfigure.
On a 512 MB box the image build can stall — use 1 GB, or add swap first.
You don't need to be technical
You can edit files and write configs by hand, but you usually don't need to. The agent knows its own workspace. Just ask it in Slack:
- "Remember I prefer bullet points over paragraphs" → appends to its own memory.
- "Change your name to Jarvis" → edits its identity files.
- "Write a cron that checks my inbox every 30 minutes" → drops a task file in
cron-tasks/; the scheduler picks it up. - "Connect my GitHub" → it points you to
/yodacodein Slack (or./quickstart.sh addkeyon the server), because keys are added on the server, never pasted into chat.
Security: de-rooted by default
Your API keys never enter the agent. They live in a separate broker container that holds the vault and makes the authenticated calls; the agent container — the bot itself — runs as an unprivileged user with no service keys in its environment and reaches every API through the broker. So a prompt injection or a confused agent has nothing to leak: the keys are on the other side of a container boundary, enforced by the OS, not by a prompt rule. See docs/BROKER.md.
Day-to-day
Run these from the install folder on your server:
docker compose logs -f agent # watch the bot work
docker compose restart # apply config changes
docker compose down # stop it
docker compose exec agent bash # open a shell inside the agent
Adding an API key (GitHub, Stripe, Google, …): DM your bot /yodacode in Slack for the
walkthrough, or on the server run ./quickstart.sh addkey — it stores the key in the broker (the
agent never sees it) and reloads. The new host then shows up in the agent's CAPABILITIES.md.
Your workspace (memory, skills, cron definitions) is bind-mounted, so you can read and edit it
on the host. Set PUID/PGID in .env to your host user if you want those files owned by you.
Architecture
┌──────────────┐
│ Slack API │ (Socket Mode — no inbound ports)
└──────┬───────┘
│ real-time events
╔════════════════════▼═══════════════════════╗
║ agent container (unprivileged, no keys) ║
║ yoda.js ─ surfaces ║
║ ├─ dispatcher (policy + context) ║
║ ├─ claude-runner → claude -p (stream) ║
║ │ ├─ live status streaming ║
║ │ └─ model fallback (529 → Haiku) ║
║ ├─ stop-handler (kill mid-tick) ║
║ └─ scheduler (in-container crons) ║
╚════════════════════╤═══════════════════════╝
│ broker call (unix socket)
╔════════════════════▼═══════════════════════╗
║ broker container (holds the vault) ║
║ injects credentials, makes the API calls ║
╚════════════════════════════════════════════╝
Features
| Feature | Description |
|---|---|
| De-rooted by default | Keys live in a separate broker container; the agent never sees them. |
| Live streaming | Placeholder message updates in real time as Claude works. |
| Threaded replies | Every reply in a thread. Old threads work forever (no aging). |
| Memory system | Proactive memory with 4 typed categories, a daily consolidation cron, and FTS5 search. See Memory search. |
| Skill self-generation | Opt-in reflector turns long conversations into reusable SKILL.md files. See Self-improvement. |
| Loop guardrails | Repeat-failure, no-progress, and iteration-cap detection. See Loop guardrails. |
| In-container crons | Declarative YAML tasks run on their own timers — no host systemd. See Cron tasks. |
| Model fallback | Sonnet to Haiku (configurable chain). Fail-fast on 529. |
| Slash commands | /opus, /sonnet, /haiku <question> pick a model per thread; /yodacode shows help & setup. |
| Effort levels | Reasoning depth (low to max) set globally, per cron, or per thread. See Effort levels. |
| Browser automation | Playwright for JS-rendered pages and screenshots (when the image includes it). |
| Subagents | Task tool for parallel work and context protection. |
| Stop command | Type "stop" to kill an in-flight reply cleanly. |
| Web dashboard | Status, crons, live logs, file editing. Basic auth. |
| Auto-capabilities | CAPABILITIES.md is auto-generated from the broker registry + bin/ manifests so the agent never lies about what it can do. |
Configuration
The installer writes .env for you. To change something later, edit .env and
docker compose restart. See .env.example for the full list with documentation.
CLAUDE_CODE_OAUTH_TOKEN= # set by the installer (claude sign-in)
SLACK_BOT_TOKEN= # set by the installer
SLACK_APP_TOKEN= # set by the installer
YODA_DM_AUTHORIZED_USERS= # comma-separated Slack user IDs allowed to DM the bot
YODA_CLAUDE_MODEL= # primary model (empty = Claude Code default)
YODA_CLAUDE_FALLBACK_MODELS=claude-haiku-4-5
YODA_CLAUDE_EFFORT= # low|medium|high|xhigh|max (empty = model default)
BOT_NAME= # your assistant's name
USER_NAME= # what it calls you
PUID= # host uid to own bind-mounted workspace files (optional)
PGID=
Effort levels
Claude Code exposes a reasoning effort control (low, medium, high, xhigh, max), where
higher means deeper reasoning at the cost of more tokens per turn. YodaCode wires it in three ways:
- Global default: set
YODA_CLAUDE_EFFORTin.env. Empty uses the model's own default. - Per cron: add
effort: xhighto a task's YAML. - Per thread (sticky): say
ultrathinkorxhighin any message, and that reply plus every later reply in the same thread runs atxhigh. Sayxhigh offto drop back. A new thread starts at the default.
Notes: xhigh is supported on Opus only; other models clamp it to high, and Haiku ignores effort.
Each reply is a fresh claude -p, so thread stickiness is re-derived from recent thread history —
in a very long thread, just say the word again.
Adding a cron task
Scheduled tasks are YAML files run by the in-container scheduler — no host systemd, no shell
wrappers. Drop a file in cron-tasks/ and docker compose restart:
cp cron-tasks/_template.yaml cron-tasks/my-task.yaml
# edit: name, prompt, on_calendar (systemd OnCalendar syntax), optional model/effort/deliver
docker compose restart
The scheduler reads on_calendar, runs the prompt on schedule via cron-runner.js, and handles
optional Slack delivery and skill/memory reflection. Delete or rename a file to disable it. See
cron-tasks/README.md for the full schema. (You can also just ask the bot
to write one for you.)
Adding a tool
Drop a script into workspace/bin/ with a @yoda-tool manifest block at the top. On the next
restart, refresh-capabilities.py scans it and the agent sees it in CAPABILITIES.md. No code
edits.
#!/usr/bin/env bash
# @yoda-tool
# name: hello.sh
# summary: Say hello to a name.
# tags: example
# usage:
# hello.sh <name>
# examples:
# ./bin/hello.sh world
# @end
echo "hello $1"
Adding a surface
Create workspace/lib/surfaces/<name>.js implementing the surface contract (see lib/surface.js
for the interface). Add <name> to YODA_SURFACES in .env and docker compose restart.
Closed-loop self-improvement (opt-in)
Two background reflectors can run after any successful conversation that crosses a threshold
(default: ≥30 seconds OR ≥5 tool calls). Both spawn a separate detached claude -p (Haiku by
default, so it's cheap), look at the just-completed transcript, and decide whether to persist
anything:
- Skill reflector asks "Did we discover a reusable PROCEDURE here?" If yes, it writes
workspace/skills/<slug>.mdwith numbered steps + frontmatter and appends a pointer toskills/INDEX.md(which is@-importedinto the agent's persona). - Memory reflector asks "Did we learn a durable FACT here?" If yes, it appends a dated bullet
to
MEMORY.mdunder the right section, or writes a newmemory/<slug>.mdfor larger topics.
Both fire-and-forget (never block the reply) and rebuild the FTS5 index after writing. A nightly
skill-review cron dedupes near-identical skills, promotes frequently-used ones into a "Core"
section of INDEX.md, and archives stale ones.
Both are off by default. Opt in with:
YODA_SKILL_REFLECTOR_ENABLED=1
YODA_MEMORY_REFLECTOR_ENABLED=1
Loop guardrails
Every tick is wrapped by a tool tracker that watches the stream-json event stream and detects
three failure modes:
repeat_failure: the same tool + same input errored ≥2× in a row → warning in the placeholder.no_progress: the same tool + same input + same output ≥3× in a row → "may be looping" warning.iteration_cap: total tool_use count exceeded the budget (YODA_MAX_ITERATIONS_SLACK, default 60) → SIGTERMs claude and replaces the placeholder with "🛑 Iteration cap hit".
Per-run summaries persist to state/tool-runs.json for post-mortem. Disable with
YODA_GUARDRAIL_ENABLED=0.
Memory search
./bin/memory-search.sh "<query>" runs a SQLite FTS5 full-text search over MEMORY.md, every file
in memory/, and every file in skills/. The bot uses it to fetch just the relevant context for a
question instead of stuffing every memory file into every prompt.
Flags: --limit N (default 5), --scope active|index|skill|all, --type <feedback|project|user|reference>.
The index is rebuilt on startup and after the nightly memory-consolidate cron.
Important notes
- Quota usage. Each reply is one turn against your Max limit. Higher effort levels
(
xhigh/max) and cron tasks use more. Monitor atclaude.ai/settings/usage. - Personal use. Designed for one person on one server. Not multi-tenant.
Star History
License
MIT