The Problem

Organizations that need a 24/7 multi‑channel AI assistant often inherit code bases riddled with duplicated logic and absent test coverage, making extensions and bug fixes disproportionately expensive. TinyClaw’s repository exhibits exactly these maintainability risks.

What This Does

TinyClaw is a team of AI agents that functions as a personal assistant, running multiple isolated agents with specialized roles and routing messages via a @agent_id syntax. The code base is organized into four channel‑specific TypeScript clients—src/discord-client.ts, src/telegram-client.ts, src/whatsapp-client.ts, and src/queue-processor.ts—each invoked from the CLI entry point bin/tinyclaw (or ./tinyclaw.sh). Shared shell helpers live in lib/ (agents.sh, common.sh, daemon.sh, messaging.sh, setup-wizard.sh, heartbeat-cron.sh, update.sh). Configuration is gathered by the interactive wizard in lib/setup-wizard.sh and stored as environment variables; AI providers (Anthropic Claude, OpenAI GPT) are selected there. The system uses a file‑based queue (lib/messaging.sh) to avoid race conditions and runs inside a tmux session for always‑on availability.

How It Is Wired

The internal call graph contains four modules (src/discord-client, src/queue-processor, src/telegram-client, src/whatsapp-client) with zero import edges and no circular dependencies, simplifying changes to individual channels. Execution starts at bin/tinyclaw → lib/setup-wizard.sh → lib/daemon.sh, which spawns the three client processes and the queue processor. Each client handles its respective channel’s incoming messages, pushes them onto the shared file queue, and the queue processor dispatches them to the configured AI provider. The modules are otherwise independent; a modification to one client does not ripple through the others, but the duplicated 6‑line blocks (108 occurrences across six files) and nesting depth of up to eight indicate that future changes risk introducing inconsistencies.

How To Use It

# 1. Clone the repository (use the exact URL)
git clone https://github.com/moses-y/tinyclaw.git
cd tinyclaw

# 2. Install dependencies
npm install

# 3. Start the interactive setup wizard (collects tokens, workspace name, AI provider)
./tinyclaw start   # or: bin/tinyclaw start

The wizard writes a minimal config under lib/ and launches the daemon. Required environment variables (bot tokens, API keys) are captured during setup; no manual editing of config files is needed for a basic deployment.

Real‑World Use

A distributed team wants an always‑on assistant that can answer queries on both Discord and Telegram. They add a new agent by editing lib/agents.sh and assign it an @agent_id. When a user mentions the ID, the relevant client posts the message to the file queue; the queue processor forwards it to the selected AI model (Claude Sonnet, for example). The team monitors activity with tinyclaw logs queue and can restart individual channels without affecting the others, thanks to the isolated client architecture.

Code Health & Issues

  • Duplicated code blocks – 108 repeated 6‑line segments across lib/common.sh, scripts/remote-install.sh, src/discord-client.ts, src/telegram-client.ts … (extract shared helpers; DRY the logic).
  • Deep nesting – Max indentation depth of 8 in src/discord-client.ts, src/telegram-client.ts, src/whatsapp-client.ts; flatten with guard clauses.
  • High branching density – 108 branch points over 368 lines in src/telegram-client.ts; decompose decision logic (strategy or table dispatch).
  • No test files – repository‑wide untested code paths.
  • No LICENSE file – unclear usage/redistribution rights.

Code‑health audit (static analysis):

  • HIGH – Pin third‑party GitHub Actions to a commit SHA (.github/workflows/release.yml uses softprops/action-gh-release@v1); a tag can move and run with whatever owner last pushed.
  • MEDIUM – Enable Dependabot or Renovate (one manifest, no update bot configured).
  • MEDIUM – Gate pull requests on a dependency vulnerability scan (no scan in CI).
  • MEDIUM – Set persist-credentials: false on checkout (.github/workflows/release.yml keeps the token for later steps).
  • LOW – Add timeout-minutes to workflow jobs (release workflow declares no job timeout).

The Bottom Line

TinyClaw delivers a functional, multi‑channel AI assistant with a clean modular structure and no circular dependencies, making it straightforward to add or remove channels. However, the code base suffers from extensive duplication, deep nesting, high branching density, missing tests, and no license—issues that raise maintenance overhead and limit production readiness. It is suitable for prototyping or internal use; any deployment that expects regular updates, compliance, or long‑term support should address the audit findings first.