convez.ai
Agente
ProvanceMedia

yodacode

ProvanceMedia/yodacode

Ver no GitHub
InicialPluginScore · de 0 a 100

Personal Claude-Code-powered chat agent for Slack, WhatsApp, and beyond

Instalação

$npx convez-ai ProvanceMedia/yodacode

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 dias
Versão
—
Issues abertas
1
Contribuidores
2

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 /yodacode in Slack (or ./quickstart.sh addkey on 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

FeatureDescription
De-rooted by defaultKeys live in a separate broker container; the agent never sees them.
Live streamingPlaceholder message updates in real time as Claude works.
Threaded repliesEvery reply in a thread. Old threads work forever (no aging).
Memory systemProactive memory with 4 typed categories, a daily consolidation cron, and FTS5 search. See Memory search.
Skill self-generationOpt-in reflector turns long conversations into reusable SKILL.md files. See Self-improvement.
Loop guardrailsRepeat-failure, no-progress, and iteration-cap detection. See Loop guardrails.
In-container cronsDeclarative YAML tasks run on their own timers — no host systemd. See Cron tasks.
Model fallbackSonnet to Haiku (configurable chain). Fail-fast on 529.
Slash commands/opus, /sonnet, /haiku <question> pick a model per thread; /yodacode shows help & setup.
Effort levelsReasoning depth (low to max) set globally, per cron, or per thread. See Effort levels.
Browser automationPlaywright for JS-rendered pages and screenshots (when the image includes it).
SubagentsTask tool for parallel work and context protection.
Stop commandType "stop" to kill an in-flight reply cleanly.
Web dashboardStatus, crons, live logs, file editing. Basic auth.
Auto-capabilitiesCAPABILITIES.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_EFFORT in .env. Empty uses the model's own default.
  • Per cron: add effort: xhigh to a task's YAML.
  • Per thread (sticky): say ultrathink or xhigh in any message, and that reply plus every later reply in the same thread runs at xhigh. Say xhigh off to 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>.md with numbered steps + frontmatter and appends a pointer to skills/INDEX.md (which is @-imported into the agent's persona).
  • Memory reflector asks "Did we learn a durable FACT here?" If yes, it appends a dated bullet to MEMORY.md under the right section, or writes a new memory/<slug>.md for 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 at claude.ai/settings/usage.
  • Personal use. Designed for one person on one server. Not multi-tenant.

Star History

Star History Chart

License

MIT

Ver o original no GitHub

Bom para

Relacionados