najmuzzaman-mohammad/gawkbot

gawkbot – Open‑source “always‑on” AI assistants for your own machine

What it is – gawkbot is a desktop (macOS) and iPhone companion that lets you turn a natural‑language description of a workflow into a dedicated AI‑driven “micro‑app”. Each micro‑app (called a bot) runs locally, uses the LLM you already have (Claude Code, Codex, Opencode, or any local model you expose via Ollama/Hermes/OpenClaw), and can act on more than 1 200 integrations (Slack, Gmail, HubSpot, etc.). Every external action (send, commit, purchase, delete) is paused behind an approval gate that requires a click from you.

How it works

• Agent detection – On start‑up gawkbot scans your PATH, config folders and running processes to discover existing LLM‑CLI tools (Claude Code, Codex, Cursor, etc.). Detected agents can be adopted and become individual bots.
• Bot building – You describe a workflow in one sentence (or demo it). The chosen LLM builds a bot: a sandbox directory, a screen UI, a schedule (Routines), a set of Tools, a typed data table, and a Knowledge wiki page with citations.
• Runtime – Each bot runs in its own sandbox on your machine (or a cloud VM you point to). A side‑car service (agent/) supervises the bot processes. Bots can also be accessed from the iPhone app, which shows the same inbox of questions.
• Notch UI – On macOS the assistant lives in the camera notch. It pops up with moods, sound cues, and keyboard shortcuts (⌃⌥Space to open, J/K to navigate, 1‑9 to pick answers, V to talk, etc.).
• Approval gate – Reads are free; any write operation is presented as an ExternalActionApprovalCard and waits for your manual approval before the bot proceeds.
• Sharing – You can invite teammates via a private Tailscale/WireGuard mesh (gawkbot share) or a public Cloudflare tunnel that creates a one‑use URL.
• Persistence – Bot state, transcripts, and the “company brain” are stored as plain files under ~/.wuphf/, so you can inspect or delete them (gawkbot shred).

Key features

Feature	What you get
App UI	Real screen showing bot’s workspace, tools, data tables, and knowledge pages.
Routines	Cron‑like schedules, versioned prompts, per‑run transcripts.
Tools	Custom actions you teach the bot (e.g., “Score a lead”).
Knowledge	Wiki‑style pages with inline citations for every claim.
Integrations	1 200+ pre‑built connectors; you connect once and all bots share them.
Approval gate	Every external write requires a click; you see cost, tokens, and run count.
Multi‑workspace	Isolated workspaces you can list, switch, or share.
Local‑first	Runs on your hardware, uses your API keys; optional telemetry is off by default.

Getting started

1. Install the macOS app from gawk.bot/download.html or the GitHub releases.
2. On first launch verify your runtime and sign in to an LLM CLI (Claude Code is the default).
3. Describe your first workflow; watch the live build feed.
4. Interact via the notch or the iPhone app (apps/ios).

Installation from source (requires Go 1.25+ and Bun for the web UI):

git clone https://github.com/najmuzzaman-mohammad/gawkbot.git
cd gawkbot/web && bun install && bun run build && cd ..
go build -o gawkbot ./cmd/wuphf
./gawkbot

Configuration flags – e.g., --provider ollama to use a local Ollama model, --no-open to suppress auto‑opening the browser, --unsafe for dev‑only permission bypass.

Privacy – Optional anonymous analytics and session recordings are disabled unless you set a PostHog key. All data lives locally; no keys are stored in bot environments.

Why it matters – gawkbot gives you the same “always‑on” assistant experience of commercial services (e.g., xAI’s Grok Bot) but self‑hosted, free, and with explicit human approval on every action. It’s a concrete example of personal AI‑agent orchestration that can be extended with any LLM you control.