terraphim / terraphim/terraphim-ai
feat: Implement TinyClaw multi-channel AI assistant (terraphim_tinyclaw)
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 62
- Forks
- 5
- Avg merge
- 2h 27m
- Merged PRs (30d)
- 1
Description
Summary
Build a multi-channel AI assistant binary (terraphim-tinyclaw) on the Terraphim agent crate ecosystem. Connects to Telegram, Discord, and CLI, routes user messages through a tool-calling agent loop with context compression, and responds via the originating channel.
Design document: docs/plans/tinyclaw-terraphim-design.md (v4, spec interview complete)
Research document: docs/plans/tinyclaw-terraphim-research.md
Branch: claude/tinyclaw-terraphim-plan-lIt3V
Architecture
Hybrid LLM Routing
- terraphim-llm-proxy (separate process): Tool-calling requests + quality-critical responses. 6-phase intelligent routing across 9+ providers with format conversion (186 tests).
- Direct GenAiLlmClient: Context compression via local Ollama. Cheap, high-volume.
- Fallback: If proxy unavailable, tools disabled entirely (text-only mode). No fragile text-parsing.
Reused Infrastructure (~5,600 LOC)
terraphim_multi_agent: AgentContext, PromptSanitizer, CommandHistory, TerraphimAgent (KG enrichment)terraphim_multi_agent::vm_execution: DangerousPatternHook (7 regex threat patterns), ExecutionConfidence scoring (0.0-1.0)terraphim-llm-proxy: Tool-call conversion, SSE streaming, circuit breakerterraphim_automata:find_paragraph_end()for message chunking
New Code (~3,400 LOC)
- Channel trait + ChannelManager + 3 adapters (Telegram via teloxide, Discord via serenity, CLI)
- ProxyClient (HTTP client for proxy with on-failure health tracking)
- ExecutionGuard (wraps DangerousPatternHook + confidence scoring)
- HybridLlmRouter (proxy for tool calls, direct for compression)
- ToolCallingLoop (iterative LLM -> tool execution -> LLM)
- Tool registry + 5 tools (filesystem, edit, shell, web_search, web_fetch)
- Session manager with JSONL persistence (200-message cap + summary)
- Markdown-to-platform formatting (Telegram HTML, Discord pass-through)
Key Decisions (from spec interview)
| Decision | Choice |
|---|---|
| Proxy lifecycle | Pre-started (user manages separately) |
| Proxy fallback | Disable tools, text-only mode |
| Health detection | On-failure only, 60s backoff |
| Task-type signaling | Skip Phase 1, proxy default routing |
| Auth default | Require non-empty allow_from (refuse to start without) |
| Message concurrency | Serial (one at a time) |
| Group sessions | Per-chat with user attribution |
| Session cap | 200 messages + summary |
| Message chunking | Paragraph split via find_paragraph_end() |
| Role management | Global /role list|select, queued during processing |
| System prompt | Two-layer: SYSTEM.md + role KG context |
| Graceful shutdown | Finish current iteration, save session, silent disconnect |
| Shell timeout | Configurable, default 120s |
| FS boundaries | No restriction (full access) |
| Secrets | Env var expansion in TOML config |
Implementation Steps
- Crate scaffold + bus + config (4h)
- Channel trait + CLI adapter (3h)
- Session manager (3h)
- Tool trait + registry + 5 tools (6h)
- Proxy client + execution guard (5h)
- Tool-calling loop with hybrid routing (7h)
- LLM-based context compression (2h)
- Markdown formatting (2h)
- Telegram adapter (8h)
- Discord adapter (6h)
- Gateway mode + orchestrator (4h)
Out of Scope (Phase 2+)
- WhatsApp bridge (Node.js subprocess)
- Feishu/Lark, Slack, Email adapters
- Voice transcription (Groq Whisper)
- Skills system, cron/scheduled tasks
- Subagent spawning
- Task-type signaling headers
- Proxy sidecar auto-launch
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading docs/plans/tinyclaw-terraphim-design.md and docs/plans/tinyclaw-terraphim-research.md, then review the implementation steps and reused Terraphim crates listed in the issue. Done means the eleven planned implementation steps match the specified routing, channels, sessions, tools, safety decisions, and Phase 2 boundaries.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- ai, backend, cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100