How mercphobia/krol works
Krol is a mobile-first AI agent framework. A user starts a conversation through the CLI or an interface; the agent loop streams model responses, dispatches requested tools through policy checks, and returns results to the conversation. Around that core, Krol provides persistent memory, planning and scheduled autonomy, extensibility, and multiple user interfaces. The README documents these capabilities, but many implementation files were not sampled, so their internal connections are shown only where documented or explicitly marked unverified.
Main entry points: loop.py Agent loop · cli.py CLI · session.py Policy session · base.py Tool registry
Components 27
Agent runtime
- Agent loop
src/krol/core/loop.py - Model providers
src/krol/models/base.py - Chat types
src/krol/types.py - Token economy
src/krol/tokens.py - History compaction
src/krol/compaction.py
Safety and tools
- Policy session
src/krol/policy/session.py - Tool registry
src/krol/tools/base.py - Built-in tools
src/krol/tools/filesystem.py - Self-upgrade
src/krol/self_upgrade/tool.py - Checkpoints
src/krol/policy/checkpoint.py
Memory and autonomy
- Persistent memory
src/krol/memory/store.py - Memory recall
src/krol/memory/recall.py - Goals and todos
src/krol/goals.py - Cron scheduler
src/krol/sched/jobs.py - Subagents
src/krol/subagents/orchestrator.py
Extensions
- Skills
src/krol/skills/registry.py - Mods and hooks
src/krol/mods/runtime.py - MCP client
src/krol/mcp/client.py
Interfaces
- CLI
src/krol/cli.py - Web UI
src/krol/ui/webui.py - Chat interfaces
src/krol/ui/chat.py - Telegram
src/krol/ui/telegram.py - Discord
src/krol/ui/discord.py - HTTP API
src/krol/api/server.py - Node TUI
tui/src/app.mjs - Python TUI host
src/krol/ui/host.py
Other components
- User
Connections 26
- User → CLI: submits prompt
README.md - CLI → Agent loop: starts agent
src/krol/cli.py - Agent loop → Model providers: streams requests
src/krol/core/loop.py - Agent loop → Policy session: checks tool calls
src/krol/core/loop.py - Policy session → Tool registry: executes guarded
src/krol/policy/session.py - Tool registry → Built-in tools: registers tools
src/krol/tools/__init__.py - Tool registry → Self-upgrade: registers tool
src/krol/tools/__init__.py - Policy session → Checkpoints: creates checkpoints
src/krol/policy/session.py - Agent loop → Persistent memory: uses memory
src/krol/core/loop.py - Agent loop → Memory recall: recalls context
- Agent loop → History compaction: compacts history
src/krol/core/loop.py - Agent loop → Token economy: tracks usage
src/krol/core/loop.py - CLI → Goals and todos: manages goals
README.md - CLI → Cron scheduler: manages schedules
README.md - Agent loop → Subagents: delegates work
- Agent loop → Skills: loads relevant skills
src/krol/core/loop.py - Agent loop → Mods and hooks: dispatches hooks
src/krol/core/loop.py - CLI → MCP client: connects servers
README.md - User → Web UI: sends messages
README.md - Web UI → Chat interfaces: routes messages
src/krol/ui/webui.py - User → Telegram: chats with agent
README.md - User → Discord: chats with agent
README.md - User → HTTP API: sends requests
README.md - User → Node TUI: enters terminal text
tui/src/app.mjs - Node TUI → Python TUI host: sends frames
- Python TUI host → Agent loop: runs agent