
CludeGods
Always-on AI Gods that work inside Claude Code, and you can talk to them. Proactive workers, computer use (browser, terminal & files), real-time voice like J…
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up CludeGods (claude-plugin project) into my current project. Found on https://claudeers.com/cludegods Repo: https://github.com/AKamaly/CludeGods Homepage/docs: — Detected install method: claude-plugin → /plugin install cludegods@AKamaly/CludeGods Category: automation. Platforms: cli, api, desktop, web. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: active; community-verified: false. Confirm the source before running anything.
/plugin marketplace add AKamaly/CludeGods /plugin install cludegods@AKamaly/CludeGods
git clone https://github.com/AKamaly/CludeGods
// compatibility
| Platforms | cli, api, desktop, web |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | TypeScript |
CludeGods
Always-on Claude Code Gods that you can talk to.
Always-on AI Gods that work inside Claude Code.
Always-on proactive workers · Computer use: browser, terminal & files · Real-time voice, like Jarvis (RIP Iron Man) · Put any worker on a call, in its own voice · Bring workers into Slack · Spaces and Pages for projects
Built on Claude Code and VoiceMode. · Get started · How to use it · Overview · Architecture · Features · Safety · Changelog · Contributing
The app scene, a call with a barge-in, a permission approved with a click, and a scheduled worker checking in with drafts. A 14-second cut of the silent launch film; the film is an animated mockup of the real parts, not a screen capture.
Overview
CludeGods is a small set of parts that sit on top of Claude Code and
VoiceMode. You type /gods, a small call
card with the colleague god appears in the corner, and you talk to your Claude Code session the way you would to
someone sitting next to you. Over on the right, a Workers pane shows your standing worker
chats, each with a task box.
A toolkit, not a hosted product. Everything runs on your Mac. The only state is plain
files under ~/.voicemode/call/. Speech to text and text to speech run locally; the
transcript of what you say goes to Claude, the same as anything you type into the session.
Press play, then click the speaker icon: GitHub starts every video muted, and this one talks.
https://github.com/user-attachments/assets/f384d329-f26c-4d89-b912-9ed2e24fbf38
CludeGods in 54 seconds: a voice call with Claude, every step said out loud, a click to approve, a task for an always-on worker, and a worker on the call.
The parts:
godsskill: a live voice call with your Claude Code session. An always-on mic streams your words in, Claude answers out loud without blocking its own work, and you can cut in at any time.- CallPill: a floating macOS call card. The god on the call (the colleague, or the worker you put on) listens, thinks and talks with you, the line being spoken shows under it, and mic and stop buttons sit below. If you choose, it also shows permission prompts during a call, answered only by a physical click.
- Hooks:
narratesays each step out loud as it happens;permitcan route permission prompts to the pill (off by default: the app's own dialog handles them). - Workers pane mod: a pane beside the chat with your standing worker chats as cards, each one a god with its own voice and hours, live status, a task box, an outbox you approve with a click, and an Activity view of its last steps.
- Spaces pane mod and
pages: Markdown spaces and pages that you and your workers share. Workers save pages in the spaces you let them write, or leave drafts for your Approve if you prefer; Memory always waits for your Approve. guardhook: holds each worker to the tools you gave it: full by default, or read only, drafts only, or a list of tools.- Slack bridge: mention a worker in your own Slack workspace and it answers in the thread, through a local Socket Mode app with an allow-list.
cludegods: sets up voice, checks every part and fixes what is off, updates and uninstalls.
What it feels like
You type /gods. Claude says "I'm here. What's first?" You ask "Can you check why the
build broke this morning?" Claude says "Hmm, let me look," and while it reads logs you hear
"Reading the CI log." and "Searching the code." between your own questions. Halfway through
its answer you say "wait, not that one," and it stops talking and listens.
Long jobs go to helper agents that report milestones in a sentence. Anything outward, like an email or a post, lands in the chat as a draft. Claude reads it back in one sentence, and nothing goes out until you say a clear yes (or type it, if you set it that way).
In the Workers pane, Research is working and Scribe has been idle for ten minutes. You type a task into Scribe's box and press Enter.
Features
Hop on a call with Claude
/gods starts the ears (always-on capture with Silero VAD and Whisper), the mouth (a
non-blocking speech queue), and CallPill. The god on the call card moves through Listening, You, Thinking,
and talking, with the line being spoken as its caption. Talk over Claude and it stops: each partial transcript is checked while a line
plays, and if it is you, the speech is cut and your words go straight to the session.
|
The call card. Real-time voice, and you can cut in at any time.
Every step, said out loud
The narrate hook turns each tool call into a short spoken line ("Reading config.py.",
"Now I'm going to run the tests.") at most once every 6 seconds, only during a live call and
only in the call's own session. You hear what Claude is doing without watching the screen.
Keep always-on workers
Each worker is its own Claude Code chat with a name, a role, a god, a voice and its own hours. The Workers pane lists them as cards: the god animates while the worker is Working, a badge counts the drafts waiting for your yes, and Activity shows its last steps read from the transcript. Type a task into a card and press Enter to send it to that chat; Open jumps to it.
|
Workers connect to you through the pane: send a task, run on a schedule, collect drafts in an outbox, approve with a click.
Make them yours
Settings on every card: a name, one of six gods, a voice (Kokoro: af_heart, am_michael,
bf_emma and more), working hours, a tools preset, pause, and the Spaces it may write
to. It all lands in ~/.voicemode/call/workers.json, and each worker speaks its heads-ups
in its own voice.
|
Their names. Their voices. Their hours.
Permissions by click, never by voice
The mic hears the whole room, so voice never answers a permission prompt. By default the
prompt is the app's own dialog, exactly as without CludeGods. Set
approvals.permission_prompts to "pill" and, during a live call, CallPill shows the
request beside the call card with Deny and Allow, and a mouse click is the only thing that
answers it. A spoken "yes, go ahead" is ignored.
Outward actions, like sending an email, work differently: Claude writes the exact action in
the chat and reads it back in one sentence, and a clear spoken yes to that read-back counts.
Set approvals.outward to "typed" to require a typed yes. See the
Safety model.
|
A permission request on CallPill, with permission_prompts set to "pill". Only the click counts.
Workers that check in on their own
Give a worker a schedule, and the pane wakes it at that time: to run its charter if it
has one, or to check in on its role if not. It does its run, writes drafts and notes to an
outbox, and the card shows a 2 drafts badge. Each item that needs a yes gets Approve,
Change and Decline on the card: Approve tells the worker to go ahead with exactly that
draft, Change sends it back with your note, Decline tells it to drop it. Nothing from a
scheduled run goes out before you approve it. Details in Proactive workers.
|
Scribe runs Monday to Friday at 9:00 and leaves two drafts that need your yes.
Spaces and Pages
A Space is a folder of Markdown pages under ~/.voicemode/call/spaces/. The Spaces pane
lists them with search and nested subpages, shows a page, and has Ask a worker about this
page (send a question about it to any worker) and Open in editor. Workers read pages and save
them directly in the spaces you let them write. Set approvals.worker_publish to
"approve" and they save through pages draft instead: the draft shows up in their outbox
as "needs your yes", and only your Approve publishes it, with a revision check so a stale
draft never overwrites newer edits. A built-in Memory space holds the rules every
worker reads before it starts; it changes only through a draft you approve, whatever the
setting. Each call leaves a short receipt page in a calls space.
Put a worker on the call
Say "put me on with Scribe" during a call. CallPill switches to Scribe's god and name, your words go to Scribe's chat, and Scribe answers out loud in its own voice. "Back to you" returns the call to Claude. Names must match a worker exactly; Claude asks if it is unsure.
Bring workers into Slack
skills/gods/bridges/slack/ is a local Socket Mode Slack app, so it needs no public
URL. Mention the app or DM it, optionally with a worker's name first ("@CludeGods scribe
draft the release note"), and the message lands in that worker's chat; the reply goes back
into the same thread. Only allow-listed users and channels get through, replies can only go
to threads that came in that way, and tokens live in your keychain. Setup, the app manifest,
and what leaves your Mac: bridges/slack/README.md.
Microsoft Teams is not supported yet.
Each worker gets only the tools you give it
A worker has its chat's full tools unless you add a restriction in its Settings. The
guard hook checks every tool call a worker makes against its preset: read (read and
search only), drafts (read, plus writing its own outbox and page drafts), full, or an
explicit list of tools. A denied call goes back to the worker with the reason, so it can
draft instead. Publishing a page, editing the registry, and approving its own drafts are
never open to a read or drafts worker. New workers start with full;
workers.default_tools in config.json changes that.
Local voice
Whisper (speech to text), Silero VAD (voice activity), Kokoro through mlx-audio (the voice), and CallPill all run on your Mac, managed by VoiceMode. Your audio stays on the machine. The transcript of what you say goes to Claude as part of the session, like anything you type.
|
MIT licensed. The voice stack runs locally; the session itself still talks to Claude.
Get started
Install (macOS on Apple Silicon)
You need the Claude desktop app with Claude Code, plus git and python3 (the Xcode command
line tools have both: xcode-select --install).
One line
Paste this into Terminal:
curl -fsSL https://raw.githubusercontent.com/AKamaly/CludeGods/main/bootstrap.sh | bash
It clones CludeGods to ~/.cludegods/src, installs the skills, the hooks, CallPill and the
Workers and Spaces panes, then checks everything. It backs up what it replaces and is safe to
run again. Then:
- Restart the Claude app (quit it fully, then open it again).
- Type
/godsin any chat. The Workers and Spaces buttons are in the chat footer; press Workers (or type/workers) to open the pane, which starts on a Welcome view with three first steps. It never opens by itself.
Voice is optional
Workers and Spaces work without it. Voice is what lets you talk to Claude out loud: local Whisper, Kokoro through mlx-audio, and Silero VAD, all managed by VoiceMode. It needs Homebrew, downloads a few GB of speech models, and takes a few minutes. Add it whenever you like:
- type
/gods: with no voice yet, Claude says what voice needs and sets it up on your typed yes, then starts the call; - or press Enable voice on the Workers pane's Welcome view (Show on its Getting started bar brings Welcome back);
- or run
~/.claude/skills/gods/bin/cludegods setup voicein Terminal.
Or install with voice from the start:
curl -fsSL https://raw.githubusercontent.com/AKamaly/CludeGods/main/bootstrap.sh | bash -s -- --voice
In Terminal, the setup shows what it will install and asks first. Run it again and it skips
what is already done. It ends with a short spoken test and a mic check. AirPods or other
Bluetooth output? Add --bluetooth-patch.
Something off? ~/.claude/skills/gods/bin/cludegods doctor checks every part and says
how to fix what is not right (--fix <id> runs the fix). The Workers pane shows the same
checks, with a button for each fix. docs/TROUBLESHOOTING.md
explains each one.
Or let Claude install it
Copy this, paste it into a Claude Code chat, and press Enter. Claude installs CludeGods, asks you about voice on the way, and tells you when it is ready.
Install CludeGods for me from https://github.com/AKamaly/CludeGods and get it running.
I'm on a Mac with Apple Silicon and the Claude desktop app.
1. Run the one-line installer:
curl -fsSL https://raw.githubusercontent.com/AKamaly/CludeGods/main/bootstrap.sh | bash
It installs CludeGods without voice (the lite install), adds the Workers and Spaces
panes, and checks everything. If it stops early, tell me why in a line or two and stop.
2. Run ~/.claude/skills/gods/bin/cludegods doctor and tell me in a few lines what is
installed and anything that failed. For a failed check with a fix, ask me first, then
run the fix line it prints.
3. Ask me if I want voice now, to talk to Claude out loud (local speech models, a few GB,
a few minutes, needs Homebrew). On a yes, ask if I use AirPods or other Bluetooth
headphones, then run ~/.claude/skills/gods/bin/cludegods setup voice --yes, adding
--bluetooth-patch if I said yes. It takes a few minutes, so run it in the background
where no timeout cuts it off. It ends with a spoken test line: tell me before it starts
to say a few words when I hear it. Then tell me what each step did. On a no, tell me I
can add voice later: /gods offers it, and so does Enable voice in the Workers pane.
4. Finish by telling me to restart the Claude app once, then type /gods in any chat. The
Workers and Spaces buttons appear in the chat footer.
Or step by step
git clone https://github.com/AKamaly/CludeGods.git
cd CludeGods
./install.sh
./install.sh --voice adds voice, --bluetooth-patch fixes crackling on AirPods and other
Bluetooth output (upgrading VoiceMode removes it, so run it again after), and --skip-pill
skips CallPill. The installer copies the gods and spaces skills, with the cludegods
CLI, into ~/.claude/skills/, installs CallPill (built here when the Xcode tools are
installed, else the prebuilt app from the latest release, signed on your Mac), adds the hooks
to ~/.claude/settings.json, and creates ~/.voicemode/call/ with your settings in
config.json. The defaults suit one developer on their own Mac;
config/config.example.json explains every key, and the
installer never overwrites your copy. It backs up anything it replaces and is safe to run
again after a git pull.
Then the panes. In a terminal session of Claude Code:
/plugin install workers-pane --marketplace AKamaly/CludeGods
/plugin install spaces-pane --marketplace AKamaly/CludeGods
/plugin install inbox-relay --marketplace AKamaly/CludeGods
Answer y to add the marketplace and press Enter for the user scope. inbox-relay is only
needed for Slack. In the desktop app, where /plugin does not run: click + next to the
prompt box, then Plugins, Add marketplace with AKamaly/CludeGods, and add each
plugin. ~/.claude/skills/gods/bin/cludegods doctor --fix install-panes does the same from
Terminal. Restart the app once, then type /gods in any chat.
Manual install (what the installer does, step by step)
-
The skills and the pill:
mkdir -p ~/.claude/skills cp -R skills/gods skills/spaces ~/.claude/skills/ scripts/install-pill.sh ~/.claude/skills/gods/bin -
The hooks: merge
config/settings.example.jsoninto~/.claude/settings.json, keeping any hooks you already have. It registersnarrateandguardonPreToolUseandpermitonPermissionRequest. -
The state folder:
mkdir -p ~/.voicemode/calland an empty registry,{"workers": []}, in~/.voicemode/call/workers.json.config/workers.example.jsonshows every field a worker can have. Copyconfig/config.example.jsonto~/.voicemode/call/config.jsonfor the settings. -
Voice (optional). VoiceMode and its local services (needs uv:
brew install uv):uvx voice-mode-install voicemode service install mlx-audio voicemode service install whisper voicemode whisper model large-v3-turbo voicemode service enable whisper voicemode service enable mlx-audioThen Silero VAD into the VoiceMode environment:
VM_PY=~/.local/share/uv/tools/voice-mode/bin/python uv pip install --python "$VM_PY" onnxruntime mkdir -p ~/.voicemode/models curl -L -o ~/.voicemode/models/silero_vad.onnx \ https://github.com/snakers4/silero-vad/raw/master/src/silero_vad/data/silero_vad.onnxAnd the Bluetooth patch, if you want it:
SITE=$("$VM_PY" -c 'import voice_mode, os; print(os.path.dirname(voice_mode.__path__[0]))') patch -d "$SITE" -p1 --dry-run < patches/voicemode-mouth-bluetooth.patch && \ patch -d "$SITE" -p1 -b < patches/voicemode-mouth-bluetooth.patch -
Working on a mod instead of installing it: start Claude Code with
--plugin-dir /path/to/CludeGods/mods/workers-pane(one flag per mod), or list the folders inCLAUDE_CODE_PLUGIN_DIRS.
Update and uninstall
cludegods lives at ~/.claude/skills/gods/bin/cludegods; it is not on your PATH, so type
the full path, or add alias cludegods=~/.claude/skills/gods/bin/cludegods to ~/.zshrc.
- Update:
~/.claude/skills/gods/bin/cludegods updatepulls the source you installed from, runsinstall.shagain with the same options (voice stays once it is set up), updates the three panes, and lists what changed. Restart the Claude app afterwards. - Uninstall:
~/.claude/skills/gods/bin/cludegods uninstall, or./uninstall.shfrom the source folder (~/.cludegods/srcafter the one-line install). It backs everything up to~/.claude/cludegods-backups/first, then removes the skills (with the CLI and CallPill), its own hooks insettings.json(yours stay), and the three panes. Your workers, spaces and settings in~/.voicemode/callgo too, once you typedelete;--keep-datakeeps them. VoiceMode stays; it has its own uninstaller. - Coming from 0.4 or earlier:
/colleagueis now/gods. In your clone, rungit pull && ./install.shonce: it moves the oldcolleagueskill to~/.claude/cludegods-backups/and points the hooks and worker instructions atskills/gods. Then~/.claude/skills/gods/bin/cludegods updatebrings the panes up to date, and from then on it is the only command you need.
How to use it
The call
- First call: if voice is not set up yet,
/godssays what it needs (local speech models, a few GB, a few minutes, nothing leaves your Mac) and sets it up on your typed yes, then starts the call. - Start: type
/gods, or say "let's talk" in a chat. Claude starts the mic, the voice and CallPill, and says "I'm here. What's first?" Then just talk. Calls run best on Haiku at low effort, and heavier work goes to Sonnet or Opus helpers by itself; if the chat is on another model, Claude tells you once a day which menu choice to pick./godsin another chat moves the call there, and the first chat steps back. - Cut in any time: talk over Claude and it stops and listens.
- Push to talk: right-click the pill's mic button and choose Push to talk (or run
~/.claude/skills/gods/bin/call mode talk;call mode openswitches back). The mic then stays off until you press the mic button or runcall talk, and closes after your turn, or after about 10 seconds of silence. A second press closes it at once, and a press also cuts Claude's speech. - Mic key:
~/.claude/skills/gods/bin/call micis one key for both modes: with push to talk it is your talk key, with the open mic it mutes and unmutes. To put it on a key, open the Shortcuts app, make a new shortcut with a Run Shell Script action running that command, then open its details and choose Add Keyboard Shortcut. The first run asks you to allow scripts (Shortcuts, Settings, Advanced, Allow Running Scripts). - Tips: once a day the call may say which model menu choice is fastest and, on laptop
speakers, that headphones make cutting in work better.
call tip model --neverorcall tip headphones --neverturns one off. - Something off?
~/.claude/skills/gods/bin/call statusshows the voice and Whisper services, the mic mode, what the ears last heard, and whether a listener is armed.cludegods doctorchecks the whole install, and docs/TROUBLESHOOTING.md covers no sound, a silent mic, echo and more. - CallPill shows who you are talking to and what they are saying. Mic mutes you (capture really stops); with push to talk it is the talk button (Press to talk, One sec, Go ahead). Stop cuts the speech and stops the current work and its helpers. It opens on the screen you are using and remembers where you put it on each screen. Drag it to move it, scroll or pinch to resize, and use the arrows to fold it down to just the god and the buttons.
- Sending and posting: before anything outward (an email, a post, a delete), Claude
puts the exact action in the chat and reads it back in one sentence. Say "yes, send it" to
go ahead. Set
approvals.outwardto"typed"to require a typed yes instead. - Permissions: when Claude asks to run something, the app's own dialog asks, as usual.
Set
approvals.permission_promptsto"pill"to get a card beside the pill with Deny and Allow during a call. Only your click answers; a spoken yes never does. - Hang up: say "that's it" or "end the call". A short summary of the call is saved as a page in the Calls space.
Workers
A worker is a standing Claude Code chat with a job. It keeps its context between tasks, has its own god, voice and hours, and is held to the tools you allow.
- First run: with no workers yet, the Workers pane (the Workers button in the
footer, or
/workers) opens on Welcome, with three one-click steps: Create your first worker, Write your first Memory rule (it opens Memory in the Spaces pane on a new rule), and Try a voice call (it puts/godsin your prompt box, or offers Enable voice while voice is not set up). A Getting started · 1 of 3 done bar stays on top until you finish or dismiss it. - Create one: + New worker offers six ready-made workers: Inbox triage, Daily brief, Repo watcher, Research, Release notes and Meeting prep. One click makes its card with hours and instructions; press Enter on the request it puts in your prompt box to start its chat (Start chat on the card asks again). Blank worker lets you name one yourself.
- Needs you: everything waiting on you in one list, each with its button: drafts for your yes (Approve, Change, Decline), permission requests on the call card (Open), scheduled runs that did not go through (Retry), and setup problems (their fix). Needs you · N in the header opens it, and the footer shows how many.
- Health strip: Voice, Listening and Workers at a glance, from
cludegods doctor. A red or amber problem shows a button that fixes it, like Restart Whisper or Install panes, and Check checks again. docs/TROUBLESHOOTING.md explains each one. - Give it a task:
- type into its Ask field and press Enter,
- press Open and talk to it in its own chat,
- or on a call, say "new task for Scribe: …". Claude passes it on and tells you when it reports back. "Tell Scribe and Research to …" reaches both.
- Talk to it directly: during a call, press Talk to Scribe on its card, or say "put me on with Scribe". The pill switches to Scribe's god, and Scribe answers in its own voice. Back to Claude, or "back to you", hands the call back.
- Make it yours: Settings on the card: name, god, voice, When it works (its hours), What it can do (Can do anything, or restrict it to Can draft or Can read), pause, and which Spaces it may write to.
- Let it work on its own: give it hours under When it works. At that time it wakes,
runs its Instructions (its
charter, see Proactive workers) or, without them, checks in on its role, and leaves what it found for you. - Approve: anything a worker wants to send or post waits as "needs your yes", on its card (Needs you · N) and in the Needs you list. Approve tells the worker to go ahead with exactly that; Change sends it back with your note on what to revise; Decline tells it to drop it. Nothing outward happens before your Approve, or your yes in its own chat.
- Today: the Today button shows the Needs you list, an Ask all field, and what each worker did since midnight.
- Activity shows its last steps; Delete (two presses) archives the chat.
Spaces
Spaces are folders of pages you and your workers share: a small wiki for your projects.
Open them with the Spaces button in the footer, or /spaces-pane.
- Memory: rules every worker reads before it starts ("write in my voice", "ask before sending anything"). An empty Memory offers starter rules you add with one press, then edit to fit you.
- Notes: a general space for pages, and where workers may save by default.
- Calls: a summary page for each call.
- + New page takes a title and a few lines right in the pane; Create and open in editor opens the file for the rest. Press Open › on a space or a page to go in. On a page: Ask a worker about this page, Open in editor, New page, New subpage.
- Workers save pages in the spaces you let them write. Set
approvals.worker_publishto"approve"and they draft instead: the draft shows in their outbox, and the page lands only when you press Approve. Memory always works that way.
Slack (optional)
Mention your workers in your own Slack workspace and they answer in the thread. It needs a Slack app you create in a few minutes; setup and what leaves your Mac are in skills/gods/bridges/slack/README.md.
Waiting sessions (optional)
CallPill can list sessions waiting on you. It reads ~/.voicemode/call/pending/*.json,
one record per session:
{"session_id": "…", "at": 1767268800.0, "title": "Fix the build", "message": "Waiting for approval",
"link": "claude://claude.ai/epitaxy/local_…", "transcript_path": "…", "cwd": "…"}
Write these from your own Notification hook if you want the list. Open only ever opens a
claude:// session link; there is no Allow in that list.
Architecture
flowchart LR
mic([Microphone]) --> ears
subgraph VoiceMode["VoiceMode (local services)"]
ears["ears: voice_mode.listen<br/>Silero VAD + Whisper large-v3-turbo"]
mouth["mouth: voice_mode.mouth<br/>mlx-audio Kokoro (Kokoro-FastAPI fallback)"]
end
ears -- "heard_*.jsonl" --> listen["listen.py<br/>echo gate + barge-in"]
listen -- "USER: ... lines" --> monitor["Monitor tool"]
monitor --> session["the call session<br/>(Claude Code, gods skill)"]
session -- "call say" --> mouth
mouth --> spk([Speakers / headphones])
listen -. "call hush on barge-in" .-> mouth
session -- "PreToolUse" --> narrate["narrate hook"]
narrate -- "call say" --> mouth
session -- "PermissionRequest" --> permit["permit hook"]
permit -- "permit/<id>.json (pill mode)" --> pill["CallPill"]
pill -- "click writes <id>.answer" --> permit
ears -- "heard log (state)" --> pill
pill -- "mute / stop" --> session
pane["Workers pane mod"] <--> reg[("~/.voicemode/call/workers.json")]
session <--> reg
pane -- "send task / open" --> workers["worker chats"]
pane -- "requests/*.json" --> listen
session -- "start_session / SendMessage" --> workers
pane -- "scheduled wake / Run now" --> workers
workers -- "outbox/*.jsonl" --> pane
workers -- "status/*.json, runs/*.jsonl" --> pane
pane -- "outbox-say" --> mouth
workers -- "PreToolUse" --> guard["guard hook<br/>tools preset per worker"]
guard -. "reads presets" .-> reg
guard -. "reads approvals" .-> cfg[("~/.voicemode/call/config.json")]
workers -- "pages new / draft" --> store[("spaces/*.md")]
pane -- "Approve: pages publish" --> store
spacespane["Spaces pane mod"] <--> store
spacespane -- "Ask a worker" --> workers
slack([Slack]) <--> bridge["Slack bridge<br/>Socket Mode, allow-list"]
bridge -- "inbox/*.jsonl" --> relay["inbox-relay mod"]
relay -- "hand the message over" --> workers
workers -- "bin/reply" --> bridge
Everything runs on your Mac. The only state is plain files under ~/.voicemode/call/.
Components
skills/gods/bin/call
The plumbing, one shell script. call start launches the ears (always-on capture with
Silero VAD and Whisper), the mouth (a non-blocking speech queue), and the pill.
call say "text" returns at once and lines queue in order; call say --now cuts in.
call hush, call mute, call unmute, call stopwork, call stop (--now cuts the last
line), call status. Push to talk: call talk opens the mic for one turn, call mode open|talk switches the mode, and call mic is one key for both (talk, or mute and unmute).
call start --greet "text" speaks the greeting as soon as the voice is up; --model NAME
names the chat's model for the once-a-day model tip. call start exits 3 when the local
voice is not installed and 4 when it is installed but its services do not answer; call setup-voice installs it in the background (cludegods setup voice --yes) and prints
SETUP: progress lines. call tip model|headphones --never turns a tip off. Lines follow the
Mac's sound output when it changes mid-call. Settings by environment: CALL_VOICE (default
af_heart), CALL_SPEED, CALL_OUTPUT_DEVICE (pin one output), CALL_SAY_MAX_WORDS
(default 45), CALL_STOP_WAIT_S (default 8), CALL_SILERO_THRESHOLD, CALL_SILENCE_S,
CALL_MIC_DEVICE, VOICEMODE_PY. ~/.voicemode/call/config.json may set user_label, the
label your lines carry (default USER), and "call": {"mic": "talk"} for push to talk.
skills/gods/bin/cludegods
Sets up, checks, updates and removes CludeGods; Python 3.9+ standard library only.
setup voice [--yes] [--bluetooth-patch] runs six steps that each skip when already done:
Homebrew and uv, VoiceMode, its services, Silero VAD, the Bluetooth patch, and a spoken
self-test with a mic check. setup vad and setup bluetooth run one step. doctor prints
one line per check; doctor --json prints the object the Workers pane reads,
{"version", "voice_installed", "checks": [{"id", "label", "ok", "severity", "detail", "fix", "fix_label"}]}; doctor --fix ID runs one repair (each one is in
docs/TROUBLESHOOTING.md). update pulls the source recorded in
~/.voicemode/call/install.json, runs install.sh again with the same options and updates
the panes. uninstall [--keep-data] [--yes] backs up first, then removes. version prints
the installed version.
skills/gods/bin/listen.py
Runs under Claude Code's Monitor tool and turns the ears' log into one line per event:
USER: …, USER (over you): …, EARS: down, EARS: muted, PANE: …, CALL: moved (the
call went to another chat). Its jobs:
- Echo gate. On laptop speakers the mic hears Claude's own voice and there is no echo canceller. A turn whose audio starts while Claude is speaking has Claude's words stripped (loosely matched, because the echo comes back garbled), and only a real remainder gets through. On headphones nothing is stripped.
- Barge-in. While a line is playing, each partial transcript is checked at once. If it is you, the mouth is cut and your words go to the session without waiting for the turn to end.
- Catch-up. The Monitor expires every 30 minutes. The listener keeps a cursor per call,
written when it is stopped too, so a re-armed listener delivers what was said while none
ran, as
USER (earlier, HH:MM, …): up to 30 lines, with any older turns counted in one line. It also reports a Stop, mute, focus or mic switch made while it was down.
listen.py --selftest runs the gate against synthetic logs; --replay FILE runs a real
log through it and prints every decision; --replay-rearm FILE checks a real log for lost
or doubled turns across expiries.
skills/gods/bin/narrate
A PreToolUse hook. During a live call, and only in the call's own session, it turns the
tool call into a short spoken line ("Now I'm going to run the tests.", "Reading
config.py.") at most once every 6 seconds. Standard library only, always exits 0, never
blocks a tool.
skills/gods/bin/permit and CallPill
permit is a PermissionRequest hook. By default (approvals.permission_prompts is
"app") it exits at once with no output and the app's own dialog handles the prompt. With
"pill", and only while a call is live and CallPill runs, it writes the request to
~/.voicemode/call/permit/<id>.json and waits up to 50 seconds for <id>.answer. CallPill
shows the request in a card beside the call card with Deny and Allow. A mouse click is the
only thing that writes the answer. On a timeout the hook prints nothing and the normal
in-app dialog takes over. permit --selftest runs both modes.
CallPill (pill.swift) is a native AppKit app with no dependencies. The god is a sprite
strip from skills/gods/bin/gods/ stepped on a CALayer (about 1.5% CPU), mapped to
the call: Listening is idle, You is listen, Thinking is work, Claude talking is talk, and a
finished reply plays one happy loop. ~/.voicemode/call/focus names the worker on the
call, and the card switches to that worker's god and name. Light and dark follow the
system. Mic and stop buttons are always visible; with push to talk the mic button is the
talk button (Press to talk, One sec, Go ahead), and a right-click on it switches modes. A
compact mode folds the card to the god and the buttons; scroll or pinch to resize. It opens
on the screen under the mouse, at the spot you last dragged it to on that screen, and comes
back if its display goes away. It can also list sessions waiting on you from
~/.voicemode/call/pending/*.json with an Open button per row (see
Waiting sessions). pill --snapshot out.png draws every
state into one image without opening a window; pill --selftest checks the state rules and
the placement.
|
Every CallPill state from pill --snapshot: the call card, the permission card, Scribe on the call, and the waiting list.
mods/workers-pane
A Claude Code mod (plugin with a hooks module) for the desktop app. It draws a Workers pane
from ~/.voicemode/call/workers.json: one card per worker with an animated SVG avatar,
its status (● Working · 4m, Idle, ■ Stopped, ▲ Stopped on an error, ◌ No chat yet),
a task box that sends straight to that chat, and a two-press Delete; the name opens the
chat. Workers with hours also get a schedule and Run now (Check in when there is no
charter), and every worker has an outbox feed (see Proactive workers).
"+ New worker" (one of six templates, or Blank worker) writes the worker's entry at once
and puts a Create worker: … request in your prompt box for your own Enter, because the app
refuses to start sessions from automated events; a template's entry records template: <id>. With no workers it opens on a Welcome view, and keeps first-run progress in
~/.voicemode/call/onboarding.json. Needs you gathers outbox items waiting for a yes,
permission requests in permit/, wakes that did not go through, and cludegods doctor
problems. The health strip runs cludegods doctor --json at most once a minute while the
pane shows, and its buttons run doctor --fix. A Workers · N launcher sits in the footer
(with "N need you" beside it while anything waits), and a Today · N button opens the Today
view. All paths are resolved from $HOME at runtime.
The mod runs in every chat, so it also runs in each worker's own chat. There it finds its
worker in the registry (by the desktop's id for the chat, its transcript name, or the
standby prompt it started with), keeps the entry's transcript up to date, writes
status/<key>.json as each turn starts and ends, and appends one line per finished turn to
runs/<key>.jsonl. The card's status and the Today view read those. A working report
with no sign of life for 15 minutes counts as stale.
The card's Settings view writes god, voice, hours, tools, paused and spaces
back to the worker's registry entry and keeps every key it does not know. The outbox lists
items that need a yes with Approve, Change and Decline; decisions (approved, declined,
or changes with your note) go to outbox/<key>.decisions.jsonl. The + New worker form
presets its tools from workers.default_tools in config.json, and "Make this the
default" writes that key, keeping every other key in the file. Activity shows the last ten tool steps from the worker's
transcript. hooks/gods.ts draws the six gods as SVG (animated with SMIL while working).
tsconfig.json only extends .claude-plugin/types/tsconfig.json, which Claude Code
generates when it loads the mod. It is there so your editor and tsc type-check the mod;
the generated types are not committed.
mods/spaces-pane and skills/gods/bin/pages
pages is a standard-library Python CLI over ~/.voicemode/call/spaces/<space>/<page>.md
(front matter: title, created, updated, by, parent): spaces, mkspace,
list, show, new, draft and publish. draft writes spaces/.drafts/<id>.md and
the matching outbox item; publish refuses a draft whose page changed since it was made
(exit 3) and a space the worker may not write (exit 4), and marks the draft's outbox item
approved. new --worker K is refused (exit 4) for Memory, and for every worker when
approvals.worker_publish is "approve". The Spaces pane mod draws the
library, the page view, Ask a worker, and a footer launcher. Other panes open it on a space
by writing {"at": <ms>, "space": "<slug>", "action": "open" | "new-page"} to
~/.voicemode/call/open-spaces (new-page opens the new-page form); a plain touch opens it
as it is. skills/spaces/SKILL.md tells workers how to use it.
skills/gods/bin/guard
A PreToolUse hook. It maps the hook's session to a worker through the registry's
transcript, and holds that worker to its tools preset. Sessions that are not workers,
and workers without a preset, pass untouched. For every worker it also applies
approvals.worker_publish to pages new|publish|mkspace, refuses a worker publishing a
Memory draft, and requires a worker's own --worker key on pages new|draft. A missing or
invalid config.json means the defaults. It fails open on its own errors and logs to
~/.voicemode/call/guard.log. guard --selftest runs its cases.
skills/gods/bridges/slack, mods/inbox-relay, bin/reply, bin/bridge
The bridge daemon (Python, slack_sdk in its own uv venv) writes allowed messages to
~/.voicemode/call/inbox/<worker>.jsonl. The inbox-relay mod hands each one to the
worker's chat. The worker answers with bin/reply <id> "text", and the bridge posts it in
the thread it came from. bin/bridge start|stop|status|log runs the daemon.
art/ and scripts/render-gods.mjs
art/gods.js is the source of the six gods (colleague, research, scribe, scout, sales,
herald) and their states (idle, talk, listen, work, happy). render-gods.mjs renders the
sprite strips CallPill animates (skills/gods/bin/gods/).
patches/voicemode-mouth-bluetooth.patch
A small diff against VoiceMode's voice_mode/mouth/output.py: play at the output device's
native sample rate (48 kHz on AirPods) with continuous upsampling, and open the stream at
high latency. Without it, Bluetooth outputs crackle. VOICEMODE_MOUTH_LATENCY overrides
the latency.
skills/gods/design/
orb.html is the WebGL orb the first CallPill used; workers.html is the pane mockup. Open
either in a browser.
Proactive workers
A worker can run on its own and report back instead of waiting for a task. A schedule
alone is enough; a charter says what each run does (see the inbox worker in
config/workers.example.json):
charter(Instructions, in the pane): the worker's standing instructions, limits included. A worker made from a template comes with them. For example: each run, read new replies, draft follow-ups to the outbox, send nothing you have not approved. The card never shows it; every wake sends all of it. With nocharter, each wake asks the worker to check in on itsrole.schedule: when it runs. Once a day:{"days": "mon-fri", "time": "09:00", "tz": "UTC"}. Or every few hours, within optional active hours:{"days": "mon-fri", "every": "3h", "from": "09:00", "to": "18:00", "tz": "UTC"}(everyis1h,2h,3h,4h,6hor12h).daystakes a range (mon-fri,sun-thu,fri-mon), a list (mon,wed,fri) ordaily;tzis any IANA zone. The card's hours chip readsMon to Fri · 9:00orEvery 3h · 9:00-18:00, and you can set it under When it works in the card's Settings.
The pane is the scheduler. At the scheduled time the Workers pane sends the worker's
own chat a wake message carrying its charter (or its role). It has to be the pane: the only local thing
that can put a message into an existing desktop chat is a mod's $.session.send. A
launchd job or cron has no way into a chat, and a scheduled task starts a new session
instead of waking the one that holds the worker's context. Each wake claims
~/.voicemode/call/wakes/<key>-<date> with an atomic mkdir, so a worker is woken once a
day (or once per slot, for an every-few-hours schedule) however many sessions run the pane;
after a gap only the latest missed slot fires. A delivered wake leaves result.json in its
claim. One that is not delivered (the chat is not running yet) gives its claim back and
writes wakes/<id>.retry for every pane to honour, so however many panes run, it is
retried once every 10 minutes. A claim left without a result for 10 minutes (its pane
closed mid-send) is taken over once.
Run now (or Check in, without a charter) on a card sends the same wake at once.
Each worker's own chat reports on itself in ~/.voicemode/call/status/<key>.json and
runs/<key>.jsonl, and keeps its transcript in the registry up to date.
The outbox. Every wake tells the worker to append one JSON line per item to
~/.voicemode/call/outbox/<key>.jsonl, and to send, post or change nothing outward during
the run:
{"id": "ob_3f9c1a2b7d4e", "at": "2026-01-05T09:04:00Z", "kind": "draft",
"title": "a reply to the venue about Friday", "body": "Hi, Friday works for us...",
"to": "[email protected]", "needs_approval": true}
kind is draft (something outward, needs_approval: true), note (a finding), or page
(a Spaces draft); an email draft may add a subject, which the card shows. The card's
badge counts the items still waiting for a yes, and Outbox lists them with their
recipient, age and first lines. The pane itself never sends anything: Approve passes your
go to the worker's chat, which then acts on exactly that draft. Change sends the
worker your note on what to revise, and it appends a revised item; the old one leaves the
list once the chat has the note.
The spoken heads-up. Each new outbox line is toasted in the app. During a live call,
skills/gods/bin/outbox-say also speaks one line for it ("Inbox drafted a reply to
the venue about Friday"), once per line, however many panes saw it.
Approvals. Approve on the card, or open the worker's chat, edit the draft there and
reply yes. On a call, a spoken yes counts only as a clear answer to a one-sentence read-back
of the exact action, and never with approvals.outward set to "typed"; see the
Safety model.
Limits:
- The desktop app must be open. The pane runs inside it; nothing wakes a worker while it is closed.
- A wake missed while the Mac sleeps or the app is closed fires later the same day, as soon as the pane polls again.
- A day missed entirely is skipped, not replayed.
Safety model
The mic hears the whole room: a video, a phone call, another person. The design assumes it
will mishear. The defaults suit one developer on their own Mac. Each stricter rule is one
setting in ~/.voicemode/call/config.json (see
config/config.example.json).
- Nothing outward happens on a line you may not have said. For sending, posting,
publishing outside your Mac, deleting, purchases, and invites, Claude writes the exact
action in the chat and reads it back in one sentence. By default a clear spoken yes to
that read-back ("yes, send it") counts. A mid-thought fragment, a yes buried in another
sentence, or a line that sounds like room audio does not, and an unclear answer falls back
to a typed yes. Set
approvals.outwardto"typed"to require a typed yes every time. - Voice never answers a permission prompt. By default the app's own dialog handles
prompts, exactly as without CludeGods. Set
approvals.permission_promptsto"pill"to get them on CallPill during a live call. There only a physical click answers: thepermithook waits for an answer file that only the pill's click handler writes, and clicks are ignored for 0.6 seconds after a request appears. - The settings change only by typing. Changing
config.json, or loosening a worker's tools or spaces, needs a typed yes. - Voice never starts sessions. New worker chats start only from text you submit yourself. The desktop app also refuses session starts from automated events, so a mod or hook cannot do it on its own.
- Workers get the tools you give them. A worker has its chat's full tools unless you
give it a preset:
read,drafts, or a list of tools. Theguardhook enforces a preset on every tool call. Adraftsworker can only write its own outbox and page drafts, so it cannot raise its own permissions or approve its own work. - Pages are direct by default, and Memory is always reviewed. Workers save pages in the
spaces you let them write. Set
approvals.worker_publishto"approve"and every page waits for your Approve. Memory, which every worker follows, changes only through a draft you approve. - Slack is allow-listed. Only listed users and channels reach a worker, replies only go to threads that came in that way, and message text is treated as a request from that person, never as instructions that override the worker's charter.
- Names are never fuzzy-matched. If Claude is unsure it heard a person or company right, it asks.
- The echo gate keeps Claude from hearing itself on laptop speakers and acting on its own words as if you had said them. Lines that make no sense as speech are treated as room noise and questioned, never acted on.
Honest limits
// faq
What is CludeGods?
Always-on AI Gods that work inside Claude Code, and you can talk to them. Proactive workers, computer use (browser, terminal & files), real-time voice like Jarvis, workers on a call in their own voice, Slack, and Spaces for your projects.. It is open-source on GitHub.
Is CludeGods free to use?
CludeGods is open-source under the MIT license, so it is free to use.
What category does CludeGods belong to?
CludeGods is listed under automation in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/cludegods)
// retro hit counter
[](https://claudeers.com/cludegods)
// reviews
// guestbook
// related in Automation & Workflows
The API to search, scrape, and interact with the web at scale. 🔥
🌐 Make websites accessible for AI agents. Automate tasks online with ease.
Taste-Skill - gives your AI good taste. stops the AI from generating boring, generic slop