Architecture
Component View
📄 Text version
┌─────────────────────────────────────────────────────────────────────────────┐
│ CHANNELS │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ User (Telegram/ │ │ User (Browser) │ │
│ │ Discord) │ │ │ │
│ └──────────┬──────────┘ └──────────┬──────────┘ │
└─────────────┼──────────────────────────┼────────────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ GATEWAY · Fastify :18790 │
│ ┌─────────────────────────────────────┐ ┌─────────────────────────────┐ │
│ │ Dashboard UI (Preact/Vite) ◄────────┼───┘ │ │
│ │ │ Dashboard API │ │
│ └─────────────────────────────────────┘ └─────────────────────────────┘ │
│ │ │ │
│ │ /health /status /message │ │
│ │ /model /cron/:id/run │ │
│ └────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ CORE │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Agent │──│ Code Agents │──│ Cron │ │
│ │ Runtime │ │ (Claude/ │ │ Scheduler │ │
│ └──────┬───────┘ │ Codex/Kimi) │ └──────────────┘ │
│ │ └──────────────┘ │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ ├───►│ Audit Log │ │ Skills │ │ Heartbeat │ │
│ │ └──────────────┘ │ System │ │ Timer │ │
│ │ └──────────────┘ └──────────────┘ │
│ │ │
│ │ ┌──────────────┐ │
│ └───►│ Exec │ │
│ │ Approval │ │
│ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ PROVIDERS │
│ ┌──────────────────────────────────────┐ ┌─────────────────────────────┐ │
│ │ Anthropic / OpenAI / Codex / Kimi │ │ MCP Servers (mcporter) │ │
│ │ / MiniMax │ │ │ │
│ └──────────────────────────────────────┘ └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ ~/.skimpyclaw/ (config, logs, memory, templates) │
└─────────────────────────────────────────────────────────────────────────────┘Runtime Flow (Message Handling)
📄 Text version
User Channel/API Agent Runtime Provider Registry Adapter Model API Tools
│ │ │ │ │ │ │
│──message───────────────►│ │ │ │ │
│ │──runAgentTurn(agent,msg)──────►│ │ │ │
│ │ │──build prompt │ │ │
│ │ │──load skills │ │ │
│ │ │──sanitize │ │ │
│ │ │ │ │ │ │
│ │ [Tools enabled] │ │ │ │
│ │ │──chatWithTools─►│ │ │ │
│ │ │ │──resolve────►│ │ │
│ │ │ │ ╔══════════╧══════╗ │
│ │ │ │ ║ runToolLoop ║ │
│ │ │ │ ║ ──call──────────►│ │
│ │ │ │ ║ ◄─tool calls─────│ │
│ │ │──executeTool──────────────────────────────────────►│
│ │ │◄────────────────────────────────────tool result────│
│ │ │ │ ╚═══════════════════╝
│ │ │◄────────────────final response──────│ │ │
│ │ │ │ │ │ │
│ │ [Tools disabled] │ │ │ │
│ │ │──chat──────────►│ │ │ │
│ │ │ │──resolve────►│ │ │
│ │ │ │ │──chat───►│ │
│ │ │ │ │◄─response│ │
│ │ │──append to memory │
│ │ │──record audit │
│ │◄─────────────│ │ │ │ │
│◄─reply──────────────────│ │ │ │ │Startup Sequence
📄 Text version
src/index.ts
│
▼
┌─────────────────────────┐
│ loadConfig() │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ Load .env file │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ initProviders() │
│ Anthropic + OpenAI │
│ + Codex clients │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ createGateway() │
│ + listen :18790 │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ initCron() │
│ schedule jobs │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ initActiveChannel() │
│ + startActiveChannel() │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ initHeartbeat() │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ Service running │
└─────────────────────────┘Source Layout
text
src/
index.ts # App entrypoint with file logging setup
gateway.ts # Fastify server + top-level routes
agent.ts # Prompt assembly, model calls, tool loop, memory writes, Langfuse tracing
tools.ts # Tool registry, MCP auto-discovery, code agents (code_with_agent, code_with_team)
model-selection.ts # Shared model-selection contract (alias/provider-model/bare-id resolution)
file-lock.ts # In-memory file lock for concurrent writes
audit.ts # Append-only audit log (trace/event model, JSONL storage)
cron.ts # Job scheduling + execution + cron logging
heartbeat.ts # Periodic health/attention checks
channels.ts # Active channel selection + proactive routing
channels/
telegram/ # Telegram bot commands and message handling (Grammy)
discord.ts # Discord bot commands and message handling (discord.js)
voice.ts # Voice input/output (TTS/STT via multiple providers)
digests.ts # Daily digest generation for cron job article outputs
skills.ts # Skill loading, eligibility checks, and prompt injection
skills-types.ts # TypeScript types for skills system
exec-approval.ts # Human-in-the-loop exec approval flow with risk tiers
api.ts # Dashboard REST API under /api/dashboard/*
dashboard-frontend.ts # Dashboard static asset serving (Preact/Vite build)
security.ts # Auth, path validation, bash command blocklist, rate limiting
config.ts # Config loading with env var expansion
types.ts # All TypeScript interfaces and types
setup.ts # Interactive setup wizard
langfuse.ts # Observability integration with cost tracking
usage.ts # Token usage tracking and aggregation
service.ts # Runtime service management
cli.ts # CLI command definitions
cache.ts # TTL cache utility
sessions.ts # Session persistence for chat history
doctor/ # Health check system
index.ts # Doctor entry point
checks.ts # Individual health checks
formatters.ts # Output formatting (text/JSON)
runner.ts # Check orchestration
types.ts # Doctor type definitions
templates/ # Default template markdown files copied during setup
SOUL.md # Core agent personality and principles
IDENTITY.md # Agent name, emoji, persona
USER.md # User context and preferences
TOOLS.md # Tool usage instructions
BOOT.md # Startup behavior
HEARTBEAT.md # Heartbeat check instructions
MEMORY.md # Memory management guidelines
AGENTS.md # Multi-agent coordination
BOOTSTRAP.md # Bootstrap instructions
web/dashboard/ # Preact/Vite dashboard frontend
src/
App.tsx # Main app component with routing
api/client.ts # API client for backend communication
components/ # Shared UI components
pages/ # Page components (Overview, Cron, Audit, Memory, Config, Skills, Digests, etc.)
dist/ # Compiled output + built dashboard assetsModel Provider Architecture
Provider routing is unified through src/providers/index.ts:
chat()resolves the provider/model, gets an adapter from the registry, and callsadapter.chat(...).chatWithTools()resolves the provider/model, gets an adapter, and runsrunToolLoop(adapter, ...).runToolLoop()is the shared tool loop for all providers (iteration control, guards, tool execution, compaction, usage/audit hooks).
Adapter contract (src/providers/adapter.ts):
isAvailable()chat(messages, options, config)- provider-specific tool-loop methods used by
runToolLoop()(buildMessages,buildToolDefs,call, result appending, compaction, usage recording)
Current adapters:
AnthropicAdapterCodexAdapterOpenAIAdapter(OpenAI-compatible providers including Kimi, MiniMax, OpenRouter, Groq, etc.)
MCP support is adapter-scoped: Anthropic includes MCP tool definitions; Codex/OpenAI-compatible adapters do not.