claudeers.
// Automation & Workflows

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…

// Automation & Workflows[ cli ][ api ][ desktop ][ web ][ claude ]#claude#ai-agents#always-on-agents#claude-code#macos#voice#voice-assistant#voicemode#automation◷ MIT$open-sourceupdated 18 days ago
Actively maintained
100/100
last commit 19 days ago
last release 19 days ago
releases 5
open issues 0

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.
// or install directly (claude-plugin)
/plugin marketplace add AKamaly/CludeGods
/plugin install cludegods@AKamaly/CludeGods
// or clone
git clone https://github.com/AKamaly/CludeGods

// compatibility

Platformscli, api, desktop, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageTypeScript

Get your FREE $2.50 API credits to access TickAtlas financial data ↗
The six CludeGods workers: Scout, Colleague, Research, Scribe, Sales, and Herald

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


CludeGods: the app, a voice call, approving with a click, and a worker checking in

Watch the full launch film (67 s) · Latest release

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:

  • gods skill: 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: narrate says each step out loud as it happens; permit can 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.
  • guard hook: 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 in the Thinking state

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.

Diagram: Research, Scribe, Scout, and Sales connected through the Workers pane

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.

Make them yours: Research, Sales and Scout, each with 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 card for npm run deploy:staging with Deny and Allow buttons

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's card at 09:00 with two drafts that need a yes

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.

Open source. Local voice. Safe by design.

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:

  1. Restart the Claude app (quit it fully, then open it again).
  2. Type /gods in 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 voice in 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)
  1. 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
    
  2. The hooks: merge config/settings.example.json into ~/.claude/settings.json, keeping any hooks you already have. It registers narrate and guard on PreToolUse and permit on PermissionRequest.

  3. The state folder: mkdir -p ~/.voicemode/call and an empty registry, {"workers": []}, in ~/.voicemode/call/workers.json. config/workers.example.json shows every field a worker can have. Copy config/config.example.json to ~/.voicemode/call/config.json for the settings.

  4. 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-audio
    

    Then 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.onnx
    

    And 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
    
  5. 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 in CLAUDE_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 update pulls the source you installed from, runs install.sh again 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.sh from the source folder (~/.cludegods/src after 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 in settings.json (yours stay), and the three panes. Your workers, spaces and settings in ~/.voicemode/call go too, once you type delete; --keep-data keeps them. VoiceMode stays; it has its own uninstaller.
  • Coming from 0.4 or earlier: /colleague is now /gods. In your clone, run git pull && ./install.sh once: it moves the old colleague skill to ~/.claude/cludegods-backups/ and points the hooks and worker instructions at skills/gods. Then ~/.claude/skills/gods/bin/cludegods update brings 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, /gods says 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. /gods in 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 open switches back). The mic then stays off until you press the mic button or run call 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 mic is 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 --never or call tip headphones --never turns one off.
  • Something off? ~/.claude/skills/gods/bin/call status shows the voice and Whisper services, the mic mode, what the ears last heard, and whether a listener is armed. cludegods doctor checks 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.outward to "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_prompts to "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 /gods in 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_publish to "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/&lt;id&gt;.json (pill mode)" --> pill["CallPill"]
  pill -- "click writes &lt;id&gt;.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.

CallPill states: listening, talking, you, thinking, muted, a permission card, a worker on the call, and the waiting list

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 no charter, each wake asks the worker to check in on its role.
  • 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"} (every is 1h, 2h, 3h, 4h, 6h or 12h). days takes a range (mon-fri, sun-thu, fri-mon), a list (mon,wed,fri) or daily; tz is any IANA zone. The card's hours chip reads Mon to Fri · 9:00 or Every 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.outward to "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_prompts to "pill" to get them on CallPill during a live call. There only a physical click answers: the permit hook 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. The guard hook enforces a preset on every tool call. A drafts worker 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_publish to "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

…view the full README on GitHub.

// 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.

11 views
★ 53 stars
unclaimed
updated 18 days ago

// embed badge

CludeGods on Claudeers
[![Claudeers](https://claudeers.com/api/badge/cludegods.svg)](https://claudeers.com/cludegods)

// retro hit counter

CludeGods hit counter
[![Hits](https://claudeers.com/api/counter/cludegods.svg)](https://claudeers.com/cludegods)

// reviews

// guestbook

0/500

// related in Automation & Workflows

🔓

The agent that grows with you

// automationNousResearch/⟨Python⟩★ 264,763◷ MIT[ claude ]
🔓

The API to search, scrape, and interact with the web at scale. 🔥

// automationfirecrawl/⟨TypeScript⟩★ 199,533◷ AGPL-3.0[ claude ]
🔓

🌐 Make websites accessible for AI agents. Automate tasks online with ease.

// automationbrowser-use/⟨Python⟩★ 121,235◷ MIT[ claude ]
🔓

Taste-Skill - gives your AI good taste. stops the AI from generating boring, generic slop

// automationLeonxlnx/⟨JavaScript⟩★ 110,676◷ MIT[ claude ]
→ see how CludeGods connects across the ecosystem