Docs · Architecture · Diagram

SkimpyClaw Architecture at a glance

Component view — channels, gateway, agent runtime, tools, and providers. All in one self-hosted service on your machine.

Local Machine · self-hosted service External APIs INPUT CHANNELS Telegram Bot voice, images src/channels/telegram Discord Bot threads, attachments src/channels/discord Web Dashboard Preact + Vite SPA :18790/dashboard CLI start · onboard · cron skimpyclaw … Fastify Gateway bearer auth · port :18790 src/gateway.ts + src/api.ts CORE RUNTIME Agent Runner runAgentTurn() · tool loop history · memory · audit src/agent.ts Provider Router runToolLoop (unified) model-selection · aliases src/providers/* Cron agentTurn + script payloads src/cron.ts Heartbeat keep-alive + proactive alerts src/heartbeat.ts Tool Executor registry · MCP discovery · dispatch · allowedPaths guard src/tools.ts + src/tools/* TOOLS Built-in Tools Read · Write · Glob · Bash Fetch src/tools/*.ts security gate Exec Approval risk tiers 0–3 human-in-loop for 2–3 src/exec-approval.ts code_with_agent delegate to coding CLI + Discord interactive sessions src/code-agents/* Skills trigger-loaded prompt snippets ~/.skimpyclaw/skills/ CODING AGENT CLIs Claude Code claude -p / --resume Codex codex exec Cron scheduled tasks Anthropic API Claude Opus / Sonnet / Haiku OAuth or API key Codex / ChatGPT chatgpt.com responses Codex OAuth MCP mcporter tools API key + baseURL MCP Servers auto-discovered via mcporter Telegram API long-poll bot updates bot token Discord API gateway websocket bot token ~/.skimpyclaw/ (local storage) config.json · discord-thread-agents.json · logs/* · skills/ · agents/

Input Channels

  • Telegram bot — voice, images, history, /new
  • Discord bot — threads, attachments, profile aliases, interactive coding sessions
  • Web dashboard — audit, cron, usage, templates, skills
  • CLI — start, stop, onboard, tools, cron

Core Runtime

  • Fastify gateway on :18790 with bearer auth
  • Agent runner with tool loop, history, and memory
  • Unified provider router (Anthropic / Codex / OpenAI-compat)
  • Configured agents + Discord profile routing
  • Cron scheduler + heartbeat keep-alive

Tools

  • Read, Write, Glob, Bash, Fetch
  • Path-scoped to allowedPaths
  • MCP tools auto-discovered via mcporter

Safety Gate

  • Exec approval classifies bash commands tier 0–3
  • Tiers 2–3 pause and require human approval
  • Approval requests route to the active channel

Coding Agents

  • code_with_agent spawns Claude or Codex CLI
  • Monorepo-aware validation scoped to changed packages
  • Live stdout streaming + cost / token tracking
  • Discord threads: bidirectional claude --resume sessions

Local Storage

  • Config at ~/.skimpyclaw/config.json (0600 perms)
  • JSONL logs: audit, usage, code-agents, interactive-sessions
  • Discord profile aliases in discord-thread-agents.json
  • Skills at ~/.skimpyclaw/skills/<name>/SKILL.md
  • Agent templates at ~/.skimpyclaw/agents/<name>/

External APIs

  • Anthropic (Claude Opus / Sonnet / Haiku)
  • Codex backend via ChatGPT responses endpoint
  • Anthropic and Codex providers
  • MCP servers auto-discovered via mcporter