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 │──│ Subagent │──│ Code Agents │──│ Cron │ │
│ │ Runtime │ │ Pool │ │ (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 Model API Tools
│ │ │ │ │
│──message────────────────►│ │ │
│ │──runAgentTurn(agent, msg)──►│ │
│ │ │──build prompt │
│ │ │──load skills │
│ │ │──sanitize │
│ │ │ │ │
│ │ [Tools enabled] │
│ │ │ │ │
│ │ ╔══════════════╧══════════╗
│ │ ║ TOOL LOOP ║
│ │ ║ ──chatWithTools───────►│
│ │ ║ ◄──tool_use blocks─────│
│ │ ║ ──executeTool──────────┼──►
│ │ ║ ◄──tool result─────────┼──│
│ │ ╚═════════════════════════╝
│ │ │ │ │
│ │ │◄─final response │
│ │ │ │
│ │ [Tools disabled] │
│ │ │ │ │
│ │ │──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)
subagent.ts # Background task dispatch: retry, concurrency, disk registry
model-selection.ts # Shared model-selection contract (alias/provider-model/bare-id resolution)
file-lock.ts # In-memory file lock for concurrent subagent 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
telegram.ts # 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
model-selection.ts # Shared model-selection contract for API/CLI/chat commands
digests.ts # Digest storage and management for cron job article outputs
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
Three provider paths in agent.ts:
- Anthropic —
chatWithTools()— standard Anthropic SDK with tool_use - Codex —
codexChat()— raw fetch tochatgpt.com/backend-api/codex/responses(ChatGPT backend) - OpenAI-compatible —
chat()via OpenAI SDK — includes OpenAI, Kimi, MiniMax, openrouter, groq, etc.
Both Anthropic and Codex share ExecuteToolContext for spawn_subagent and file locking.