Introduction

OpenCrabs adalah agen orkestrasi AI yang di-hosting sendiri dan tidak terikat provider, berjalan sebagai satu biner Rust. Ia mengotomatiskan terminal, browser, channels (Telegram/Discord/Slack/WhatsApp/Trello), dan codebase Anda, sambil menghormati privasi Anda dan menjaga kendali tetap di tangan Anda.

11,091 test mencakup provider, tools, channels, TUI, self-healing, dan otomatisasi browser.

Apa yang Membedakan OpenCrabs

Nol Telemetri, Bahkan Tanpa Opt-In

• OpenCrabs tidak pernah menelepon pulang. Sesekali pun tidak. Tanpa analitik, tanpa pelacakan, tanpa statistik penggunaan, tanpa logging jarak jauh, tanpa laporan crash
• Percakapan, tools, memori, konfigurasi, dan kunci API Anda tidak pernah meninggalkan mesin Anda
• Satu-satunya trafik keluar adalah yang Anda mulai sendiri secara eksplisit: panggilan LLM API, pencarian web, perintah GitHub, otomasi browser
• Ini bukan sekadar kotak centang kebijakan privasi: tidak ada kode telemetri untuk dinonaktifkan, tidak ada flag opt-out, tidak ada layanan analitik untuk diblokir. Memang tidak ada apa pun untuk dikirim

Bebas Provider Sejak Desain

• 16 provider bawaan + Custom OpenAI Compatible: Anthropic Claude, OpenAI, Gemini, Xiaomi MiMo, OpenRouter, Qwen (DashScope), MiniMax, Ollama, z.ai GLM, GitHub Copilot, Codex, Codex CLI, OpenCode, OpenCode CLI, Moonshot AI (Kimi), Command Code CLI
• Integrasi CLI natif: gunakan Claude Code CLI, OpenCode CLI, Codex CLI, dan Command Code CLI sebagai provider tanpa kunci API
• Rantai fallback lengket: failover otomatis saat rate limit atau error, persistensi sadar-kesehatan bertahan melewati restart
• Prompt caching di Anthropic, OpenRouter, Gemini, Qwen DashScope memangkas biaya hingga 95%
• Override jendela konteks: batasi atau perluas konteks model apa pun lewat konfigurasi (provider OpenCrabs bawaan adalah pengecualian: jendelanya tetap 200k)
• Xiaomi MiMo: 30+ model termasuk seri reasoning MiMo, provider berkunci
• Moonshot AI (Kimi): endpoint API plan (api.moonshot.ai) dan Coding plan (api.kimi.com), konfigurasi reasoning-effort, jendela konteks sesuai tier paket

Multi-Agent Orchestration

• Sessions adalah agen yang terisolasi penuh, masing-masing dengan brain, provider, model, direktori kerja, dan riwayatnya sendiri
• Sub-agent bertipe: general, explore, plan, code, research dengan akses tools yang disesuaikan
• Orkestrasi tim: team_create, team_broadcast, team_delete untuk alur kerja terkoordinasi
• Override provider/model per panggilan: campur model antar tim (plan dengan GLM, code dengan Deepseek, review dengan Kimi)
• Protokol A2A: gateway JSON-RPC 2.0 untuk komunikasi antar agen

Komunikasi Natif di Channels

• Telegram, Discord, Slack, WhatsApp, Trello, integrasi bot penuh dengan DM, grup, dan thread
• Rich message Telegram: tabel, heading, daftar, dan matematika natif lewat konfigurasi rich_messages
• Streaming draf pesan: pembaruan “sedang mengetik…” secara langsung saat token dihasilkan di DM
• Blok yang bisa dilipat: bagian <details>/<summary> untuk keluaran panjang
• Isolasi session per topik forum: setiap topik di supergrup Telegram mendapat session-nya sendiri
• Reaksi Telegram: bot membaca reaksi emoji masuk dan bisa membalas dengan reaksi alih-alih pesan bila cocok
• Reaksi bingkai (v0.3.61): reaksi masuk dibaca berdasarkan sentimen, agen menyapa pengguna dengan nama depan
• Reaksi di tengah giliran (v0.3.61): reaksi saat giliran sedang berjalan disuntikkan ke loop saat ini alih-alih memicu giliran kedua
• Saran tindak lanjut (v0.3.69): tindak lanjut opsional sekali-ketuk di Telegram, Discord, Slack, WhatsApp; isi-tanpa-kirim di TUI
• Penempelan ulang kartu rencana Telegram (v0.3.71): kartu rencana ditempel ulang dan prosa dilipat ke dalamnya saat terkubur pesan
• Penangkapan riwayat grup penuh (v0.3.73): setiap pesan grup disimpan ke riwayat, bahkan dari pengirim dan bot di luar allowlist
• Pembicara grup yang benar (v0.3.73): berhenti menyapa pengirim riwayat grup seolah-olah dia pembicara saat ini
• Pewarisan session: /new mewarisi direktori kerja dari session terbaru Anda
• /goal di semua channels: tetapkan tujuan otonom dari Telegram, Discord, Slack, WhatsApp
• Dukungan suara: Whisper STT + Piper TTS lokal, sepenuhnya offline
• Pemulihan crash lintas channel: permintaan tertunda dialihkan kembali ke channel asal saat restart
• /cowork: buat workspace bersama dari channels dan TUI
• /rename, /profiles, /cd, kelola sessions, profil, dan direktori dari channel mana pun

Self-Healing & Peningkatan Diri

• Recursive Self-Improvement (RSI): agen menganalisis kinerja, mengenali pola, dan menulis ulang brain files

• Deteksi tool call fantom: menangkap saat model menceritakan perubahan tanpa benar-benar mengeksekusi tools

• Self-heal deteksi fantom (v0.3.72): menangkap giliran tanpa tool yang mengklaim efek samping berisiko tinggi (ship/push/tag/release)

• Edit konfigurasi hanya via config_manager (v0.3.74), agen tidak pernah mengedit config.toml/keys.toml secara mentah; setiap penulisan divalidasi sebelum diterapkan

• Dedup brain (v0.3.75): perintah /dedup plus pemindaian pasca-tulis dan mingguan lintas file menjaga brain files agar tidak mengganda, dengan persetujuan inline-keyboard Telegram

• Petunjuk brain-file saat tools meleset (v0.3.75): catatan brain yang relevan muncul otomatis saat tool call meleset atau error

• Kemunculan memori proaktif (v0.3.76): memori relevan muncul tanpa diminta saat konteks percakapan cocok dengan pengetahuan tersimpan

• Penamaan model natural (v0.3.76): /models opus berhasil; nama percakapan diresolusi menjadi ID model yang tepat

• Routing provider plan/eksekusi (v0.3.76): arahkan perencanaan dan eksekusi ke provider/model terpisah

• Timeout loop berpikir (v0.3.78): menangkap loop penalaran tak berujung, memicu penegakan fantom dengan sticky fallback

• Mesin epistemik (v0.3.78): pelacakan keyakinan dengan tingkat kepercayaan, mesh kognitif OODA/BDI, gerbang Orient sebelum eksekusi rencana

• Gerbang verifikasi Ralph (v0.3.78): verifikasi tugas sadar-kriteria dengan batas iterasi; tugas harus memenuhi kriteria penerimaan yang dinyatakan

• Gerbang keamanan TOML (v0.3.78): blocklist bash yang bisa dikonfigurasi saat runtime dengan hot-reload, redaksi rahasia bertanda kutip, verifikasi brain file

• Analitik Mission Control (v0.3.78): filter D/W/M, grid kartu tiga kolom, tab phantom/model/streaming, DB event khusus

• Onboarding OpenAI TTS (v0.3.78): pemilih suara dan kolom kunci API di wizard onboarding

• Instalasi Homebrew (v0.3.79): brew install opencrabs dari homebrew-core: biner siap pakai, kedua arsitektur, tanpa toolchain Rust

• /restart dan /exit (v0.3.79): restart atau matikan dari channel atau TUI mana pun; hanya owner di channels, mengumumkan sebelum bertindak

• Pemutus arus kuota (v0.3.79): provider dengan kuota habis mendapat breaker TTL dan dilewati dalam perjalanan fallback; kehabisan rantai dilaporkan eksplisit

• Status rencana lintas session (v0.3.79): rencana bertahan melewati batas session; eksekusi tugas rencana terisolasi aktif secara default, Ralph memverifikasi di direktori session itu sendiri

• Sistem tema (v0.5.0): preset terverifikasi, pemilih interaktif, dan tema Anda sendiri dari ~/.opencrabs/themes/*.toml; truecolor dideteksi dengan tingkat cadangan ANSI-256, dan preset yang kontrasnya membuat teks tak terbaca akan ditolak

• Memori struktur kode (v0.5.0): tree-sitter membangun indeks simbol dan graf pemanggilan di samping indeks teks, sehingga “siapa yang memanggil X” menelusuri sisi pemanggilan yang sebenarnya sementara pertanyaan konseptual tetap lewat jalur teks (#1324)

• Transfer berkas lewat SSH (v0.5.0): berkas yang dijatuhkan ke TUI di host jarak jauh ditarik kembali melalui koneksi yang sudah terbuka, dengan opencrabs drop-agent di sisi klien (#1289)

• Putusan pengiriman notify (v0.5.0): session_notify mengembalikan hasil kirim yang terbaca mesin, tanda terima injeksi kedalaman 3 membuat notify_id dapat diperiksa, dan pengiriman dialihkan ke session yang memiliki channel saat itu

• Pemadatan di latar belakang (v0.5.0): peringkas berjalan di luar giliran alih-alih menahan session selama bekerja

• Penyuntingan token saat penulisan (v0.5.0): galat provider yang membawa URL tidak lagi bisa membocorkan token bot ke log, dari mana pun dicatat (#1322)

• Userbot Telegram hanya-terima (v0.5.0, eksperimental): penangkapan MTProto di balik feature, dengan login lokal via QR/kode/2FA; menyimpan teks yang diizinkan untuk diambil dan tidak pernah bertindak sebagai pengguna

• Penjangkaran waktu (v0.5.1): agen selalu tahu jam berapa sekarang: setiap giliran membawa penanda waktu dalam zona waktu pengguna, dan prompt sistem tetap stabil byte demi byte untuk caching penyedia (#1516)

• Sesi cron per job (v0.5.1): setiap job terjadwal mendapat sesinya sendiri, sehingga dua job yang berjalan bersamaan tidak pernah berbagi konteks atau penyedia (#1511)

• Gerbang glob skill (v0.5.1): daftar globs: sebuah skill dapat menolak panggilan tool ke berkas yang cocok sampai agen benar-benar membaca body skill tersebut (#1515)

• Tulisan config divalidasi terhadap struct (v0.5.1), penjaga tulis dan saran bagian config_manager kini diturunkan dari tipe Config itu sendiri, agar tidak pernah menyimpang dari kode yang dikirim (#1508)

• Desain plan ditolak saat ditulis (v0.5.1): desain plan yang rusak langsung dipantul dengan menyebutkan bagian yang hilang, dan tulisan yang ditolak mengembalikan scaffold alih-alih menghapus draf (#1507)

• Tekanan balik anggaran penyedia (v0.5.1): penyedia yang melaporkan anggaran token output memicu satu komaksi berbatas lalu percobaan ulang, alih-alih kaskade 400 (#1518)

• Token A2A terikat dan config khusus owner (v0.5.1), token A2A terikat ke gateway yang menerbitkannya, dan config.toml/keys.toml berpindah ke mode khusus owner, dengan rahasia disingkirkan dari log

• Mode server ACP (v0.5.2): opencrabs acp berbicara Agent Client Protocol lewat stdio JSON-RPC, sehingga Zed, MonoCode, dan klien ACP mana pun menjalankan brain yang sama dengan channels Anda, lengkap dengan streaming progres dan persetujuan yang kembali ke editor (#1540)

• Penjelajahan sadar shadow-DOM (v0.5.2): resolusi selector menembus shadow root, sehingga otomasi menjangkau web component yang sebelumnya tidak terlihat oleh tools

• Permukaan WhatsApp penuh (v0.5.2): pesan suara native, video/stiker/lokasi/kontak masuk, suara polling, pemulihan presence dan media, tanda terima reaksi, streaming dengan edit di tempat, pesan sementara, pemblokiran kontak, pin/teruskan/profil, pembaruan status, penemuan newsletter, tombol native flow, riwayat per chat

• Tracing langsung dan tabel native di Discord (v0.5.2), giliran panjang mengalir sebagai balasan langsung ber-tracing, jawaban otomatis masuk thread, tabel markdown dirender secara native, dan giliran dengan tools tidak lagi mengirim jawaban akhir dua kali (#1603, #1608)

• Topik forum Telegram dan /clear (v0.5.2): buat/ganti nama topik forum dengan pengikatan session, dan /clear memulai session baru tanpa panggilan summariser (#1585)

• Anggaran payload menu perintah (v0.5.2): setMyCommands Telegram diam-diam menolak body permintaan di atas ~7,8KB sambil melaporkan BOT_COMMANDS_TOO_MUCH; deskripsi kini dipendekkan bertingkat agar seluruh menu muat (#1613)

• Cron dengan trigger (v0.5.3): job menjalankan pre-flight check dan hanya mengeksekusi saat kondisi Anda terpenuhi (output tidak kosong, exit code, regex), run yang dilewati biayanya 0 token, dan trigger yang terpicu bisa mengirim goal ke sebuah session (#233)

• Windows kelas satu (v0.5.3): penanganan shell per-platform, pembacaan file BOM/UTF-16, fallback tilde dan cwd, dengan CI membangun Windows dan meng-gate PR (#627)

• Memori epistemik (v0.5.3): fakta di MEMORY.md membawa confidence dan decay (#1643), section yang dingin mengarsipkan diri sendiri, dan opencrabs memory prune menampilkan apa yang sudah dingin sebelum menyentuhnya (#1657)

• Mesin tema selesai (v0.5.3): setiap widget TUI menyelesaikan warnanya melalui tema, dengan suite guard terhadap situs ANSI mentah baru, dan tema bisa mendeklarasikan canvas background (#1634)

• Poll saran WhatsApp (v0.5.3): kumpulan follow-up yang melebihi batas tombol native dirender sebagai poll, dan satu suara memilih opsinya (#1616)

• Keluarga session ACP (v0.5.4): session kini first-class di permukaan ACP: context meter dipulihkan saat load dan mengikuti usage updates, session/load memutar ulang transcript dan memulihkan model per-session, set_model bertahan antar proses, session/set_mode native menerapkan approval policy di sisi server, session/compact melakukan push, dan session/new menawarkan katalog model secara live

• Serah terima terminal interaktif (v0.5.4): !vi/!nano mengambil alih terminal secara interaktif dan mengembalikannya dengan session utuh; hanya terminal Unix, di Windows tetap memakai capture lewat pipe (#1744, #1759)

• Paste & drop universal (v0.5.4): satu router attachment bersama menerima semua jenis file saat paste atau drop dan mengklasifikasikan kode, docs, arsip, dan data agar masing-masing masuk ke pipeline yang tepat (#1740, #1743)

• Mesin pencari Serper (v0.5.4): serper_search menambahkan hasil Google SERP, dan fan-out web_search mendedupe berdasarkan URL antar engine (#1731)

• Decision cache (v0.5.4): decide_cached menjawab keputusan berulang dari ring reuse L1 dengan tier shadow/live dan config [decisions] (#1648)

• Biaya yang dilaporkan provider dan satu rantai timeout (v0.5.4), ledger usage memilih biaya yang benar-benar dilaporkan provider daripada estimasi tabel (#1707), dan flag timeout diselesaikan [providers.<name>] -> [agent] -> default untuk semua provider (#1688)

• Perintah terkompilasi /architecture dan /attach, audit trail opsional (v0.5.4), keduanya dikirim sebagai arms terkompilasi, dan audit trail opsional mencatat apa yang berjalan dengan viewer /audit (#933, #1705)

• Permukaan native Discord (v0.5.5): polls native via send_poll, jawaban TTS dikirim sebagai pesan suara, dan commands.toml diproyeksikan ke slash commands native sehingga command Anda sendiri muncul di picker Discord (#1848, #1849, #1850)

• Flow groups dan write governors (v0.5.5): Discord dan Slack membuka flow group di awal turn dengan clock live yang menutupi masa berpikir dan teks aktivitas memimpin baris, dan satu governor write bersama mengatur budget setiap edit serta melakukan park saat 429 (#1841, #1843, #1844, #1845, #1807, #1808, #1809, #1910, #1912, #2012)

• /respond_to dan /cowork (v0.5.5): mode respond_to dan open per kanal di konfigurasi, plus dua command untuk mengubahnya langsung dari kanal itu sendiri (#2014, #2015)

• Disiplin rate limit Telegram (v0.5.5): polls getUpdates dan handoff handler diinstrumenkan untuk triase stall, floor jeda sub-sekon lintas permukaan dengan telemetri admission, jeda 429 per chat di balik satu accessor Cooldown, dan link markdown ke file lokal dikirim sebagai dokumen (#1927, #1916, #1968)

• Session lifecycle ACP v1 (v0.5.5): lima metode v1 session lifecycle telah diimplementasikan dan plan diterbitkan sebagai pembaruan plan v1 native (#1815)

• Footer dialog bersama, URL yang bisa diklik, timeline onboarding (v0.5.5): setiap dialog berbagi satu command footer dengan verb persetujuan a/r langsung, URL dan path file bisa diklik, dan onboarding dibangun ulang sebagai timeline langkah di sisi kiri dengan command setup langsung (#1775, #1772, #1979, #1980, #1981, #1982)

• Retirement cron one-shot (v0.5.5): job one-shot pensi saat terkirim alih-alih menyala lagi setahun kemudian, setiap run yang terkirim membawa run id-nya, dan laporan cron Discord tiba sebagai satu post forum (#544, #1703, #1851)

• Percobaan pertama tanpa penyiapan (v0.5.11): instalasi baru langsung masuk ke chat dengan provider bawaan sudah disiapkan, config.toml dan keys.toml sudah dibuat, dan agen menyapa Anda. Wizard bersifat opsional lewat /onboard atau --onboard (#2079)

• Turn pertama yang tidak bisa menggagalkan proses (v0.5.11): thread worker agen berjalan di stack 16 MiB, jadi turn pertama tidak lagi meluap di stack bawaan (#2080)

• Tag rilis hanya dengan CI hijau (v0.5.11): workflow rilis membaca kesimpulan run CI milik commit itu sendiri sebelum menerbitkan. Run merah menggagalkan rilis, run yang masih berjalan akan ditunggu, dan commit tanpa run juga gagal (#2078)

• Evolve me-restart unit yang benar (v0.5.11): restart terjadwal menyasar nama unit yang sudah diresolusi alih-alih glob penemuan opencrabs*.service, yang juga cocok dengan unit sementara yang menjalankan restart itu sendiri dan membuat systemd menghentikan eksekutornya sendiri (#2081)

• Guest queries Telegram mendapat permukaan penuh (v0.5.12): tag di chat tempat bot tidak pernah diundang menjalankan permukaan tools, blok status langsung, dan rendering rich yang sama seperti turn biasa, dengan satu turn yang bisa dibatalkan per guest session dan rate limiting (#2087, #2109, #2133, #2135, #2138, #2143)

• Plan diwajibkan setelah ambang tool calls (v0.5.12): begitu turn melewati ambang tool calls, agent harus berhenti dan menulis plan sebelum melanjutkan (#2128)

• Transcript bertahan saat berganti session (v0.5.12): peta lipatan diindeks dengan anchor role dan timestamp yang stabil, bukan UUID yang dibuat setiap render, jadi berganti session lalu kembali tidak lagi melipat semua turn yang sudah Anda buka (#2155)

• Instalasi headless menyiapkan provider bawaan (v0.5.12): opencrabs run, daemon, agent, acp, dan cron membuat token bawaan di home baru seperti yang sudah dilakukan TUI, sementara status dan doctor tetap hanya baca (#2151)

• Mode perbaikan doctor –fix (v0.3.83): baris cron macet, marker basi, dan izin rusak diperbaiki di tempat alih-alih sekadar dilaporkan

• Kunci tulis per path (v0.3.83): penulisan bersamaan ke file yang sama diserialisasi; penulis terakhir tidak lagi menang diam-diam

• Isolasi worktree sub-agent (v0.3.83): setiap agen anak mendapat worktree dan branch sendiri, sehingga fan-out tidak bisa merusak pohon bersama

• Kriteria penerimaan sadar-tipe (v0.3.83): kriteria rencana ditegakkan terhadap toolchain yang benar-benar dipakai proyek (#1133)

• Verifikasi rencana sadar-proyek (v0.3.83): rencana diverifikasi dengan perintah proyeknya sendiri, bukan selalu cargo, dan menemukan proyek dari folder session

• /stop membatalkan seketika (v0.3.83): menyela bahkan saat handshake provider dan jeda retry (#1148)

• Resume session A2A (v0.3.83): session diresume berdasarkan context id, gateway dialamatkan per profil (#1159, #1161)

• Kenop thinking DeepSeek (v0.3.83): DeepSeek mendapat parameter thinking yang benar-benar dibacanya, plus penanganan giliran khusus tool-call

• Korelasi log session_id (v0.3.82): setiap giliran membuka span tracing berisi session id-nya, tugas cron dan mesin RSI punya miliknya sendiri, jadi satu grep menyusun ulang seluruh giliran dari log harian bersama

• Keandalan logger (v0.3.82): logger berhenti membuang event dan berhenti menulis ke terminal TUI; penulisan yang macet tidak lagi membungkam logging thread lain

• Brain files milik pengguna dilindungi (v0.3.82): SOUL.md, USER.md, dan MEMORY.md tidak pernah diisi dari upstream, dan direktif dialihkan ke AGENTS.md, yang selalu dimuat

• Penyatuan seksi konfigurasi (v0.3.82): ejaan legacy [gateway] dimigrasikan di disk menjadi [a2a], jadi satu nama bertahan melewati putaran reload

• Cache chunk-hash (v0.3.82): memori melewatkan embedding ulang chunk yang isinya tidak berubah

• Biner pra-rilis (v0.3.82): lima target platform plus SHA256SUMS, dipublikasikan sebagai pre-release bergulir agar kontributor bisa menguji kode yang belum dirilis tanpa menunggu tag. Dijalankan sesuai permintaan, bukan setiap push

• Pelepasan rate-limit (v0.3.82): jendela rate-limit Telegram yang panjang langsung kembali alih-alih memarkir pengiriman di antrean

• Penyimpanan memori in-tree (v0.3.81): dependensi qmd dihapus; pencarian SQLite FTS5 + vektor dikelola in-tree

• Path indeks eksternal (v0.3.81): pencarian memori membaca indeks di luar direktori profil, default-deny di session bersama

• Mermaid sebagai gambar di Telegram (v0.3.81): diagram dirender sebagai gambar sementara tabel tetap formatting natif

• Penalaran Qwen lintas giliran (v0.3.81): preserve_thinking, kenop thinking per keluarga, tier effort rekomendasi secara default, Qwen hosted terjangkau di mana saja

• Perbaikan kehilangan kunci keys.toml (v0.3.81), kunci API provider tidak lagi hilang saat runtime; kunci yang teracuni menyembuhkan diri

• Deteksi loop dini (v0.3.81): putaran tool berulang tertangkap sebelum provider menolak giliran

• Gerbang mesin RSI (v0.3.81): RSI otonom mati secara default untuk daemon headless, aktifkan dengan rsi_enabled

• Cakupan memory_search (v0.3.80): cari log harian (memory), brain files (brain), atau keduanya (all); brain files diindeks saat ditulis

• Pengambilan memori ter-chunk (v0.3.80): dokumen di-chunk sebelum embedding sehingga chunk belakang tetap bisa dicari; recall diperingkat dengan BM25

• Rendering natif Slack (v0.3.80): tabel dan heading datang dalam format Slack sendiri alih-alih markdown mentah

• Perintah channel terkunci owner (v0.3.80): perintah dan skills kustom hanya untuk owner pada lengan catch-all channel di grup

• Gerbang konvergensi RSI (v0.3.80): self-improvement berhenti saat konvergen, mundur saat beruntun tanpa perbaikan, meng-hash temuan berdasarkan identitas stabil

• Penjaga loop (v0.3.80): penjaga pengumuman berulang dan pengulangan hampir-identik di semua tools; tembakan detektor loop sampai ke rantai fallback

• Mode inventaris browser (v0.3.80): browser_find polos menghitung setiap elemen yang bisa diklik di halaman

• Pembaruan templat brain-file (v0.3.80): templat AGENTS.md, BOOT.md, dan SOUL.md berubah; seeding tidak pernah menimpa file yang ada, jadi diff terhadap src/docs/reference/templates/ dan merge manual jika Anda ingin default baru

• Rebuild brain sistem: brain files dibangun ulang dari disk saat berubah, tanpa perlu restart

• Penemuan tools proaktif: mencari tools yang tersedia sebelum mengaku tidak bisa

• Analyzer prompt multi-bahasa (v0.3.67): PromptAnalyzer bersama dengan dorongan lembut di TUI dan Telegram, 6 paket bahasa (EN/ES/FR/ID/PT/RU)

• Mode rencana (v0.3.67-v0.3.68): trek design/checklist, kartu rencana persisten, perintah /plan <query>, persetujuan-diri agen saat pengguna memberi otonomi

• Klik-untuk-membuka (v0.3.69): klik kiri pada blok tool-call atau penalaran untuk membuka blok itu saja, melengkapi Ctrl+O

• review_gate skills (v0.3.70): deklarasi frontmatter untuk skills berisiko tinggi yang memerlukan persetujuan pengguna sebelum efek samping

• Aktivasi tools JIT: tools extended diaktifkan sesuai permintaan, tanpa pra-registrasi

• Perbaikan konfigurasi otomatis: config.toml rusak diperbaiki otomatis, konfigurasi terakhir-yang-baik tidak pernah dirusak

• Manajemen anggaran konteks: ambang compaction 65% lunak / 90% keras dengan fallback LLM

• Deteksi stream macet: jendela bergulir 2048 byte menangkap pola berulang

• Pertahanan gaslighting: membuang pembuka penolakan-tool di tengah giliran

• Pengiriman hasil build (v0.3.61): hasil rebuild/evolve sampai ke siapa pun yang meminta, di semua channels dan TUI

UI Terminal

• Rendering markdown natif: penekanan, daftar, tautan, dan item tugas dirender langsung di terminal
• Pengukur tok/s waktu-nyata: token per detik secara langsung saat streaming
• Tampilan versi (v0.3.73): versi yang berjalan ditampilkan di header TUI dan di /help + /usage channel
• Pembukaan penalaran 3-keadaan (v0.3.74): klik atau Ctrl+O memutar blok penalaran tertutup → dibatasi → penuh, jadi tidak pernah membanjiri tampilan
• Header per giliran (v0.3.75): setiap giliran mendapat header ringkasan satu baris, proses berpikirnya dilipat ke dalamnya, dan giliran terlipat secara default sehingga tampilan tetap bersih
• Pengelompokan tool call (v0.3.61): tool call beruntun dilipat menjadi satu blok yang bisa dibuka, menjaga TUI tetap bersih selama operasi banyak langkah
• Lipatan teks menengah (v0.3.61): teks pemrosesan menengah dilipat ke log di tempat yang sama dengan tool call, jadi hanya jawaban akhir yang tetap terlihat
• Pencarian session: filter pencarian + gulir viewport di semua sessions
• Panel terpisah: sessions paralel gaya tmux dengan persistensi layout
• Tempel gambar dari clipboard: tempel gambar dari browser atau aplikasi apa pun langsung ke TUI
• Penyematan rencana: rencana aktif disemat di akhir prompt setiap giliran
• Onboarding digerakkan agen: penyiapan pertama yang dipersonalisasi dengan alur terpandu
• Loop otonom /goal: tetapkan tujuan dan agen berputar sampai juri LLM bilang selesai, dengan kontrol jeda/lanjut/status
• Penetapan tujuan sendiri (v0.3.61): agen bisa menetapkan dan menggerakkan tujuan multi-gilirannya sendiri lewat tool goal_manage tanpa pengguna memanggil /goal

Pengalaman Developer

• 50+ tools bawaan: operasi file, bash, pencarian web, eksekusi kode, otomasi browser, generasi gambar, suara, rendering PDF
• Pencarian web paralel terpadu (v0.3.73): web_search, exa_search, dan brave_search menyebar paralel di bawah satu tool web_search
• web_scrape: scraping URL-ke-markdown natif dengan proteksi SSRF, perayapan sitemap, deteksi JS-shell, dan ekspor sadar-profil
• Deteksi captcha DDG (v0.3.73): captcha DuckDuckGo terdeteksi lewat HTTP 202 + pemeriksaan form struktural
• Skill /github bawaan: kendali penuh gh CLI untuk issues, PR, review kode, dan manajemen repo
• Penemuan tools proaktif: agen menemukan tools sebelum bilang “saya tidak bisa”
• Sistem skills: templat alur kerja dengan pencarian fuzzy, otomatis terdaftar sebagai slash command
• Tools dinamis: didefinisikan saat runtime lewat TOML (eksekutor HTTP + shell)
• Sistem projects: sessions khusus dengan overlay brain per proyek, pengarsipan file, dan lencana warna
• Editing hashline: editing file berjangkar hash dengan dukungan batch dan deteksi tabrakan
• Mission Control: dasbor layar penuh dengan kotak masuk RSI, log aktivitas, dan jadwal cron
• Unduh-otomatis RTK: proxy 4MB bawaan untuk penghematan token 53,5% pada 100+ perintah
• Proteksi file rahasia: kunci SSH, .env, kredensial terlindungi secara default
• AGENTS selalu dimuat: aturan keras dan tata kelola ditegakkan setiap giliran
• debug_logs dari konfigurasi (v0.3.71): aktif/nonaktifkan log debug dengan hot-reload, tanpa restart
• Cakupan redaksi rahasia (v0.3.71): batasi redaksi ke global/grup/DM dengan perintah /redact
• Cakupan redaksi rahasia (v0.3.71): batasi redaksi ke global/grup/DM dengan perintah /redact
• debug_logs dari konfigurasi (v0.3.71): aktif/nonaktifkan log debug dengan hot-reload, tanpa restart
• Anjing penjaga Tmux (v0.3.71): hanya membunuh pane, peringatan 30 detik, sambung-ulang otomatis
• Gerbang rencana tiga-keadaan (v0.3.71): GateDecision dengan bash menuju persetujuan di Editing pasca-init
• ToolHints gaya MCP (v0.3.71): model risiko untuk klasifikasi tools, menggerakkan gerbang rencana

Browser Automation

• Dukungan CDP penuh: navigasi, klik, ketik, tangkapan layar, JS eval, cari elemen
• Mode headless atau headed dengan tangkapan layar per elemen
• Persistensi cookie/session lintas sesi browser
• Isolasi tab per session: tidak ada penginjakan DOM lintas session

Penemuan Direktif Proyek (v0.3.59)

OpenCrabs otomatis menemukan file aturan yang ditinggalkan tools coding AI lain di sebuah repo. Arahkan agen ke repositori mana pun (lewat /cd, workspace channel, atau menjalankannya di dalamnya) dan ia memindai konvensi dari Claude Code, Cursor, Windsurf, Cline, Gemini CLI, GitHub Copilot, OpenCode, dan standar lintas-tool AGENTS.md. Tanpa konfigurasi, tanpa langkah impor.

Indeks dibangun ulang saat Anda /cd ke direktori baru, jadi file direktif selalu mutakhir.

Mulai Cepat

# Install (Linux/macOS)
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
OS=$(uname -s | tr A-Z a-z)
TAG=$(command -v jq >/dev/null 2>&1 && curl -s https://api.github.com/repos/opencrabs/opencrabs/releases/latest | jq -r .tag_name || curl -s https://api.github.com/repos/opencrabs/opencrabs/releases/latest | grep -o '"tag_name":"[^"]*"' | cut -d'"' -f4)
curl -fsSL "https://github.com/opencrabs/opencrabs/releases/download/${TAG}/opencrabs-${TAG}-${OS}-${ARCH}.tar.gz" | tar xz
./opencrabs

# Or via Cargo (requires Rust 1.94+)
cargo install opencrabs --locked

Pembaruan otomatis aktif secara default. Nonaktifkan dengan [agent] auto_update = false di ~/.opencrabs/config.toml.

Architecture

┌─────────────────────────────────────────┐
│           OpenCrabs Binary              │
│  (Single 34-36 MB Rust executable)      │
├─────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────────┐  │
│  │   TUI       │  │   CLI Daemon    │  │
│  │  (crossterm)│  │  (systemd/launchd)││
│  └─────────────┘  └─────────────────┘  │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │        Provider Registry         │   │
│  │  15 built-in + Custom OpenAI    │   │
│  │  Sticky fallback chain          │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │        Tool Layer                │   │
│  │  50+ built-in tools             │   │
│  │  Dynamic tools via TOML         │   │
│  │  JIT activation                 │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │        Channel Adapters          │   │
│  │  Telegram / Discord / Slack /    │   │
│  │  WhatsApp / Trello / Voice      │   │
│  └────────────────���────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │        Self-Healing Layer       │   │
│  │  Context budget / Stuck stream  │   │
│  │  Phantom detection / RSI        │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │        Persistence              │   │
│  │  SQLite + Brain files           │   │
│  │  FTS5 + vector search           │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘

Langkah Berikutnya

• Instalasi: instal dan konfigurasi
• Konfigurasi: semua opsi konfigurasi
• Provider: sambungkan backend LLM Anda
• Channels: sambungkan Telegram, Discord, dll.
• Tools: jelajahi 50+ kemampuan bawaan
• Self-Healing: fitur ketahanan
• Multi-Agent: orkestrasi sub-agent dan tim

Komunitas & Dukungan

• Komunitas Telegram: gabung grup OpenCrabs untuk tanya-jawab, tips, dan obrolan rilis
• Sponsor di GitHub: dukung proyek dan jaga kenyang para kepiting
• Buy Me A Coffee: dukungan sekali bayar jika OpenCrabs menyelamatkan sore Anda

Menemukan bug atau ingin fitur? Buka issue di GitHub.

Installation

Five ways to get OpenCrabs running.

Quick install (Linux and macOS)

The fastest path. One command resolves the latest release, checks your platform, verifies the download against the published SHA256SUMS, installs opencrabs and the rtk helper, and installs the system libraries the Linux build needs.

curl -fsSL https://opencrabs.com/install.sh | bash

On Windows, use PowerShell:

iwr -useb https://opencrabs.com/install.ps1 | iex

It installs to /usr/local/bin when that directory is writable, otherwise to ~/.local/bin, and prints the export PATH line when the target is not on your PATH yet. It refuses to install when glibc is older than 2.38 (Ubuntu 24.04+, Debian 13+, Fedora 39+) or when the system uses musl, and it names the package to install instead of failing silently.

Flags go after bash -s -- when you pipe the script:

Both scripts are plain shell and PowerShell, readable before you run them: install.sh and install.ps1.

Cara 1: Homebrew (disarankan di macOS dan Linux)

brew install opencrabs

OpenCrabs is in homebrew-core. Homebrew ships prebuilt bottles for Apple Silicon Macs (macOS 15 and newer) and for Linux amd64 and arm64, so no Rust toolchain is needed there. On an Intel Mac, Homebrew builds it from source instead; use the macos-amd64 release binary if you’d rather skip the build.

Jalankan opencrabs setelah instalasi. Langsung masuk ke chat dengan provider bawaannya sudah aktif, jadi crab menyapa Anda dan Anda bisa mulai bicara. Jalankan opencrabs --onboard kalau Anda mau wizard penyiapan.

Cara 2: Unduh Biner (semua platform)

Ambil biner siap pakai dari GitHub Releases.

Linux (amd64)

sudo apt update && sudo apt install -y curl jq libgomp1
TAG=$(curl -sL https://api.github.com/repos/opencrabs/opencrabs/releases/latest | jq -r .tag_name)
curl -fsSL "https://github.com/opencrabs/opencrabs/releases/download/${TAG}/opencrabs-${TAG}-linux-amd64.tar.gz" | tar xz
./opencrabs

Linux (arm64)

sudo apt update && sudo apt install -y curl jq libgomp1
TAG=$(curl -sL https://api.github.com/repos/opencrabs/opencrabs/releases/latest | jq -r .tag_name)
curl -fsSL "https://github.com/opencrabs/opencrabs/releases/download/${TAG}/opencrabs-${TAG}-linux-arm64.tar.gz" | tar xz
./opencrabs

macOS (arm64 / Apple Silicon)

TAG=$(curl -sL https://api.github.com/repos/opencrabs/opencrabs/releases/latest | jq -r .tag_name)
curl -fsSL "https://github.com/opencrabs/opencrabs/releases/download/${TAG}/opencrabs-${TAG}-macos-arm64.tar.gz" | tar xz
./opencrabs

Windows

$tag = (Invoke-RestMethod https://api.github.com/repos/opencrabs/opencrabs/releases/latest).tag_name
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest "https://github.com/opencrabs/opencrabs/releases/download/$tag/opencrabs-$tag-windows-amd64.zip" -OutFile opencrabs.zip -UseBasicParsing
Expand-Archive opencrabs.zip -DestinationPath . -Force
.\opencrabs.exe

Ia langsung masuk ke chat dengan provider bawaannya sudah aktif. Jalankan opencrabs --onboard kalau Anda mau wizard penyiapan.

Windows adalah platform kelas satu (v0.5.3): penanganan shell yang sadar platform, pembacaan BOM/UTF-16 dan fallback tilde/cwd bawaan, dan CI membangun Windows di setiap PR (#627).

Verifikasi unduhan Anda (opsional): setiap rilis menerbitkan file SHA256SUMS bersama tarball-nya.

Perlu izin terminal. OpenCrabs membaca/menulis brain files, konfigurasi, dan file proyek. Aplikasi terminal Anda butuh akses sistem file atau OS akan memblokir operasi.

OS	Yang perlu dilakukan
macOS	Pengaturan Sistem → Privasi & Keamanan → Akses Disk Penuh → nyalakan aplikasi terminal Anda (Alacritty, iTerm2, Terminal, dll.). Jika tidak ada di daftar, klik “+” dan tambahkan dari /Applications/. Tanpa ini, macOS terus-menerus memunculkan “ingin mengakses data dari aplikasi lain”.
Windows	Jalankan terminal (Windows Terminal, PowerShell, cmd) sebagai Administrator saat pertama kali, atau beri terminal akses tulis ke %USERPROFILE%\.opencrabs\ dan direktori proyek Anda. Windows Defender juga mungkin bertanya, klik “Izinkan”.
Linux	Pastikan user Anda memiliki ~/.opencrabs/ dan direktori proyek. Di sistem SELinux/AppArmor, proses terminal butuh akses baca/tulis ke path tersebut. Terminal Flatpak/Snap mungkin perlu --filesystem=home atau izin setara.

/rebuild bekerja bahkan dengan biner siap pakai: ia meng-klon sumber ke ~/.opencrabs/source/ saat pertama dipakai, lalu membangun dan hot-restart.

Cara 3: Bangun dari Sumber

Diperlukan untuk /rebuild, menambah tools kustom, atau memodifikasi agen.

Penyiapan cepat (disarankan)

Skrip penyiapan otomatis mendeteksi platform Anda (macOS, Debian/Ubuntu, Fedora/RHEL, Arch) dan memasang semua dependensi build + Rust:

# Install all dependencies
curl -fsSL https://raw.githubusercontent.com/opencrabs/opencrabs/main/src/scripts/setup.sh | bash

# Clone and build
git clone https://github.com/opencrabs/opencrabs.git
cd opencrabs
cargo build --release
./target/release/opencrabs

Penyiapan manual

Jika Anda lebih suka memasang dependensi sendiri:

• Rust stable: pasang Rust. Toolchain stable bekerja sejak v0.2.85
• Kunci API dari minimal satu provider yang didukung
• SQLite (di-bundle lewat rusqlite)
• macOS: brew install cmake pkg-config
• Debian/Ubuntu: sudo apt install build-essential pkg-config libssl-dev cmake
• Fedora/RHEL: sudo dnf install gcc gcc-c++ make pkg-config openssl-devel cmake
• Arch: sudo pacman -S base-devel pkg-config openssl cmake

git clone https://github.com/opencrabs/opencrabs.git
cd opencrabs
cargo build --release
./target/release/opencrabs

OpenCrabs memakai keys.toml alih-alih .env untuk kunci API. Wizard onboarding akan membantu menyiapkannya, atau edit ~/.opencrabs/keys.toml langsung.

Cara 4: Docker

Jalankan OpenCrabs dalam kontainer terisolasi. Build memakan ~15 menit (Rust release + LTO).

git clone https://github.com/opencrabs/opencrabs.git
cd opencrabs
docker compose -f src/docker/compose.yml up --build

Konfigurasi, workspace, dan DB memori bertahan di volume Docker lintas restart. Kunci API di keys.toml dipasang ke kontainer saat runtime, tidak pernah dibakar ke dalam image.

Mulai Otomatis saat Boot

Jaga OpenCrabs berjalan sebagai daemon latar belakang yang menyala bersama sistem Anda.

Linux (systemd)

The binary writes the unit itself, so the file cannot drift from the version you are running:

opencrabs service install

That writes ~/.config/systemd/user/opencrabs.service with Type=simple and OOMPolicy=continue, then reloads systemd. Start it with opencrabs service start: a user unit does not come back after a reboot unless lingering is enabled (see below), while a system-wide unit is enabled so it does. OOMPolicy=continue matters because the daemon is the parent of every tool call and cron child: without it, one child killed by the OOM killer stops the whole unit and takes every agent lane with it. The unit name carries the profile when you are not on default, as opencrabs-<profile>.service.

On a headless SSH session the per-user systemd bus is often missing, and the command fails with Failed to connect to bus. Enable lingering so the user service runs without a login, or install a system-wide unit instead:

sudo loginctl enable-linger $(whoami)
# or
sudo opencrabs service install

Manage the daemon with opencrabs service start|stop|restart|status, or with systemctl directly.

Cek status: systemctl --user status opencrabs | Log: journalctl --user -u opencrabs -f

macOS (launchd)

cat > ~/Library/LaunchAgents/com.opencrabs.agent.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.opencrabs.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/opencrabs</string>
        <string>daemon</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/opencrabs.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/opencrabs.err</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.opencrabs.agent.plist

Perbarui path di ProgramArguments agar cocok dengan lokasi instal Anda.

Windows (Task Scheduler)

1. Win + R → taskschd.msc
2. Create Basic Task → Nama: OpenCrabs
3. Pemicu: When I log on
4. Aksi: Start a program → C:\Users\<you>\.cargo\bin\opencrabs.exe, Argumen: daemon
5. Di Properties > Settings, centang If the task fails, restart every 1 minute

Atau lewat PowerShell:

$action = New-ScheduledTaskAction -Execute "$env:USERPROFILE\.cargo\bin\opencrabs.exe" -Argument "daemon"
$trigger = New-ScheduledTaskTrigger -AtLogon
$settings = New-ScheduledTaskSettingsSet -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1)
Register-ScheduledTask -TaskName "OpenCrabs" -Action $action -Trigger $trigger -Settings $settings

Pembaruan

• Pengguna Homebrew: brew upgrade opencrabs (jika Anda ketik /evolve pada instalasi Homebrew, ia mendelegasikan ke Homebrew, biner tetap dikelola brew, dan tap lama dipensiunkan demi autobump homebrew-core)
• Pengguna biner: ketik /evolve di TUI untuk mengunduh rilis terbaru
• Pengguna sumber: git pull && cargo build --release, atau ketik /rebuild di TUI
• Pengguna Docker: docker compose pull && docker compose up -d

Onboarding

A first run does not open the wizard. OpenCrabs goes straight to the chat, with its built-in provider already provisioned and the agent greeting you. The onboarding wizard is opt-in: run opencrabs --onboard, or /onboard from inside a session.

Panduan video ada di halaman Video Onboarding.

Mulai Cepat (3 menit)

Jalur cepat ini membuat Anda bisa mengobrol dengan agent dalam waktu kurang dari 3 menit.

Pengaturan Lanjutan (7 menit)

Pengaturan lengkap dengan Telegram, suara lokal, vision, dan pembuatan gambar.

Alur Onboarding

Wizard ini adalah TUI yang dikendalikan keyboard dengan 8 langkah. Navigasi dengan tombol panah, Tab untuk maju, Esc untuk kembali.

Pengaturan Channel (Langkah 4)

Layar channel menampilkan 5 integrasi: Telegram, Discord, WhatsApp, Slack, Trello.

• Space mengaktifkan atau menonaktifkan channel
• Enter pada channel yang aktif membuka layar pengaturannya (token, ID, allowlist)
• Enter pada Continue atau Tab melewati ke langkah berikutnya
• Setiap layar pengaturan channel memiliki tombol Test Connection

Lihat Ringkasan Channels untuk panduan navigasi lengkap.

Menjalankan Ulang Pengaturan

Anda dapat langsung ke langkah mana pun tanpa menjalankan ulang seluruh wizard:

Setelah onboarding, agent Anda aktif dan memperkenalkan diri. Ia membaca file brain-nya (SOUL.md, AGENTS.md, TOOLS.md) dan memulai percakapan.

Bootstrap

Pada saat pertama kali dijalankan, agent melewati fase bootstrap:

• Mengenal Anda (nama, preferensi, gaya kerja)
• Menentukan identitasnya (nama, kepribadian, emoji)
• Membuka SOUL.md bersama Anda untuk membahas nilai-nilai
• Menyiapkan USER.md dengan profil Anda

File bootstrap (BOOTSTRAP.md) akan menghapus dirinya sendiri setelah selesai.

Migrasi dari Tool Lain

Sudah memakai ClaudeCode, OpenClaw, Hermes, atau harness agent AI lainnya? Agent Anda dapat memindahkan data yang sudah ada (memori, skill, perintah kustom, preferensi) ke file brain miliknya menggunakan bahasa alami. Tidak perlu memindahkan file secara manual.

Ini berfungsi dengan semua agent atau harness coding yang menyimpan konfigurasi secara lokal. Migrasi mencari direktori konfigurasi tool lain di filesystem Anda, membaca isinya, dan memetakannya ke format file brain OpenCrabs (SOUL.md, USER.md, TOOLS.md, MEMORY.md, AGENTS.md, CODE.md).

Migrasi Terpandu

Jika Anda ingin meninjau apa saja yang akan dimigrasi sebelum prosesnya berjalan:

Cari data ClaudeCode/OpenClaw/Hermes saya secara lokal (atau harness agent lain yang pernah saya pakai) dan audit migrasi ke file brain kita, laporkan setelah selesai, jalankan setelah saya konfirmasi dan setujui.

Agent akan:

1. Mencari direktori konfigurasi tool lain di filesystem Anda
2. Membaca dan mengurai semua file terkait (memori, perintah, skill, preferensi)
3. Membuat audit yang menunjukkan secara tepat apa dipetakan ke mana
4. Menunggu konfirmasi Anda
5. Menjalankan migrasi dan melaporkan rincian lengkap

Migrasi Otomatis

Jika Anda ingin langsung selesai:

Cari data agent/harness saya yang sudah ada secara lokal dan migrasikan semuanya ke file brain kita, tanpa perlu persetujuan saya. Langsung rencanakan dan jalankan, lalu laporkan setelah selesai dengan rincian lengkap.

Agent melewati langkah audit, merencanakan migrasi secara internal, menjalankannya, dan memberi Anda ringkasan semua yang dipindahkan.

Apa yang Dipetakan

Tips: Jalankan migrasi tepat setelah onboarding selagi konteksnya masih segar. Agent sudah memiliki USER.md dan SOUL.md Anda dari wizard, sehingga ia dapat menggabungkan data secara cerdas alih-alih menimpanya.

Perintah Utama

Mode Persetujuan

Atur seberapa besar otonomi yang dimiliki agent:

Direktori Kerja

Agent bekerja di dalam direktori kerja untuk operasi file. Ubah dengan:

• Perintah /cd di chat
• Pemilih direktori di TUI (Tab untuk memilih)
• Tool config_manager set_working_directory

Direktori kerja disimpan per sesi. Saat berpindah sesi, direktori dipulihkan secara otomatis.

Petunjuk Filter Model (v0.3.78)

Pemilih model onboarding sekarang selalu menampilkan petunjuk filter di atas daftar model (“Type to filter…”). Sebelumnya, petunjuk ini hanya muncul setelah Anda mulai mengetik, sehingga pengguna tidak tahu bahwa filter tersedia. Selain itu, ID model yang diketik persis sekarang mengalahkan pencocokan substring: jika Anda mengetik claude-opus-4-8 secara persis, model tersebut dipilih meskipun model lain memiliki substring yang sama.

Video Onboarding

Video panduan instalasi dan onboarding OpenCrabs tersedia di kanal YouTube OpenCrabs. Setiap OS memiliki video mulai cepat dan video pengaturan lanjutan. Klik miniatur untuk memutar videonya di sini.

macOS

Install in under 2 minutes (Homebrew)

Advanced setup on macOS (Telegram, voice, images)

Ubuntu/Linux

Install in 3 minutes (one paste)

Advanced setup on Linux (Telegram, voice, images)

Windows

Install in 2 minutes (PowerShell)

Advanced setup on Windows (Telegram, voice, images)

Semua video: youtube.com/@OpenCrabs

Halaman Onboarding berisi langkah demi langkah jalur Mulai Cepat dan Lanjutan dalam bentuk teks.

Configuration

OpenCrabs uses two config files stored at ~/.opencrabs/:

Workspace Layout

~/.opencrabs/
├── config.toml          # Main configuration
├── keys.toml            # API keys (gitignored)
├── commands.toml        # Custom slash commands
├── opencrabs.db         # SQLite database
├── SOUL.md              # Agent personality
├── USER.md              # Your profile
├── MEMORY.md            # Long-term memory
├── AGENTS.md            # Agent behavior docs
├── TOOLS.md             # Tool reference
├── SECURITY.md          # Security policies
├── HEARTBEAT.md         # Periodic check tasks
├── memory/              # Daily memory notes
│   └── YYYY-MM-DD.md
├── images/              # Generated images
├── logs/                # Application logs
└── skills/              # Custom skills/plugins

Provider Configuration

See Provider Setup for detailed provider configuration.

Quick example: add Anthropic:

# config.toml
[providers.anthropic]
enabled = true
default_model = "claude-sonnet-4-20250514"

# keys.toml
[providers.anthropic]
api_key = "sk-ant-..."

Provider Priority

When multiple providers are enabled, the first one found in this order is used for new sessions:

MiniMax > OpenRouter > Anthropic > OpenAI > Gemini > Custom

Each session remembers which provider and model it was using. Switch providers per-session via /models.

Config Safety (v0.3.74)

A malformed line in config.toml or keys.toml corrupts the whole file and takes the agent down (no provider keys, no bot token, no way back in). v0.3.74 makes that class of failure nearly impossible:

• Config edits via config_manager only: the agent edits config.toml / keys.toml only through the config_manager tool, never with raw file edits. The write path validates the result and refuses anything that would break parsing (#715).
• Guard config-breaking writes: edit_file / write_file writes that would break config.toml / keys.toml are denied outright (#713).
• Re-validate before write: config is re-validated immediately before fs::write in the config_manager write paths (#714).
• Validate keys before snapshot: keys.toml is validated before it is saved as the last-good snapshot, so a bad snapshot can’t poison recovery (#712).

v0.3.79 hardened this further:

• Every config write is atomic (#911): a crash or a concurrent reader mid-write can never observe a half-written config.toml or keys.toml.
• Config loads no longer race on shared state, concurrent reloads can’t interleave and leave a torn config in memory.
• Reload failures are specific: a failed reload says what failed, and a write race is named as the transient condition it is instead of a scary generic error.
• Never select a provider you didn’t configure, fallback and model routing can no longer land on a provider section that doesn’t exist in your config.

Agent Behavior

[agent]
working_directory = "/path/to/default/dir"
thinking = "on"                     # "on", "off", or "budget_XXk"
approval_policy = "auto-always"     # "ask", "auto-session", "auto-always"
max_concurrent = 4                  # max parallel tool calls
context_limit = 200000              # context window cap (tokens)
max_tokens = 65536                  # max output tokens per API call
auto_update = true                  # auto-install releases on startup
silent_compaction = false           # suppress post-compaction personality narration
compaction_notice = false            # show the compaction notice pair; off by default (v0.5.4)
lazy_tools = true                   # JIT tool-schema loading (ships core + tool_search only)
redact_sensitive_data = true        # redact API keys, tokens, passwords, IPs from output
debug_logs = false                  # enable debug file logging (hot-reloads, no restart)
default_provider = "minimax"        # fallback provider when no provider is active (v0.3.62)
default_model = "MiniMax-M2.7"      # fallback model when no model is active (v0.3.62)

Timeout flags resolve per provider first: [providers.<name>] wins over [agent], which wins over the built-in default, and every provider family honours the chain, anthropic and gemini included (v0.5.4, #1688).

Sub-agent and RSI Overrides

Route spawned sub-agents and RSI (self-improvement) cycles to separate providers so they never compete with your main chat for quota:

[agent]
subagent_provider = "minimax"           # provider for spawned sub-agents
subagent_model = "MiniMax-M2.7"         # model for spawned sub-agents
self_improvement_provider = "minimax"   # provider for RSI self-improvement cycles
self_improvement_model = "MiniMax-M2.7" # model for RSI cycles

Channel Configuration

Telegram

[channels.telegram]
enabled = true
token = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
allowed_users = ["123456789"]       # numeric Telegram user IDs
allowed_channels = ["-100123456"]   # restrict to specific group/channel IDs (empty = all)
respond_to = "mention"              # "all", "dm_only", "mention" (default)
session_idle_hours = 24.0           # idle timeout for non-owner sessions
rich_messages = true                # native Telegram rich messages (Bot API 10.1, default since v0.3.64)
silence_group_start = true          # silently ignore /start from non-allowed users in groups
bot_owner = ["123456789"]           # owner IDs (gated commands, /cd hidden dirs, /profiles)

Discord

[channels.discord]
enabled = true
token = "your-discord-bot-token"
allowed_users = ["123456789012345678"]
allowed_channels = ["123456789012345678"]
respond_to = "mention"
session_idle_hours = 24.0

Slack

[channels.slack]
enabled = true
token = "xoxb-your-bot-token"
app_token = "xapp-your-app-token"      # Socket Mode token
allowed_users = ["U12345678"]
allowed_channels = ["C12345678"]
respond_to = "mention"
session_idle_hours = 24.0

WhatsApp

[channels.whatsapp]
enabled = true
allowed_phones = ["+15551234567"]      # E.164 format
session_idle_hours = 24.0

Trello

[channels.trello]
enabled = true
token = "your-trello-api-token"
app_token = "your-trello-api-key"
allowed_users = ["memberId1"]
board_ids = ["boardId1", "boardId2"]
poll_interval_secs = 60
session_idle_hours = 24.0

Other Channels (Preview)

Signal, Google Chat, and iMessage are available as preview placeholders:

[channels.signal]
enabled = true
allowed_phones = ["+15551234567"]

[channels.google_chat]
enabled = true
token = "your-google-chat-token"
allowed_users = ["user@example.com"]

[channels.imessage]
enabled = true
allowed_phones = ["+15551234567"]

Cron Defaults

Route cron jobs to cheaper providers so they never compete with your interactive session:

[cron]
default_provider = "minimax"
default_model = "MiniMax-M2.7"

Memory and Embeddings

[memory]
vector_enabled = true

[memory.embedding]
url = "https://api.openai.com/v1"
model = "text-embedding-3-small"
# api_key loaded from keys.toml: [providers.memory_embedding] api_key = "sk-..."
# dimensions = 1536  # auto-detected from first API response if unset

When [memory.embedding] is not set, embeddings are generated locally via the embeddinggemma-300M GGUF model (~300MB download, ~2.9GB RAM). Setting [memory.embedding] with an API endpoint eliminates the local model overhead.

To index your own docs (or an entire scraped docs site) into memory search, see Memory System → External Index Paths for the full knowledge-base workflow.

Brain Files

[brain]
strip_empty_sections = true
default_cap = 500

[brain.caps]
SOUL.md = 300
AGENTS.md = 800

Browser

[browser]
cdp_endpoint = "http://localhost:9222"

To start a standalone Chromium with CDP enabled:

chromium --remote-debugging-port=9222 --headless --no-sandbox

A2A (Agent-to-Agent) Gateway

[a2a]
enabled = false
bind = "127.0.0.1"
port = 18790
allowed_origins = ["https://your-app.com"]
# api_key = "your-secret-key"  # Bearer token for incoming requests

Daemon Mode

[daemon]
health_port = 8080

OpenCrabs runs in two modes: TUI (interactive terminal UI with chat) and Daemon (headless background service for channels + cron). For any one profile, run only one at a time. The TUI always wins: opening it while a daemon runs shuts the daemon down and takes over the channels.

For full service lifecycle management (TUI vs Daemon comparison, opencrabs service install/start/stop, profile-aware services, OPENCRABS_PROFILE env var, troubleshooting), see the CLI Commands reference.

Image Generation and Vision

[image.generation]
enabled = true
model = "gemini-3.1-flash-image-preview"

[image.vision]
enabled = true
model = "gemini-3.1-flash-image-preview"
provider = "openrouter"           # bypasses enabled gate for vision-only providers (v0.3.63)

Vision analysis automatically scans all enabled providers (Google, OpenRouter, OpenAI-compatible, Anthropic) before returning an error. No configuration needed.

Voice Provider Fallback

STT and TTS providers support automatic failover via fallback_chain. When the primary returns a 5xx, fails a liveness probe (Voicebox), or is otherwise unreachable, the dispatcher walks the chain in order and tries each entry that has the credentials/config it needs.

[providers.stt]
fallback_chain = ["groq", "openai_compatible", "local"]

[providers.tts]
fallback_chain = ["openai_compatible", "openai", "local"]

Empty or omitted chain means “use the default priority order with the primary removed.”

TOML Bash Blocklist (v0.3.78)

A new TOML-driven bash blocklist provides runtime-configurable safety gates for shell commands. The blocklist lives in a TOML file and defines patterns that the agent’s bash tool will refuse to execute:

# safety.toml (example)
[bash_blocklist]
patterns = ["rm -rf /", "dd if=", "mkfs", ":(){ :|:& };:"]

• Patterns are matched against the command string before execution
• The blocklist reloads on file change (no restart needed)
• Configurable per-profile, so different environments can have different safety gates
• Blocked commands return a clear error explaining which pattern matched

This replaces hardcoded safety checks with a user-extensible system. You can add project-specific dangerous commands without code changes.

Safety TOML Reload (v0.3.78)

All safety-related TOML files (bash blocklist, brain verification rules) now hot-reload on change. Edit the file and the new rules take effect immediately on the next tool call. No restart, no /reload, no config manager dance.

CLI Commands

OpenCrabs punya CLI lengkap dengan 20+ subperintah untuk mengelola setiap aspek agen.

Penggunaan

opencrabs [COMMAND] [OPTIONS]

Perintah

Flag Konfigurasi

Pintasan Keyboard (TUI)

Prompt Pembaruan Saat Startup

Saat versi baru tersedia, dialog di tengah muncul di layar splash menawarkan menerima (Enter) atau lewati (Esc). Menerima otomatis memicu /evolve. Setelah pembaruan, biner restart dan splash menampilkan versi baru.

Perintah Channel

/doctor, /help, /usage, /evolve, /restart, /exit, dan perintah sistem bekerja langsung di Telegram, Discord, Slack, dan WhatsApp tanpa melalui LLM. Dieksekusi seketika dan mengembalikan hasil di channel.

/restart dan /exit mengumumkan diri sebelum bertindak, karena begitu prosesnya hilang tidak ada yang tersisa untuk melaporkan kegagalan. Keduanya hanya untuk owner, seperti semua perintah lain yang mengubah proses yang berjalan. /exit adalah satu-satunya perintah tanpa jalan kembali dari chat: pemulihan butuh akses ke mesin tempat OpenCrabs berjalan.

Sejak v0.3.80, stop dengan bahasa natural juga dihormati, menyuruh bot berhenti dengan bahasa sehari-hari bekerja di channels dan TUI, bukan hanya kata polos “stop”.

Seluruh logika perintah channel dipusatkan di src/channels/commands.rs (847 baris) – handler bersama yang menghapus duplikasi logika perintah di 5 implementasi channel. Setiap channel mendelegasikan ke try_execute_text_command() untuk perilaku yang konsisten.

/evolve di channels kini berjalan langsung (mengunduh + memasang biner) tanpa bolak-balik LLM. Sebelumnya diarahkan melalui agen.

Mode Chat

# Default: launch TUI
opencrabs

# Same as above
opencrabs chat

Mode Agen

Mode non-interaktif untuk skrip dan otomasi:

# Interactive multi-turn chat
opencrabs agent

# Single-message mode
opencrabs agent -m "File apa yang berubah hari ini?"

Mode Daemon vs TUI

OpenCrabs berjalan dalam salah satu dari dua mode. Pilih yang cocok untuk mesinnya. Untuk satu profil, jalankan hanya satu pada satu waktu.

Kenapa tidak keduanya sekaligus?

Satu kredensial bot (mis. token Telegram) hanya bisa memegang satu poll getUpdates yang hidup. Jika daemon dan TUI sama-sama memegang token profil yang sama, mereka berkelahi (HTTP 409) dan channel jatuh.

TUI selalu menang

Saat Anda membuka TUI ketika daemon untuk profil yang sama sedang berjalan, TUI mematikan daemon itu lebih dulu, mengambil alih channels, dan menampilkan banner tentang hal itu. Channels Anda sudah terpasang, jadi mereka cukup lanjut tanpa menyambung ulang. Daemon tetap mati sampai Anda menyalakannya lagi (opencrabs service start, atau jalankan ulang opencrabs daemon).

Di mesin tempat daemon biasanya berjalan, alur sehari-harinya: buka opencrabs saat ingin duduk bersamanya; tutup TUI dan jalankan opencrabs service start saat ingin headless lagi.

Mulai otomatis saat boot

• Daemon: gunakan installer layanan (opencrabs service install); ia memasang systemd (Linux) / launchd (macOS) untuk mulai saat boot dan restart saat crash. Ini setup selalu-aktif yang disarankan.
• TUI: agar UI terminal terbuka otomatis saat login, gunakan autostart terminal/desktop, bukan installer layanan:
  • Desktop Linux: taruh file .desktop di ~/.config/autostart/ dengan Exec=x-terminal-emulator -e opencrabs.
  • macOS: Pengaturan Sistem > Umum > Item Login > tambahkan skrip .command yang menjalankan opencrabs.
  • VPS lewat SSH: jalankan di dalam tmux/screen dan sambungkan ulang. Di VPS headless Anda biasanya ingin daemon, bukan TUI.

Sangat disarankan untuk pengguna harian. Jika Anda berencana memakai OpenCrabs setiap hari, mintalah ia menyiapkan dirinya sebagai layanan sistem. Cukup katakan semacam “siapkan dirimu untuk menyala bersama komputerku” atau “hapus layanan mulai-otomatisnya”. Agen menangani pemasangan dan penghapusan launchd (macOS) atau systemd (Linux) secara otomatis untuk Anda.

Menjaga TUI tetap berjalan di VPS (tmux)

Jika Anda ingin TUI interaktif lengkap selalu tersedia di server jauh (bukan daemon headless), tmux adalah jalannya. Session Anda bertahan dari koneksi SSH terputus, laptop tidur, dan koneksi tidak stabil.

1. Pasang tmux

# Debian / Ubuntu
sudo apt install tmux

# RHEL / CentOS / Fedora
sudo yum install tmux

2. Cari di mana opencrabs terpasang

which opencrabs

# If that returns nothing, search the whole filesystem
find / -name "opencrabs" -type f 2>/dev/null

3. Mulai sesi tmux bernama

tmux new -s opencrabs

4. Jalankan opencrabs di dalamnya

opencrabs

5. Lepaskan (opencrabs tetap berjalan)

Tekan Ctrl+B, lalu D. Anda kini bisa menutup SSH dan opencrabs tetap berjalan.

6. Sambungkan ulang nanti

tmux attach -t opencrabs

Sudah selesai. Kembali dari mesin mana pun, sambungkan ulang, dan lanjutkan dari tempat Anda berhenti. Jika Anda hanya butuh channels (Telegram, Discord, Slack, WhatsApp) berjalan headless tanpa TUI, daemon lebih cocok: opencrabs service install && opencrabs service start.

Endpoint Kesehatan

Tambahkan ke config.toml untuk membuka pemeriksaan kesehatan:

[daemon]
health_port = 8080

Lalu GET http://localhost:8080/health mengembalikan 200 OK dengan status JSON. Berguna untuk watchdog systemd, monitor uptime, atau load balancer.

Manajemen Layanan

Pasang OpenCrabs sebagai layanan sistem (launchd di macOS, systemd di Linux):

opencrabs service install
opencrabs service start
opencrabs service stop
opencrabs service restart
opencrabs service status
opencrabs service uninstall

Layanan sadar-profil

Setiap profil mendapat layanan mandirinya sendiri:

# Install a specific profile as a service
opencrabs -p hermes service install
opencrabs -p hermes service start

# Each profile gets its own service name
# macOS: com.opencrabs.daemon.hermes
# Linux: opencrabs-hermes.service

# Manage independently
opencrabs -p hermes service status
opencrabs -p hermes service stop
opencrabs -p hermes service uninstall

Beberapa profil bisa berjalan sebagai layanan daemon simultan dengan isolasi penuh.

Variabel lingkungan OPENCRABS_PROFILE

Set OPENCRABS_PROFILE=hermes untuk memilih profil tanpa flag -p. Berguna untuk layanan systemd, tugas cron, dan mode daemon.

Penanganan masalah: daemon tetap mati

Jika opencrabs service status bilang stopped:

1. Apakah Anda membuka TUI? Membuka opencrabs sengaja mematikan daemon agar session interaktif bisa memiliki channels. Daemon tetap mati sampai Anda menjalankan opencrabs service start lagi.
2. Build lama mungkin masih punya Restart=on-failure alih-alih Restart=always. Buat ulang unit dengan opencrabs service install (lalu service start) untuk mendapatkan kebijakan selalu-restart.
3. Konfigurasi, kunci, perintah, dan tools hot-reload saat runtime. Mengedit config.toml atau keys.toml tidak pernah butuh restart daemon. Jika perubahan tidak berlaku, periksa log untuk baris ConfigWatcher: reloaded alih-alih me-restart.

Manajemen Cron

# List all cron jobs
opencrabs cron list

# Add a new cron job
opencrabs cron add \
  --name "Daily Report" \
  --cron "0 9 * * *" \
  --tz "America/New_York" \
  --prompt "Check emails and summarize" \
  --provider anthropic \
  --model claude-sonnet-4-20250514 \
  --thinking off \
  --deliver-to telegram:123456

# Remove a cron job (accepts name or ID)
opencrabs cron remove "Daily Report"

# Enable/disable (accepts name or ID)
opencrabs cron enable "Daily Report"
opencrabs cron disable "Daily Report"

Pintasan Keyboard TUI

Troubleshooting

Common issues and how to fix them.

Windows Defender Blocking OpenCrabs

Windows Defender may flag opencrabs.exe as suspicious because it’s an unsigned binary that executes shell commands and makes network requests. This is a false positive.

Add an exclusion:

1. Open Windows Security → Virus & threat protection
2. Virus & threat protection settings → Manage settings
3. Exclusions → Add or remove exclusions
4. Add an exclusion → File → select opencrabs.exe

Or via PowerShell (admin):

Add-MpPreference -ExclusionPath "C:\path\to\opencrabs.exe"

If SmartScreen blocks the first run, click More info → Run anyway.

Binary Won’t Start or Crashes

Startup Errors

Run with debug logging to see what’s failing:

opencrabs -d chat

Logs are written to ~/.opencrabs/logs/.

Download a Previous Version

If the latest release crashes on your machine, download a previous working version from GitHub Releases:

# List all releases
gh release list -R opencrabs/opencrabs

# Download a specific version
gh release download v0.2.66 -R opencrabs/opencrabs -p "opencrabs-*$(uname -m)*$(uname -s | tr A-Z a-z)*"

/evolve: Update & Rollback

/evolve downloads the latest release from GitHub and hot-swaps the binary. It has built-in safety checks:

1. Download: Fetches the platform-specific binary from GitHub Releases
2. Pre-swap health check: Runs opencrabs health-check on the new binary (10s timeout). If it fails, the new binary is deleted and your current version stays untouched.
3. Backup: Creates a backup at <binary-path>.evolve_backup
4. Atomic swap: Replaces the current binary
5. Post-swap health check: Verifies the swapped binary works. If it fails, auto-rolls back to the backup.
6. Restart: exec()-restarts into the new version
7. Brain update prompt: After restart, your crab announces the new version, diffs brain templates against your local files, and offers to update them

If /evolve Fails

The most common reason is the health check caught an issue, your current version stays safe. If something went wrong after the swap:

# Restore the backup manually
cp /path/to/opencrabs.evolve_backup /path/to/opencrabs
chmod +x /path/to/opencrabs

Cargo Install Fallback

When /evolve uses cargo install (building from source), it tries the stable toolchain first. If that fails, it automatically falls back to cargo +nightly. The progress message shows which toolchain succeeded.

Check-Only Mode

The agent can check for updates without installing:

/evolve check_only=true

Bash Tool Safety

The bash tool includes a hard command blocklist that prevents catastrophic commands even if accidentally approved:

• rm -rf /, sudo rm -rf .
• mkfs, dd to /dev/
• Fork bombs
• /etc overwrites, /proc writes
• Sensitive file exfiltration
• Crypto mining commands

These are blocked at the tool level: no configuration needed.

Older CPUs (Pre-2011 / No AVX)

Some features require AVX/AVX2 instructions. Since v0.2.67, OpenCrabs detects CPU capabilities at runtime and automatically hides unavailable options in the onboarding wizard.

What’s Affected

Symptoms

• Local STT option doesn’t appear in /onboard:voice: your CPU lacks AVX2
• Local TTS (Piper) should always be available: no CPU restrictions, works on machines as old as 2007
• Memory search falls back to text-only FTS silently
• Crash with “illegal instruction” on very old CPUs

Fix: Build from Source with CPU Targeting

# For your specific CPU (best performance)
RUSTFLAGS="-C target-cpu=native" cargo build --release

# For Sandy Bridge (AVX but no AVX2)
RUSTFLAGS="-C target-cpu=sandybridge" cargo build --release

macOS with Apple Silicon

Local STT uses Metal GPU acceleration on macOS, no CPU flags needed. Works out of the box on M1/M2/M3/M4.

Config Issues

Config Won’t Load

If config.toml has a syntax error, OpenCrabs will fail to start. Restore from backup:

# Check if a backup exists
ls ~/.opencrabs/config.toml.backup

# Restore it
cp ~/.opencrabs/config.toml.backup ~/.opencrabs/config.toml

Or reinitialize with defaults:

opencrabs init --force

Warning: --force overwrites your config. Back up keys.toml first, it contains your API keys.

Manual Backup

Always keep a backup of your critical files:

cp ~/.opencrabs/config.toml ~/.opencrabs/config.toml.backup
cp ~/.opencrabs/keys.toml ~/.opencrabs/keys.toml.backup
cp ~/.opencrabs/commands.toml ~/.opencrabs/commands.toml.backup

RSI Has Never Run

Mission Control shows ⚠ RSI has never run: N tool event(s) recorded and unprocessed even though rsi_enabled = true is set.

Most common cause: self_improvement_provider is misspelled. Its value is the bare provider section name, no custom: prefix, no model appended:

[providers.custom.glm-53-max]              # the name is "glm-53-max"

[agent]
self_improvement_provider = "glm-53-max"   # ✅ not "custom:glm-53-max"
self_improvement_model = "..."             # the model goes in its own key

Checklist:

1. The provider value matches the config section name exactly ([providers.custom.moonshotai] → "moonshotai").
2. No custom: / custom. / custom/ prefix anywhere in a provider reference.
3. The model is in its own key (self_improvement_model), never appended to the provider.
4. Restart after fixing: Mission Control confirms cycles on the next run.

Fixed at source in opencrabs#1314: current main normalises misspelled values with a warning. Released versions fail silently, which is exactly why the spelling matters.

Channel Issues

Telegram

Bot not responding:

1. Verify token from @BotFather is in keys.toml
2. Check your numeric user ID is in allowed_users
3. If respond_to = "mention", you must @mention the bot in groups

Regenerate bot token:

1. Open @BotFather on Telegram
2. /mybots → select bot → API Token → Revoke
3. Copy new token to keys.toml under [channels.telegram]
4. Restart OpenCrabs

Re-setup from scratch: Run /onboard:channels in the TUI.

Telegram Won’t Connect / Reconnect

If the Telegram bot stops responding or you need to re-link it, re-run the channels setup and re-confirm the token + your numeric user ID.

Fix:

1. Run /onboard:channels (TUI: opens the wizard; on a channel: the agent walks you through it).
2. Paste your bot token again if it’s missing (get it from @BotFather).
3. Paste your numeric user ID and hit Enter to confirm.
4. If the bot sends you a message on Telegram, it worked.

On a channel you can do it in one line: /onboard:channels telegram <BOT_TOKEN> <YOUR_NUMERIC_ID>.

Why you have to provide your numeric ID: Telegram’s Bot API exposes only the bot’s identity from a token (via getMe), it has no way to reveal who created the bot in BotFather. A bot only learns a human’s ID when that human messages it. The onboarding wizard auto-detects your ID via getUpdates when you leave the field blank, but that only works if (a) you’ve already messaged the bot and (b) the bot isn’t already running and consuming those updates, which is exactly the case during a reconnect. So on reconnect, message the bot first, or just paste the ID (get it from @userinfobot).

WhatsApp

QR code / session expired:

WhatsApp sessions are stored at ~/.opencrabs/whatsapp/session.db. To reconnect:

# Delete the session file
rm ~/.opencrabs/whatsapp/session.db

# Re-pair via onboarding
opencrabs chat --onboard

Or press R on the WhatsApp onboarding screen to reset and get a fresh QR code.

Messages not received:

• Verify phone number is in allowed_phones using E.164 format: "+15551234567"
• Empty allowed_phones = [] means accept from everyone

WhatsApp Won’t Connect / Wrong Number Replying

Each OpenCrabs instance supports one WhatsApp account (one companion device). If you connected multiple numbers or the wrong number is replying, you need a full reset. The bot always uses the last number you connected.

Critical: Always reset the connection before connecting a new number. OpenCrabs only keeps the last paired number.

Full reset steps:

1. Remove ALL linked devices from WhatsApp. Open WhatsApp on your phone, go to Settings > Linked Devices, and remove every device in the list. Don’t bother hunting for the opencrabs one. A stale device left over from an earlier pairing is the usual reason the old number keeps replying, so the reliable fix is to clear them all and start fresh.
2. Reset the connection in OpenCrabs: in the TUI or from a channel, go to /onboard:channels and press R to reset the WhatsApp connection. Wait for confirmation that the reset is complete.
3. Re-pair from scratch: after the reset is confirmed, go to WhatsApp > Settings > Linked Devices > Link a Device and scan the new QR code shown by OpenCrabs.

If the bot still shows the old number after resetting, make sure you completed step 1 (removing the device from WhatsApp) before step 2.

Common issues:

Discord

Bot not receiving messages:

1. Ensure Message Content Intent is enabled in Discord Developer Portal → Bot settings
2. Required intents: gateway, guild_messages, direct_messages, message_content
3. Use the bot token (starts with MTk...), not the application ID

Regenerate token: Discord Developer Portal → Bot → Regenerate Token

Slack

Both tokens required:

• Bot token (xoxb-...): For sending messages
• App token (xapp-...): For Socket Mode (receiving events)

Without the app token, the bot can send but not receive messages.

Socket Mode: Must be enabled in app settings → Features → Socket Mode → ON

Trello

Setup:

1. Get API key: trello.com/app-key
2. Generate token from the same page
3. Add board_ids to config: the bot only monitors listed boards
4. Set poll_interval_secs > 0 to enable polling (default 0 = disabled)

General: Re-run Channel Setup

For any channel issues, re-run the onboarding wizard:

opencrabs chat --onboard

Or type /onboard:channels in the TUI.

Agent Hallucinating Tool Calls

If the agent starts sending tool call approvals that don’t render in the UI (meaning it believes it executed actions that never actually ran) the session context has become corrupted.

Fix: Start a new session.

1. Press / and type sessions (or navigate to the Sessions panel)
2. Press N to create a new session
3. Continue your work in the fresh session

This reliably resolves the issue. A fix is coming in a future release.

Claude Code CLI Refuses to Run as Root (VPS, Docker)

Symptom: the claude_cli provider is enabled and claude is authenticated, but every request fails as soon as it spawns. In the log the CLI exits immediately with a message about --dangerously-skip-permissions not being allowed for root, or the first spawn hangs waiting on a prompt nobody can answer.

Cause: OpenCrabs runs the CLI headless with --dangerously-skip-permissions (it owns tool execution itself, so the CLI never asks). Claude Code refuses that flag when the process runs as root unless it believes it is inside a sandbox, and on a fresh install it also wants a one-time interactive acknowledgement of that mode. A VPS or container where OpenCrabs runs as root hits both.

Fix: put the acknowledgement and the sandbox marker in the CLI’s own settings file, ~/.claude/settings.json for the user OpenCrabs runs as (/root/.claude/settings.json on a root box):

{
  "permissions": { "defaultMode": "bypassPermissions" },
  "skipDangerousModePermissionPrompt": true,
  "env": { "IS_SANDBOX": "1" }
}

Merge these keys into the file if it already exists (keep model, theme, and the rest). The CLI reads settings.json on every invocation, so no OpenCrabs restart is needed; the next spawn goes through. Verify as the same user:

echo "say OK" | claude -p --dangerously-skip-permissions

IS_SANDBOX=1 only tells Claude Code that the root check may be skipped. It does not sandbox anything, so keep the box firewalled the way you would for any root agent. On a desktop where OpenCrabs runs as your own user none of this is required.

Daemon Stays Down

Jika opencrabs service status bilang stopped:

1. Apakah Anda membuka TUI? Membuka opencrabs sengaja mematikan daemon agar session interaktif bisa memiliki channels. Daemon tetap mati sampai Anda menjalankan opencrabs service start lagi.
2. Build lama mungkin masih punya Restart=on-failure alih-alih Restart=always. Buat ulang unit dengan opencrabs service install (lalu service start) untuk mendapatkan kebijakan selalu-restart.
3. Konfigurasi, kunci, perintah, dan tools hot-reload saat runtime. Mengedit config.toml atau keys.toml tidak pernah butuh restart daemon. Jika perubahan tidak berlaku, periksa log untuk baris ConfigWatcher: reloaded alih-alih me-restart.

For full daemon/service documentation, see CLI Commands: Daemon Mode vs TUI.

Local STT (Speech-to-Text)

Since v0.2.67, local STT uses rwhisper (candle, pure Rust) instead of whisper-rs/ggml. On macOS, it uses Metal GPU acceleration automatically.

Models

Models download automatically from HuggingFace on first use.

Common Issues

Local STT option not showing in wizard: Your CPU lacks AVX2. Use API mode (Groq Whisper) instead, or build from source with RUSTFLAGS="-C target-cpu=native".

“No audio samples decoded”: Audio file is corrupt or unsupported format. Supported: OGG/Opus, WAV.

Transcription hangs: Times out after 300 seconds. Try a smaller model (quantized-tiny).

Model download fails: Check network connection. Models are fetched from HuggingFace.

Audio too short: Messages under 1 second are automatically padded to prevent tensor errors.

Disabling

[voice]
stt_enabled = false

Local TTS (Text-to-Speech)

Requirements

• Python 3 must be installed and in PATH
• Piper installs automatically in a venv at ~/.opencrabs/models/piper/venv/

Voices

Common Issues

“python3 -m venv failed”: Install Python 3. On Ubuntu: sudo apt install python3 python3-venv. On macOS: brew install python3.

“pip install piper-tts failed”: Network issue or pip corrupted. Fix pip first:

python3 -m pip install --upgrade pip

Telegram voice messages show no waveform: This was fixed in v0.2.64, audio is now properly encoded as OGG/Opus (RFC 7845). Update to latest version.

Voice preview not playing: Preview uses afplay (macOS), aplay (Linux), or powershell (Windows). Ensure audio output is available.

Re-setup

Run /onboard:voice in the TUI to reconfigure STT/TTS mode and re-download models.

Disabling

[voice]
tts_mode = "off"

Local Embeddings (Memory Search)

The memory search engine uses a ~300 MB embedding model (llama.cpp) for semantic search. It requires AVX on x86 CPUs.

Fallback

If embeddings can’t initialize (no AVX, download failed, disk full), memory search falls back to FTS-only (keyword matching). It still works, just less semantic.

Fix for Older CPUs

Build from source with CPU targeting (see Older CPUs above).

Model Location

Models are stored in ~/.local/share/opencrabs/models/ (platform-specific data directory).

Database Issues

Location

• Main database: ~/.opencrabs/opencrabs.db (SQLite + WAL)
• WhatsApp session: ~/.opencrabs/whatsapp/session.db

Database Corruption

SQLite with WAL mode is very resilient, but if corruption occurs:

# Back up the corrupted file first
cp ~/.opencrabs/opencrabs.db ~/.opencrabs/opencrabs.db.corrupt

# Reinitialize (WARNING: loses all history)
opencrabs db init

Migration Errors

The database automatically migrates on startup (11 migrations). If migrating from an older version with sqlx, the transition is handled automatically, no manual steps needed.

Building from Source

Quick Setup

curl -fsSL https://raw.githubusercontent.com/opencrabs/opencrabs/main/scripts/setup.sh | bash
git clone https://github.com/opencrabs/opencrabs.git && cd opencrabs
cargo build --release

Build Without Voice (Smaller Binary)

cargo build --release --no-default-features --features telegram,whatsapp,discord,slack,trello

Feature Flags

Debug Mode

Run with -d for verbose logging:

opencrabs -d chat

Logs go to ~/.opencrabs/logs/ with 7-day retention.

Supported AI Providers

OpenCrabs supports 15 built-in providers + Custom OpenAI Compatible. Switch between them at any time via /models in the TUI or any channel.

How It Works

• One provider active at a time per session: switch with /models
• Per-session isolation: each session remembers its own provider and model. Changing provider in the TUI does not affect other active sessions (Telegram, Discord, Slack)
• Fallback chain: configure automatic failover when the primary provider goes down
• Models fetched live: no binary update needed when providers add new models
• Function calling detection: OpenCrabs detects when a model doesn’t support tool use and warns you with a model switch suggestion, rather than silently failing
• tool_choice: "auto": sent automatically for OpenAI-compatible providers when tools are active, enabling function calling on models that require explicit opt-in
• vision_model works on ANY provider: add vision_model = "..." to any built-in or custom provider block and the agent routes incoming images through that model on the same endpoint. No second API key, no Gemini dependency. See Image Generation & Vision for the full two-path setup

Custom Provider Onboarding (v0.3.24)

Adding a custom OpenAI-compatible provider is now smoother:

• Paste-by-default: Ctrl+V / Cmd+V on the API key field pastes immediately, no need to tab into the field first
• Enter-to-load: type a model name not in the fetched list and press Enter, it’s added to the list and selected
• Field refresh: saved values (base URL, API key, model list) appear instantly without restarting the dialog

Provider Registry (v0.3.34)

All provider resolution now routes through a single registry source of truth: no more hardcoded if-else ladders scattered across the codebase. The registry correctly enforces api_key requirements for API providers (Anthropic, OpenAI, GitHub Copilot, Gemini, OpenRouter, MiniMax), so resolution skips them cleanly when keys are missing instead of silently falling back. Adding a new provider is now a one-file change.

Retry & Fallback Overhaul (v0.3.36)

The provider retry and fallback system was rebuilt for reliability:

• Patient backoff: defaults changed from 100ms hammering to 1s / 2s / 4s / 8s, giving rate-limited endpoints time to recover
• In-place rate limit retry: hits 3 retries on the same provider before falling through the fallback chain, preventing unnecessary provider switches
• Full fallback chain on any HTTP error: previously only 5xx/429 triggered fallback; now any HTTP error walks the chain
• Fail fast on hard-down endpoints: DNS failures and connection refused bail immediately instead of wasting retries
• Retry events surfaced to user: each retry shows as RetryAttempt 1/3 - rate_limit_exceeded so you always know what’s happening
• Transient 4xx HTML pages retried: Cloudflare/nginx error pages that look like 4xx but are actually transient infra issues are now retried

Qwen Cache Auto-Enable (v0.3.30)

Custom providers targeting Qwen-shaped endpoints (base URLs containing dashscope, aliyun, aliyuncs, dialagram, or models prefixed with qwen-*) automatically get ephemeral cache_control markers on the system prompt, last streaming message, and last tool call. Zero-config cost savings for Qwen custom providers, no API key or flag needed.

Qwen Tool-Call Leak Strip (v0.3.35)

Qwen models sometimes emit bare JSON tool-call objects like {"name":"bash","arguments":{"command":"ls"}} directly in the content text instead of through the proper tool-call API. A new bare_tool_call_extractor detects and strips these leaks so they don’t appear as raw JSON in the chat output.

/models Picker (v0.3.30)

The /models command now surfaces every known provider including unconfigured ones, marked with a 🔒 lock icon and setup help text. This helps users discover available providers without needing to know which ones need API keys. Custom providers with no configured models show a helpful empty-state message instead of an inert button.

OpenRouter Reasoning

For models that support extended reasoning (e.g. Qwen 3.6 Plus), OpenCrabs sends include_reasoning: true automatically when using OpenRouter. Thinking/reasoning output is displayed in collapsible sections:

▶ Thinking... (click to expand)
  The user wants to refactor...

Reasoning text wraps to screen width instead of truncating.

See Provider Setup for configuration details and API key setup.

AI Provider Setup

OpenCrabs supports 15 providers (14 built-in + Custom OpenAI-Compatible). Configure them through the onboarding wizard or manually via config.toml and keys.toml at ~/.opencrabs/.

Setup via Onboarding Wizard

The fastest way to configure a provider is the interactive wizard. Run /onboard:provider (or /onboard and navigate to step 3).

Keyboard Navigation

Live-Fetch Providers (recommended)

For providers with a /v1/models API endpoint, the wizard fetches the model list live after you enter your API key.

Supported: Anthropic, OpenAI, OpenRouter, Gemini, MiniMax, Qwen (DashScope), Ollama, z.ai GLM

Flow:

1. Use ↑/↓ to select your provider (e.g. OpenRouter)
2. Press Enter: advances to the API key field
3. Paste your API key (e.g. sk-or-...)
4. Press Enter: triggers a live fetch from the provider’s /v1/models endpoint
5. Use ↑/↓ to browse models, or type to filter (case-insensitive substring match)
6. Press Enter on your chosen model: saves config and advances

Tip: If you’ve already configured a key, the wizard detects it (shown as ••••••••) and skips straight to the model picker. Press Enter to re-fetch models with the existing key.

OAuth Providers (GitHub Copilot, Codex)

No API key needed: authenticate through your browser.

Flow:

1. Select GitHub Copilot or Codex
2. Press Enter: starts the device-code PKCE flow
3. A user code and URL appear (e.g. github.com/login/device)
4. Open the URL in your browser, enter the code, and authorize
5. Tokens are saved automatically to ~/.opencrabs/auth/
6. Models are fetched live: pick one and press Enter

CLI Providers (Claude CLI, OpenCode CLI, Codex CLI)

Use your existing CLI subscription: no separate API key.

Flow:

1. Select the CLI provider (e.g. Claude CLI)
2. Press Enter: skips the API key field (none needed)
3. Models are fetched from the local binary (claude models, opencode models, etc.)
4. Pick a model and press Enter

Requirements: The CLI binary must be installed and authenticated in your PATH.

z.ai GLM (Zhipu AI)

z.ai has two endpoint types. The wizard asks which one before the API key.

Flow:

1. Select z.ai GLM
2. Press Enter: advances to Endpoint Type selector
3. Use ↑/↓ to choose API (general) or Coding (CodeGeeX)
4. Press Enter: advances to API key field
5. Paste your key, press Enter, fetches models
6. Pick a model and press Enter

Custom OpenAI-Compatible

For Ollama, LM Studio, LocalAI, Groq, NVIDIA, vLLM, or any OpenAI-compatible endpoint.

Flow:

1. Select Custom OpenAI-Compatible (last in the list)
2. Press Enter: advances to Name field
3. Name: type a provider identifier (e.g. ollama, lm-studio, nvidia). Press Enter, normalized to a TOML-safe key
4. Base URL: paste your endpoint (e.g. http://localhost:1234/v1). Press Enter
5. API Key: paste if required, or leave empty for local endpoints. Press Enter
6. Model: you have two options:
   • Type or paste a model name: use this for newly-launched models not yet available on the live API (e.g. qwen3.6-35b-a3b-gguf)
   • Press Enter on empty field: triggers a live fetch from {base_url}/models, then pick from the list
7. Context Window: enter the token limit (e.g. 128000). Press Enter, saves and advances

Context Window Recommendation: Set to 200000 (200k tokens) for best results. OpenCrabs handles large contexts gracefully with smart auto-compaction that keeps you always up to date without manual intervention.

Local LLMs: No API key needed, just set base URL and model name. If the model is already running, paste the name directly. If you want to browse available models, leave the Model field empty and press Enter to fetch the list from your local server.

Re-running Provider Setup

Manual Configuration (advanced)

If you prefer editing files directly, configure providers in config.toml and keys.toml.

Key Handling (v0.3.81)

keys.toml no longer drops provider API keys at runtime (#1066): four providers could silently lose their keys during config reloads. The stored-key marker has one owner, and keys already poisoned by the old marker are self-healed on load. If a provider worked yesterday and 401s today, re-check keys.toml: the fix also repairs the file in place.

Anthropic Claude

Models: claude-opus-4-6, claude-sonnet-4-5, claude-haiku-4-5, and legacy models, fetched live from the API.

# keys.toml
[providers.anthropic]
api_key = "sk-ant-..."

# config.toml
[providers.anthropic]
enabled = true
default_model = "claude-sonnet-4-20250514"

Features: Streaming, tool use, extended thinking, vision, 200K context window.

OpenAI

Models: GPT-5 Turbo, GPT-5, and others, fetched live.

# keys.toml
[providers.openai]
api_key = "sk-YOUR_KEY"

OpenRouter: 400+ Models

Access 400+ models from every major provider through a single API key. Includes free models (DeepSeek-R1, Llama 3.3, Gemma 2, Mistral 7B).

# keys.toml
[providers.openrouter]
api_key = "sk-or-YOUR_KEY"

Get a key at openrouter.ai/keys. Model list is fetched live, no binary update needed when new models are added.

Google Gemini

Models: gemini-2.5-flash, gemini-2.0-flash, gemini-1.5-pro, fetched live.

# keys.toml
[providers.gemini]
api_key = "AIza..."

# config.toml
[providers.gemini]
enabled = true
default_model = "gemini-2.5-flash"

Features: Streaming, tool use, vision, 1M+ token context window.

Gemini also powers the separate image generation and vision tools. See Image Generation & Vision.

GitHub Copilot

Use your existing GitHub Copilot subscription: no separate API charges. Authenticates via OAuth device flow.

# config.toml
[providers.github_copilot]
enabled = true

Setup: Run /onboard:providers → select GitHub Copilot → follow the device code flow at github.com/login/device. Models are fetched live from the Copilot API.

Requirements: An active GitHub Copilot subscription (Individual, Business, or Enterprise).

z.ai (Zhipu AI)

Models: GLM-4-Plus, GLM-4-Flash, GLM-4-0520, CodeGeeX, fetched live. Two endpoint types: General API and Coding API.

# keys.toml
[providers.zai]
api_key = "your-api-key"

# config.toml
[providers.zai]
enabled = true
default_model = "glm-4-plus"

Get your API key at open.bigmodel.cn.

Qwen (DashScope)

Qwen models via DashScope. As of v0.3.81:

• Reasoning carries across turns (#1033): preserve_thinking is sent so multi-turn conversations keep their reasoning context
• Thinking knobs are family-gated (#1034): each model family gets only the knob it actually reads (enable_thinking, effort tiers), instead of a shared guess
• Tiered families default to the recommended effort tier (#1034)
• Hosted Qwen reachable everywhere (#1040): works outside Alibaba networks and with vendor-prefixed model ids

Claude CLI

Use your existing Claude Code subscription through the local claude binary, no separate API key needed. Supports streaming and extended thinking.

# config.toml
[providers.claude_cli]
enabled = true

Requirements: The claude CLI must be installed and authenticated. Models are detected automatically.

Ollama

Run any Ollama model natively: no custom provider setup needed. Supports both local (localhost:11434) and cloud (api.ollama.com) instances.

# config.toml
[providers.ollama]
enabled = true
default_model = "llama3"

# keys.toml (optional, only for cloud Ollama)
[providers.ollama]
api_key = "your-api-key"

Features: Streaming, tool use, local model tool-call extraction from text. Models are fetched live from the Ollama API.

Requirements: Ollama must be running locally (ollama serve) or you must have a cloud Ollama API key.

OpenCode CLI

Use the local opencode binary for free LLM completions, no API key or subscription needed. Supports NDJSON streaming and extended thinking.

# config.toml
[providers.opencode_cli]
enabled = true

Requirements: The opencode binary must be installed and available in your PATH. Models are fetched live via opencode models.

Codex CLI

Use OpenAI’s @openai/codex CLI as a native provider. User authenticates once via codex CLI; OpenCrabs piggybacks on cached credentials, zero API key handling. Non-interactive mode via codex exec --json with JSONL streaming.

# config.toml
[providers.codex_cli]
enabled = true

Models: GPT-5.5, GPT-5.4, GPT-5.3-Codex

Requirements: The codex CLI must be installed (npm install -g @openai/codex) and authenticated. Models are detected automatically.

Codex OAuth

Native OpenAI Codex subscription auth via device-code PKCE flow. No CLI dependency, no API key. User authenticates through browser once; tokens stored in ~/.opencrabs/auth/codex.json with automatic refresh and background rotation.

# config.toml
[providers.codex]
enabled = true

Models: GPT-5.5, GPT-5.4, GPT-5.3-Codex (curated GPT-5 model list)

Setup: Run /onboard:provider → select Codex OAuth → follow the device code flow at auth.openai.com/codex/device. Two-step PKCE exchange: device auth poll → authorization code → token exchange.

Requirements: An active OpenAI Codex subscription. No CLI installation needed.

MiniMax

Models: MiniMax-M2.7, MiniMax-M2.5, MiniMax-M2.1, MiniMax-Text-01

# keys.toml
[providers.minimax]
api_key = "your-api-key"

Get your API key from platform.minimax.io. Model list comes from config.toml (no /models endpoint).

Custom (OpenAI-Compatible)

Use for Ollama, LM Studio, LocalAI, Groq, or any OpenAI-compatible API.

# config.toml
[providers.custom.lm_studio]
enabled = true
base_url = "http://localhost:1234/v1"
default_model = "qwen2.5-coder-7b-instruct"
models = ["qwen2.5-coder-7b-instruct", "llama-3-8B"]

Local LLMs: No API key needed, just set base_url and default_model.

Remote APIs (Groq, etc.): Add the key in keys.toml:

[providers.custom.groq]
api_key = "your-api-key"

Multiple Custom Providers

Define as many as you need with different names:

[providers.custom.lm_studio]
enabled = true
base_url = "http://localhost:1234/v1"
default_model = "qwen2.5-coder-7b-instruct"

[providers.custom.ollama]
enabled = false
base_url = "http://localhost:11434/v1"
default_model = "mistral"

Naming Custom Providers

The provider’s name is the last segment of its config section, nothing else.

[providers.custom.moonshotai]   # the name is "moonshotai"

When you reference the provider anywhere (self_improvement_provider, subagent_provider, plan_provider, execute_provider, or the /models command) use that bare name:

[agent]
self_improvement_provider = "moonshotai"        # ✅ bare section name
self_improvement_model = "kimi-k2.5"            # the model has its own key

Never carry the custom path into the reference, and never append the model:

self_improvement_provider = "custom:moonshotai"    # ❌ RSI silently never runs
self_improvement_provider = "custom.moonshotai"    # ❌ same
self_improvement_provider = "moonshotai/kimi-k2.5" # ❌ provider-only, model goes in self_improvement_model

Real case: a user with [providers.custom.glm-53-max] set self_improvement_provider = "custom:glm-53-max" and RSI silently never ran, Mission Control showed thousands of tool events recorded and unprocessed. Dropping the custom: prefix fixed it instantly (opencrabs#1314). Current main auto-corrects misspelled values with a warning; released versions fail silently, so spell it bare.

Free Prototyping with NVIDIA API

Kimi K2.5 is available for free on the NVIDIA API Catalog, no billing required.

# config.toml
[providers.custom.nvidia]
enabled = true
base_url = "https://integrate.api.nvidia.com/v1"
default_model = "moonshotai/kimi-k2.5"

# keys.toml
[providers.custom.nvidia]
api_key = "nvapi-..."

Fallback Provider Chain

Configure automatic failover when the primary provider fails (rate limits, outages, errors). Fallbacks are tried in order until one succeeds.

# config.toml
[providers.fallback]
enabled = true
providers = ["openrouter", "anthropic"]  # Tried in order on failure

Each fallback provider must have its API key configured in keys.toml. Both complete() and stream() calls are retried transparently, no changes needed downstream.

Single fallback shorthand:

[providers.fallback]
enabled = true
provider = "openrouter"

Or just ask your Crab: “Set up fallback providers using openrouter and anthropic”, it will configure config.toml for you at runtime.

Quota Circuit Breaker (v0.3.79)

Fallback chains now know the difference between a provider that is momentarily busy and one that is genuinely out of quota.

• Hard quota exhaustion (your account has run out of credits/allowance for the period) trips a TTL circuit breaker on that provider. While the breaker is open the provider is skipped in fallback walks instead of being retried pointlessly, so failover lands on a provider that can actually serve the request.
• Transient throttles (short rate limits, 429s that clear in seconds) are classified separately and retried as before, they never trip the breaker.
• When every provider in the chain is exhausted, the failure is reported explicitly as chain exhaustion rather than surfacing as a confusing error from the last provider tried.
• Retry notices now name the provider and model being retried, and state whether the cause was a quota exhaustion or a transient throttle.

No configuration needed: it is always on whenever a fallback chain is configured.

Fallback Improvements (v0.3.80)

• Proactive setup suggestion (#1008): when no fallback chain is configured, OpenCrabs makes a one-shot suggestion to set one up, ask once, answered once, never nags again.
• HTTP 400 failover guidance (#1006, #1007): a 400-series failure now carries guidance on what to check, and a chain-exhaustion ledger records why each provider in the chain was ruled out.
• Fallback provenance in streaming logs (#969): each streamed call logs which provider actually served it, so retries and failovers are visible per call.
• Codex CLI failures route into retry and fallback (#1004, #1005) instead of surfacing as terminal errors.

Provider Configuration Fields

Every provider section ([providers.<name>]) supports these fields:

Example: full provider config:

# config.toml
[providers.minimax]
enabled = true
default_model = "MiniMax-M2.7"
vision_model = "MiniMax-Text-01"
generation_model = "MiniMax-Image-01"
context_window = 200000
force_default = true

Force Default Provider

When you set force_default = true on a provider section, a config reload pushes that provider’s default pair (provider + model) to every non-archived session, overriding their stored pairs. This enforces your chosen default across all active sessions instead of just new ones.

# config.toml
[providers.minimax]
enabled = true
default_model = "MiniMax-M2.7"
force_default = true  # Pushes MiniMax M2.7 to all sessions on reload

How it works:

• Only fires when the flagged section is the active default provider (set via /models or default_provider in [agent])
• Archived sessions are never touched
• Sessions already on the target pair are skipped
• Without this flag: defaults apply to new sessions only, existing sessions keep their own provider/model

Use case: You want to roll out a new default model (e.g. MiniMax M2.7) across all active sessions immediately, not just new ones. Set force_default = true on the MiniMax section, reload config, and every session switches to M2.7.

Note: This only reinforces the default, it doesn’t override a different active provider. If a session is using Anthropic Claude and you set force_default = true on MiniMax, the Claude session stays on Claude (because MiniMax isn’t the active default).

Vision Model

When your default chat model doesn’t support vision, set vision_model to a vision-capable model on the same provider. This registers a vision tool that the agent can call, it sends the image to the vision model, gets a description back, and the chat model uses that context to reply.

# config.toml
[providers.minimax]
enabled = true
default_model = "MiniMax-M2.5"
vision_model = "MiniMax-Text-01"  # Agent calls vision tool → this model describes image → M2.5 replies

[providers.openai]
enabled = true
default_model = "gpt-5-nano"
vision_model = "gpt-5-nano"

MiniMax auto-configures vision_model = "MiniMax-Text-01" on first run. You can also ask your Crab to set it up: “Configure vision model for MiniMax”, it will update config.toml at runtime.

This is separate from the Gemini image tools which provide dedicated generate_image and analyze_image tools.

Per-Session Providers

Each session remembers its provider and model. Switch to Claude in one session, Gemini in another, switching sessions restores the provider automatically.

Model Picker (v0.3.75)

The /models picker got a real overhaul:

• Opus 5 surfaced: Opus 5 now shows up via a third parallel list plus state discovery.
• Newest-first ordering: models are ordered newest-first instead of by merge order.
• claude-cli model discovery: the claude-cli model list is discovered live from the CLI instead of being hardcoded, with every claude-cli row formatted consistently.
• Reconciled against live inventory: the picker reconciles against the live model inventory so it never offers a model that isn’t actually available.

Natural Model Naming (v0.3.76)

The /models command now accepts colloquial model names. Instead of typing the exact model ID, you can say it the way people talk:

/models opus        → claude-opus-4-8
/models sonnet      → claude-sonnet-4-20250514
/models gpt5        → gpt-5
/models qwen max    → qwen3.8-max-preview

The resolver normalizes spacing, case, and common abbreviations before matching against the provider’s model list. Exact matches still take priority.

Plan/Execute Provider Routing (v0.3.76)

The /plan and /execute commands can now route onto their own dedicated provider and model, separate from the main chat provider:

# config.toml
[agent]
plan_provider = "anthropic"
plan_model = "claude-opus-4-8"
execute_provider = "openrouter"
execute_model = "anthropic/claude-sonnet-4"

This lets you use a stronger model for planning (where reasoning quality matters most) and a faster/cheaper model for execution (where throughput matters). If unset, both fall back to the session’s active provider.

Image Generation & Vision

OpenCrabs supports image generation (text-to-image and img2img) and vision analysis (image-to-text). Vision works through two paths, pick whichever fits your provider setup.

Vision: Two Paths

Path A: vision_model on Your Active Provider (Preferred)

Set vision_model = "<model>" inside the provider block you’re already using. Works for every built-in and custom provider. No second API key needed, the agent calls analyze_image against the vision model on the same provider endpoint.

# keys.toml
[providers.openrouter]
api_key = "sk-or-..."

# config.toml
[providers.openrouter]
model = "anthropic/claude-sonnet-4"
vision_model = "google/gemini-2.5-flash"   # ← any vision-capable model on the same endpoint

When a user sends an image and the chat model can’t handle it natively, the agent routes the image through vision_model, gets a text description back, and replies with that context.

Example: User sends an image while you’re on MiniMax M2.5 (no native vision). The agent calls the vision tool, which sends the image to MiniMax-Text-01 (or any model you set), gets the description, and M2.5 replies using that context.

Why this is preferred:

• Single API key, single billing account
• Works on any OpenAI-compatible endpoint (OpenRouter, Ollama, LM Studio, vLLM, Groq, custom)
• No extra onboarding step: just add one line to your existing provider block

Path B: Gemini Global Fallback

Use this only when your active provider has no vision-capable model. Gemini acts as a dedicated vision+image backend, independent of your chat provider.

# keys.toml
[image]
api_key = "AIza..."    # ← MUST go here. See gotcha below.

# config.toml
[image.generation]
enabled = true
model = "gemini-3.1-flash-image-preview"

[image.vision]
enabled = true
model = "gemini-3.1-flash-image-preview"

Get a free API key from aistudio.google.com. Configure interactively with /onboard:image.

⚠️ Gotcha: #[serde(skip)] on [image.vision] api_key

The api_key field under [image.vision] in config.toml is silently ignored: it’s marked #[serde(skip)] in the source. Always put the Gemini key in keys.toml under [image], never in config.toml. If vision reports as unavailable despite a key being set, this is almost always the cause.

Diagnostic: Why Is Vision Unavailable?

is_vision_available logs the exact reason at INFO level with target=vision. Search your daily log:

grep 'target=vision' ~/.opencrabs/logs/opencrabs.$(date -u +%Y-%m-%d)

Common causes surfaced:

• Missing vision_model on active provider (the only field actually required since v0.3.64)
• Missing api_key for that provider
• Missing Gemini [image] api_key in keys.toml
• Key placed in config.toml where #[serde(skip)] drops it

v0.3.64 change: setting vision_model on your active provider is now sufficient to enable vision. The enabled flag under [image.vision] is no longer required. The vision roll-through tries each provider endpoint and falls back to Gemini last.

Agent Tools

When vision or image generation is enabled, these tools become available:

Example prompts:

• “Generate a pixel art crab logo”: agent calls generate_image, returns file path
• “What’s in this image: /tmp/screenshot.png”, agent calls analyze_image

img2img: Edit Images with Context

generate_image accepts an optional image parameter (local file path or HTTPS URL). When provided, the model modifies, restyles, or composites onto that image instead of generating from scratch.

User: "Make this logo darker and add a border"
Agent: generate_image(prompt="dark background with thin white border", image="/tmp/logo.png")

• Gemini backend: full img2img support via inlineData
• OpenAI-shaped backends: reject with a clear error pointing at Gemini (img2img not supported)

Use cases: replace elements, restyle photos, composite logos onto backgrounds, modify user-uploaded images in-place.

Incoming Images from Channels

When a user sends an image from any channel, it arrives as <<IMG:/tmp/path>> in the message. The file is already downloaded, the agent can:

• See it directly (if the chat model supports vision natively)
• Pass the path to analyze_image for vision processing
• Use the path in bash commands or any tool that accepts file paths
• Reference it in replies with <<IMG:path>> to forward to channels

analyze_video: Frame-Extraction Fallback (v0.3.36)

The analyze_video tool sends the full video to Gemini’s video API for multimodal analysis. When that fails (network error, upload timeout, unsupported format), the agent falls back to ffmpeg frame extraction:

1. Extract frames at 1 fps via ffmpeg
2. Cap at 30 frames (one frame per second for the first 30 seconds)
3. Send each frame to Gemini vision via analyze_image
4. Combine per-frame descriptions into a chronological summary

This means analyze_video works even when the video API is unreachable, as long as ffmpeg is installed and at least one vision path (Path A or Path B) is configured. The fallback activates automatically. No user configuration needed.

Model Choices

• Path A: any vision-capable model on your active provider. On OpenRouter: google/gemini-2.5-flash, anthropic/claude-sonnet-4, openai/gpt-4o. On Ollama: llava, bakllava. On custom endpoints: whatever the server offers.
• Path B: gemini-3.1-flash-image-preview handles both vision input and image output in a single request.

Channel Integrations

OpenCrabs connects to multiple messaging platforms simultaneously. All channels share the TUI session by default, with per-user sessions for non-owners.

Setting Up Channels

Channels are configured through the onboarding wizard, not by editing TOML files manually.

Running the Wizard

• First launch: the wizard runs automatically
• Re-run: type /onboard in chat, or /onboard:channels to jump straight to the channels step
• Quick jump: /onboard:channels opens the channel picker and returns to chat when done

Navigation

The channel picker is a keyboard-driven TUI screen:

Channel Setup Screens

When you press Enter on an enabled channel, a dedicated setup screen opens with the fields needed for that platform (bot token, channel ID, allowed users, etc.). Each field:

• Auto-detects existing values from config.toml / keys.toml (shown as masked •••••••• for secrets, plain text for IDs)
• Tab moves to the next field
• Enter on the last field (or the Test Connection button) saves and returns to the channel list
• BackTab moves to the previous field

The Five Channels

After enabling and configuring your channels, the wizard saves everything to config.toml and keys.toml automatically. You can always re-run /onboard:channels to modify settings.

Supported Channels

Cross-Channel Session Resolution (v0.3.29)

All messaging channels now share a stable [chat:<id>] suffix pattern for reliable session lookup. Previously only Telegram had this; Discord, Slack, and WhatsApp used exact-title matching which broke when the agent auto-renamed sessions (creating duplicates on every message).

The shared channels::session_resolve module provides:

• Suffix-first lookup: fast path using [chat:discord-dm-<user_id>], [chat:slack-<channel_id>], [chat:wa-<phone>] etc.
• Legacy forward-migration: pre-suffix rows are migrated to the suffix format on first lookup
• /sessions binding: explicit chat→session binding on switch so user choices win over suffix lookup

Follow-Up Cancel (v0.3.30)

Sending a message while the agent is mid-run now acts as ESC x2 (cancel current run) across all channels. The cancelled partial content is preserved, and the new message starts a fresh agent turn.

ZIP Attachments (v0.3.30)

ZIP file attachments from users are extracted and processed inline:

• Text files are inlined into the conversation
• Images get vision markers for multimodal processing
• PDFs get text extraction
• Capped at 50 files / 10 MB per ZIP entry

Group Onboarding & /cowork (v0.3.74)

Getting a bot into a group and making it useful is now a single flow:

• /cowork opens the group: /cowork sets the target group open = true and persists it (#718).
• /cowork admin deep link: the /cowork deep link requests admin rights, so the bot joins already promoted (#709).
• Group onboarding greeting: the bot greets the group with an onboarding nudge when it joins (#707, #708).
• Per-group /start registration: /start in a group registers the member per-group instead of the stale config.toml lecture (#708).
• Register joining members: any member who joins a bot group is auto-registered (#710).
• Secure by default: member auto-registration is gated to open = true groups (#717).

Follow-Up Suggestions (v0.3.74)

• follow_up_question degrades gracefully: returns the question as plain text on non-interactive surfaces (#716).
• Telegram follow-up taps: suggest_followups renders last, fixing taps doing nothing (#723, #724).
• Accurate description: the suggest_followups tool description is channel-accurate, so the model invokes it instead of writing plain-text suggestions (#706).
• Outbound media dedup: an identical file+caption re-uploaded to the same chat within a short window is collapsed, so the agent can’t send it twice (#721).

Common Features

All messaging channels support:

• Shared session with TUI (owner) or per-user sessions (non-owners)
• Slash commands: /help, /models, /new, /sessions, custom commands
• Inline buttons: Provider picker, model picker, session switcher (Telegram, Discord, Slack)
• User allowlists: Restrict access by user ID, chat ID, role, or phone number. Since v0.5.1 the allowlists are deny-by-default and are the access boundary: on Discord and Slack an unconfigured channel (no allowed_users, no allowed_roles, no bot_owner) refuses every message, matching Telegram; on WhatsApp an empty allowed_phones no longer grants anyone owner rights. Because the default approval_policy is auto-always, the allowlist is what decides who can drive tools at all, set it deliberately
• respond_to filter: all, dm_only, or mention (respond only when @mentioned)

File & Media Support

Images are passed to the active model’s vision pipeline if it supports multimodal input, or routed to the analyze_image tool (Google Gemini vision) otherwise. Text files are extracted as UTF-8 and included inline up to 8,000 characters.

Proactive Channel Tools

The agent can send messages and take actions proactively:

Channel Voice Parity

All four messaging channels (Telegram, Discord, WhatsApp, Slack) now share a single code path via crate::channels::voice::{transcribe, synthesize}. Bot replies are recorded in the channel_messages table for conversation context, previously only user messages were stored.

Typing Indicator Persistence (v0.3.76)

Typing indicators now survive background tasks. Previously, when the agent spawned a background task (long build, test suite), the typing indicator would drop because the foreground turn ended. Now the indicator stays alive until the final response is delivered, regardless of how many background tasks run in between.

Smart Chunk Boundaries (v0.3.78)

When a response exceeds platform message limits and must be split into chunks, the splitter now prefers boundaries that leave no markup open. Previously, a chunk could end mid-bold (**text) or mid-code-fence, causing rendering glitches on the receiving platform. The splitter now scans for the nearest safe break point where all markdown delimiters are balanced.

Owner-Gated Channel Commands (v0.3.80)

User-defined slash commands and skills are owner-gated on the channel catch-all arm (#975). In a group chat, only the bot owner can trigger custom commands and skills; other members’ messages fall through to normal conversation. This closes a gap where any group member could run owner-defined automation through the catch-all routing path.

Telegram

Connect OpenCrabs to Telegram for DMs and group chats.

Setup

Step 1: Create a Bot with BotFather

1. Message @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Copy the bot token (format: 123456:ABC-DEF...)

Step 2: Configure via the Onboarding Wizard

Run /onboard:channels (or /onboard and navigate to the Channels step):

1. Use ↑/↓ to focus Telegram
2. Press Space to toggle it on
3. Press Enter to open the Telegram setup screen
4. Fill in the fields:
   • Bot Token: paste the token from BotFather
   • Owner User ID: your numeric Telegram chat ID
   • Respond To: all, dm_only, or mention (when to respond in groups)
5. Press Enter on Test Connection to verify the bot works
6. Press Enter to save and return to the channel list

Get your chat ID by messaging @userinfobot on Telegram.

Manual Configuration (advanced)

If you prefer editing files directly, the wizard writes to ~/.opencrabs/keys.toml and ~/.opencrabs/config.toml:

# keys.toml
[channels.telegram]
bot_token = "123456:ABC..."

# config.toml
[channels.telegram]
enabled = true
allowed_users = ["123456789"]
respond_to = "all"

Features

• DMs and groups: Works in private chats and group conversations
• Forum topic routing (v0.3.31): In supergroups with topics enabled, the bot tracks thread_id through the full pipeline. Use list_topics action to map topic names (e.g. #announcements) to numeric IDs, then pass thread_id to send / reply / send_photo to route into a specific topic
• Context-aware pre-tool status (v0.3.31): While a tool runs, the bot shows a live status message naming the tool, elapsed time, and either a reasoning excerpt or an anchored phrase from the user’s request
• Inline ctx budget footer (v0.3.36): context budget footer (ctx: XK/YK Z% | N tok/s) is now appended to the last response message instead of sent as a separate message. Keeps the chat clean.

v0.3.76–v0.3.78 Improvements

/new Gating (v0.3.76)

The /new command is now gated to the bot owner in group chats. Non-owners cannot create new sessions or reset context. The command menu is also scoped: owners see the full menu, non-owners see only the commands available to them.

HTML Conversion (v0.3.77)

All telegram_send actions now apply HTML-to-Telegram conversion consistently. Previously, only the main response path converted HTML entities; proactive sends, follow-ups, and media captions could arrive with raw <b> tags or unescaped ampersands.

Rich Delivery (v0.3.78)

Telegram delivery is unified on markdown formatting. The legacy “blocks path” (which sent structured JSON blocks) has been removed in favor of a single rich-markdown renderer. This eliminates formatting inconsistencies between streaming responses and proactive sends.

Callback Routing (v0.3.78)

Inline keyboard callbacks (plan approvals, follow-up taps, dedup approvals) now route to the originating session instead of the chat-bound session. Previously, tapping a button in a group chat could route the callback to the wrong session if multiple sessions shared the same chat.

Background Streaming (v0.3.78)

Background task results now stream through one turn per session instead of spawning a new message per tick. This eliminates the message flood when a background task (build, test suite) produces incremental output.

Follow-Up Attribution (v0.3.78)

When a user taps a follow-up suggestion button in a group chat, the agent now names the member who tapped it. Previously, follow-up taps were anonymous in group contexts.

Other Fixes

• /start recognizes existing members of closed groups (v0.3.76)
• Plan-card serialisation prevents duplicate cards on concurrent refreshes (v0.3.76)
• Follow-up taps run a real tools turn instead of echoing text (v0.3.76)
• Flow block no longer posts a new message every tick (v0.3.77)
• Echoed plan titles dropped from responses (v0.3.77)
• Open-group registration gated on persisted open flag (v0.3.78)
• Cowork members recorded on first message (v0.3.78)
• Rolling status edit-in-place (v0.3.36): tool status messages (⚙️ running, ✅ done) are edited in-place instead of delete+recreate, preventing flicker and preserving scroll position.
• Bot command hot-reload (v0.3.36): bot commands refresh automatically when config or skills change, without restarting the bot.
• Guard tok/s against burst-delivery (v0.3.36): tok/s footer is guarded against burst-delivery artifacts so the number stays stable.
• follow_up_question polish (v0.3.34): Telegram keyboard is now single-column with a 40-character label cap (longer options rejected with a clear error). The rolling “Running follow_up_question (16s)” status is suppressed while the keyboard is pending so buttons don’t get visually buried. The LLM is instructed to call the tool silently without echoing the question text in surrounding prose
• Inline buttons: Provider picker, model picker, session switcher use Telegram inline keyboards
• Image support: Send images to the bot, receive generated images
• Voice messages: STT transcription + TTS response
• All slash commands: /help, /models, /new, /sessions, custom commands
• Owner vs non-owner: Owner uses the shared TUI session, non-owners get per-user sessions
• Onboarding overhaul (v0.3.30): Auto-detects owner user ID from getUpdates, persists partial config on cancel, only Enter on the last step commits (Tab no longer silently rewrites ~30 config keys)
• Teloxide upgrade + join detection (v0.3.35): Upgraded from teloxide 0.13 to 0.17. New members joining a group are now detected before the allowlist check, so the bot can greet or moderate join events. Marathon-bucket rolling status rotates through project-author quip pool for more varied status messages.

v0.3.81 Improvements

Mermaid Diagrams as Images (#1044)

Mermaid code fences in rich messages render as images via the markdown+media route, while tables stay native Telegram formatting instead of being rasterized into the image.

Delivery and Rate-Limit Hardening

• Rich blocks decode as a typed AST (#1058) instead of ad-hoc string surgery, so structured messages can’t arrive mangled
• Inline rate-limit waits capped at 30s (#1064): a Telegram 429 never parks a turn indefinitely
• Flow footer + section cap (#1052, #1053, #1054, #1056): flow logs get a footer and bounded sections instead of unbounded message growth

Group Safety

• Only the owner may add the bot to a group (#1042)
• Bot-add detection (#1041): being added by a member is told apart from another bot arriving
• Unauthorised chats are never recorded (#1043): chats that were never approved leave no session residue

v0.3.82 Improvements

Long Rate-Limit Windows Bail Immediately (#1110)

A Telegram 429 that asks for a long wait no longer sleeps inline. The send returns immediately and the work is rescheduled, instead of the turn parking on a multi-minute (or multi-hour) window. This closes the failure mode where one throttled send held a turn open long enough to look like a hang.

Delivery Correctness

• Rich sends stop building a double-slash URL (#1117): a trailing slash on the API base no longer produces //bot<token>
• Rich API calls honour set_api_url (#1088): the rich path used a hardcoded api.telegram.org, so it bypassed a redirected Bot. It now routes through the caller’s API URL like every other method, which also makes the path testable without a real network call
• All six send arms route through thread resolution: forum-topic targeting is applied consistently instead of on some arms only

Observability

• Send-correlation telemetry (#1085): the three send chokepoints, every telegram_send arm, and the final streaming edit-in-place are all logged, so a message that never arrived can be traced to the arm that dropped it

Configuration

All Telegram options live under [channels.telegram] in ~/.opencrabs/config.toml:

[channels.telegram]
enabled = true
token = "123456:ABC-DEF..."          # or store in keys.toml
allowed_users = ["123456789"]         # numeric Telegram user IDs
allowed_channels = ["-100123456"]     # restrict to specific group/channel IDs (empty = all)
respond_to = "mention"                # "all", "dm_only", "mention" (default)
session_idle_hours = 24.0             # idle timeout for non-owner sessions
rich_messages = false                 # native Telegram rich messages (Bot API 10.1)
silence_group_start = true            # silently ignore /start from non-allowed users in groups
bot_owner = ["123456789"]             # owner IDs (gated commands, /cd hidden dirs, /profiles)

Per-group access control (per-chat ACL)

Telegram groups can have their own member list, so a user can be allowed in one group without gaining DM access:

• allowed_users (channel level): admins: may DM the bot and act in any chat.
• bot_owner: the owner: always allowed everywhere.
• [channels.telegram.groups.<chat_id>].allowed_users: allowed in that group only. These users are refused in DMs unless they are also an admin or the owner, which closes the “DM the bot privately to escape group oversight” bypass.

DMs are gated to admins + owner. If neither allowed_users nor bot_owner is set, the bot is unconfigured and stays open (no hard lockout); set either one to lock it down.

Each group can also override respond_to just for itself.

[channels.telegram]
allowed_users = ["111"]                  # admins: DM + any chat
respond_to = "mention"                   # global default

[channels.telegram.groups.-1001234567890]
allowed_users = ["222", "333"]           # allowed in this group only, never via DM
respond_to = "all"                       # per-group override of the global respond_to

respond_to accepts all, mention, dm_only, or auto (reply to all while there is at most one active sender, then switch to mention-only once a second unique sender appears).

Per-group open mode (v0.3.66)

Set open = true on a trusted group to serve all members without individual allowlisting:

[channels.telegram.groups.-1001234567890]
open = true                              # all members can talk, no per-user registration needed

Use this for public/community groups where you want the bot available to everyone. Members still can’t DM the bot unless they’re in the global allowed_users or bot_owner.

Guest queries

Telegram Guest Mode (Bot API 10.0) lets someone tag @yourbot in a chat the bot is not a member of. With guest_queries = true, OpenCrabs answers the tag right there using the API method answerGuestQuery.

[channels.telegram]
guest_queries = true                     # default false: guest tags are ignored
allowed_users = ["111"]                  # admins: answered anywhere
[channels.telegram.groups.-1001234567890]
allowed_users = ["222"]                  # this user is answered in this chat only

Default is off, and the gate is narrow once it is on. The caller must be the bot_owner, an admin (allowed_users), or listed for that chat. A group’s open = true grants nothing here: it opens that group to the bot, it does not authorize answering guest tags from its members. Refused queries are logged with the guest_query_id, the caller, and the chat.

Boundaries of a guest turn:

• The bot sees only the tagged message, no history from that chat, and nothing from the guest turn is stored in that chat’s history.
• A guest turn runs the same tool surface as a normal turn, with one exception: tools that need approval are denied, because approvals are buttons in a chat and the caller is not the machine’s owner. The tool set is capped at what a stranger should reach (#2134).
• The live status block and rich rendering match a normal turn: the guest sees the same progress chrome and the same markdown or rich reply, and an edit replaces the placeholder rather than appending a second message (#2109, #2133, #2135, #2138).
• One guest turn per session at a time, cancellable, behind a rate limit, so a tag storm cannot fan out into parallel turns (#2143).
• A reply with no tool calls is the answer alone, and the answer is never carried twice in one reply (#2113).
• Channel directives (<<...>>) are stripped, so a local file path can never leak into someone else’s chat.
• An overlong reply is cut and marked [truncated] rather than dropped.

Because the pinned teloxide-core has no guest update variant, guest queries are read on the raw getUpdates layer, and guest_message is in the bot’s allowed_updates list. Nothing to configure for that; it is on whenever the channel runs.

Voice and file pickup in groups

In mention-only groups (respond_to = "mention"), users can share files and voice messages even when the bot isn’t directly tagged in the same message:

1. Fire-and-forget file capture: The bot downloads ALL incoming voice, video, document, and audio files from group messages to ~/.opencrabs/tmp/, regardless of whether the bot was mentioned. This happens silently in the background.
2. Tag-then-ask: A user sends a voice message, then tags the bot in a follow-up message (e.g. @bot what did I just say?). The bot scans the tmp directory for recent voice files from that chat (5-minute window), transcribes the most recent one, and prepends the transcript to the user’s message.

This solves the core UX problem in mention-only groups: previously, tagging the bot in the same message as a voice note didn’t work because Telegram sends voice and text as separate messages.

The agent can use telegram_send with 20+ actions. The thread_id field on send / reply / send_photo targets a specific forum topic in supergroups with topics enabled.

Reactions (v0.3.58)

The bot understands Telegram emoji reactions in both directions:

• Inbound: when a user reacts to one of the bot’s messages with an emoji, the bot picks up that reaction (it looks up the original bot message by its platform message ID) and can act on it as feedback.
• Frame reactions (v0.3.61): inbound reactions are read by sentiment and the bot addresses the user by first name in its response.
• Mid-turn reactions (v0.3.61): if a user reacts during a running turn, the reaction injects into the current loop instead of spawning a second turn.
• Reaction-only replies: when a short acknowledgement says it all (a thumbs-up, a 👀, a 😂), the bot can respond with just a reaction instead of a full text message, keeping the chat uncluttered.
• Emoji validation: only real emoji count as reaction directives; code spans and stray characters are ignored, and react directives are stripped from intermediate status messages so they never leak into the visible reply.

Use the set_reaction action on telegram_send to add a reaction to a specific message from the agent.

/cowork: Workspace Creation (v0.3.59)

/cowork creates a team workspace directly from Telegram. Run it in your DM with the bot:

1. Send /cowork in your DM with the bot
2. The bot replies with an invite link and QR code for a new group
3. Scan the QR code or tap the link to create the group
4. Add your friends or teammates to the group
5. Members auto-register to the group’s allow list ([channels.telegram.groups.<chat_id>].allowed_users), not the global one. Both new joiners (via invite link) and existing members (on their first message) get registered. Cowork members can talk in the group but cannot DM the bot privately unless also on the global allowed_users. The owner gets a confirmation for each registration.

/cowork works from any surface. In Telegram DMs, the native flow activates directly. From the TUI, Discord, Slack, or WhatsApp, the agent calls the cowork_connect tool which mints a session, registers it with the bot, and returns the t.me deep link plus a scannable QR code PNG.

Flow Logs (v0.3.63)

Telegram’s rich API supports 32K-character processing-log blocks. When the agent runs multi-step operations (tool calls, research, code generation), it streams progress into a single flow-log message that grows as the turn progresses. For shorter messages, HTML formatting falls back to plain text.

Flow logs show:

• Tool calls with parameters and results
• Intermediate reasoning steps
• File edits and git operations
• Build/test progress
• Wall-clock duration (v0.3.66): finished/failed/timeout states carry the total turn time
• Bash comments as flow status (v0.3.66): line-start comments in a bash command surface as live flow status
• Full status preview (v0.3.66): the status preview uses the whole last human-readable line, no truncation

The flow-log message is edited in-place as each step completes, so the channel stays clean. Users see real-time progress without message spam.

Flow blocks re-stick to the chat bottom when buried (v0.3.65), so you always see the latest progress without scrolling.

Forum Topic Management and /clear (v0.5.2)

The agent can create and rename forum topics (not just route into existing ones), and a group’s session can bind to a topic so each topic keeps its own conversation context. /clear starts a fresh session in place (the current one closes and a blank one begins) without invoking the summariser, so it is instant and free (#1585).

Group Chat Behavior

In groups, the agent:

• Responds when mentioned by name or replied to
• Stays quiet when the conversation doesn’t involve it
• Tracks context from group messages passively

Discord

Connect OpenCrabs to Discord for server and DM interactions.

Setup

Step 1: Create a Discord Bot

1. Go to discord.com/developers/applications
2. Create a new application
3. Go to Bot section, create a bot
4. Enable MESSAGE CONTENT Intent (required: under Privileged Gateway Intents)
5. Copy the bot token
6. Under OAuth2 → URL Generator, select bot scope with Send Messages and Read Message History permissions
7. Use the generated URL to invite the bot to your server

Step 2: Configure via the Onboarding Wizard

Run /onboard:channels (or /onboard and navigate to the Channels step):

1. Use ↑/↓ to focus Discord
2. Press Space to toggle it on
3. Press Enter to open the Discord setup screen
4. Fill in the fields:
   • Bot Token: paste the token from the Developer Portal
   • Channel ID: the Discord channel to send the welcome message to (right-click a channel with Developer Mode on → Copy Channel ID)
   • Allowed Users: comma-separated Discord user IDs (since v0.5.1 an empty allowlist no longer allows everyone: until you set users, roles, or bot_owner, the channel denies all messages)
   • Respond To: all, dm_only, or mention
5. Press Enter on Test Connection to verify
6. Press Enter to save and return to the channel list

Enable Developer Mode in Discord: Settings → Advanced → Developer Mode

Manual Configuration (advanced)

# keys.toml
[channels.discord]
token = "your-bot-token"

# config.toml
[channels.discord]
enabled = true
allowed_channels = ["123456789"]
allowed_users = []
respond_to = "all"

Configuration

All Discord options live under [channels.discord] in ~/.opencrabs/config.toml:

[channels.discord]
enabled = true
token = "your-discord-bot-token"       # or store in keys.toml
allowed_users = ["123456789012345678"]  # Discord user IDs
allowed_channels = ["123456789012345678"]
respond_to = "mention"                  # "all", "dm_only", "mention" (default)
session_idle_hours = 24.0               # idle timeout for non-owner sessions

Features

• Server channels and DMs: Works in text channels and direct messages
• Interactive components: Select menus, modal forms, button interactions with component TTL and role access
• Media gallery: Batch generated files into one multi-attachment message
• Grouped tool calls: Consecutive tool calls collapse into one expandable block with Expand/Collapse toggle
• Reactions: Agent can add emoji reactions to messages. Emoji reactions from users trigger agent turns (parity with Slack/Telegram)
• Forum threads: Support for Discord forum channels
• Image support: Send and receive images
• Embed suppression: Agent wraps multiple links in <> to suppress embeds
• Slash commands: All built-in and custom commands work

Interactive Components (v0.3.63)

Discord buttons, select menus, and modal forms power the provider picker, model picker, and session switcher. Components support:

• Component TTL: Components expire after a configurable timeout
• Role access: Restrict component interactions to specific Discord roles
• Forum threads: Agent can create and manage forum threads

Media Gallery (v0.3.63)

When the agent generates multiple files (PDFs, spreadsheets, images), Discord batches them into one multi-attachment message instead of sending separate messages for each file.

Grouped Tool Calls (v0.3.63)

Consecutive tool calls collapse into a single expandable block in Discord. Users can toggle between expanded and collapsed views. This keeps the channel clean during multi-step operations.

Reactions (v0.3.63)

The agent can add emoji reactions to messages. When a user reacts with an emoji, it triggers an agent turn (parity with Slack and Telegram). This enables quick, lightweight interactions without typing full messages.

Formatting Notes

• Markdown tables in agent output convert to native Discord tables (v0.5.2); in your own messages, bullet lists are still the safest habit
• Wrap multiple links in <url> to suppress embeds

Live Reply Tracing, Auto-Threading, Native Tables (v0.5.2)

Long turns stream as a live reply that is traced and edited in place instead of staying silent until the end. Answers that belong together are auto-threaded, and markdown tables in agent output render as native Discord tables rather than raw pipes (#1608). A dedup guard on tool turns stops the final response from double-posting content a tool summary already showed (#1603).

Native Polls, Voice Replies, Slash Projection, Flow Groups (v0.5.5)

send_poll posts a native Discord poll with each option as its own answer button, so follow-up option sets render as the platform’s own poll UI (#1848). TTS replies are delivered as Discord voice messages instead of attachment links (#1849), and your commands.toml is projected onto native slash commands, so your custom commands appear in Discord’s command picker (#1850).

Flow groups now open at turn start with a live clock that keeps running while the agent thinks, and the activity text leads the line instead of hiding behind the tool count (#1841, #1843, #1844, #1845). Every outbound write, including the persistent plan card, rides one shared write governor that parks cleanly on 429s (#1910, #1912).

Per-channel control arrived with respond_to and open modes in the channel config, enforced in the message filter, the ACL and the command gate (#2014). Two commands set them from inside the channel itself: /respond_to picks who the crab answers there, and /cowork opens the channel or thread to its members (#2014, #2015). Cron reports on Discord arrive as one edited forum post instead of a chain of messages (#1851).

Sustained Typing Indicator (v0.3.76)

Discord now shows a sustained typing indicator while the agent processes a request. Previously, Discord had no typing indicator at all (Telegram and Slack did). The indicator stays alive through background tasks and long tool executions, so users see “OpenCrabs is typing…” for the entire processing duration, not just the first few seconds.

Slack

Connect OpenCrabs to Slack workspaces.

Setup

Step 1: Create a Slack App

1. Go to api.slack.com/apps
2. Create a new app (From Scratch)
3. Enable Socket Mode under Settings
4. Generate an App-Level Token (Settings → Basic Information → App-Level Tokens) with connections:write scope
5. Under OAuth & Permissions, add bot scopes: chat:write, channels:history, groups:history, im:history, reactions:write
6. Install the app to your workspace (Install App → Install to Workspace)
7. Copy both tokens: they live in different places in the Slack dashboard:
   • Bot Token (xoxb-...): under Install App, in the OAuth Tokens for Your Workspace section. It only appears after you install the app to the workspace.
   • App-Level Token (xapp-...): under Basic Information → App-Level Tokens. If you already generated it in step 4, Slack only lists the token name here; click the name to expand it and reveal the actual xapp-... value to copy.

Step 2: Configure via the Onboarding Wizard

Run /onboard:channels (or /onboard and navigate to the Channels step):

1. Use ↑/↓ to focus Slack
2. Press Space to toggle it on
3. Press Enter to open the Slack setup screen
4. Fill in the fields:
   • Bot Token: the xoxb-... token
   • App Token: the xapp-... token
   • Channel ID: right-click a channel → View channel details → copy the Channel ID at the bottom
   • Allowed Users: comma-separated Slack user IDs (Profile → ⋯ → Copy member ID)
   • Respond To: all, dm_only, or mention
5. Press Enter on Test Connection to verify
6. Press Enter to save

Manual Configuration (advanced)

# keys.toml
[channels.slack]
bot_token = "xoxb-..."
app_token = "xapp-..."

# config.toml
[channels.slack]
enabled = true
allowed_channels = ["C12345678"]
allowed_users = []
respond_to = "all"

Configuration

All Slack options live under [channels.slack] in ~/.opencrabs/config.toml:

[channels.slack]
enabled = true
token = "xoxb-your-bot-token"          # or store in keys.toml
app_token = "xapp-your-app-token"      # Socket Mode token
allowed_users = ["U12345678"]           # Slack user IDs
allowed_channels = ["C12345678"]
respond_to = "mention"                  # "all", "dm_only", "mention" (default)
session_idle_hours = 24.0               # idle timeout for non-owner sessions

Features

• Channels and DMs: Works in public/private channels and direct messages
• Action buttons: Provider picker, model picker, session switcher use Slack action buttons
• Thread support: Responds in threads when appropriate
• Slash commands: All built-in and custom commands work
• Reactions: Agent can add emoji reactions. Emoji reactions from users trigger agent turns (react-back)
• Grouped tool calls: Consecutive tool calls collapse into one edited-in-place message with Expand/Collapse toggle
• TTS voice replies: Voice responses sent as OGG/Opus files via files.upload with inline waveform UI

Grouped Tool Calls (v0.3.62)

Consecutive tool calls collapse into a single message in Slack. The message is edited in-place as each tool executes. Users can toggle between expanded and collapsed views with an Expand/Collapse button. This keeps channels clean during multi-step operations.

Reactions (v0.3.62)

The agent can add emoji reactions to messages. When a user reacts with an emoji, it triggers an agent turn (react-back). This enables quick, lightweight interactions without typing full messages. Parity with Telegram and Discord.

Reactions (v0.3.62)

Slack supports emoji reactions for lightweight acknowledgements:

• React-back: When you react to a bot message, the bot acknowledges it (e.g., adds a 👍 to show it saw your reaction)
• Reaction turns: Certain reactions can trigger agent actions (configurable)
• Grouped tool calls: Multiple tool calls in one turn collapse into a single collapsible message, keeping the channel clean

Native Rendering (v0.3.80)

Slack messages render in Slack’s own shape instead of raw markdown (#1016):

• Tables are converted to Slack-native layout instead of arriving as pipe characters
• Headings are rendered as Slack formatting rather than # hashes

Step-group narration is folded on the character stream rather than on paragraphs, and the final message no longer repeats the step-group narration it already sent (#1010).

Socket Mode

Slack uses Socket Mode (WebSocket) instead of HTTP webhooks, no public URL or ngrok needed. The connection is outbound from your machine.

WhatsApp

Connect OpenCrabs to WhatsApp via QR code pairing.

Setup

Configure via the Onboarding Wizard

Run /onboard:channels (or /onboard and navigate to the Channels step):

1. Use ↑/↓ to focus WhatsApp
2. Press Space to toggle it on
3. Press Enter to open the WhatsApp setup screen
4. The setup screen has two fields:
   • Connection: shows the QR code or connection status
   • Phone Allowlist: comma-separated phone numbers in E.164 format (e.g. +15551234567). Leave empty to accept all messages.
5. When not yet paired, a QR code appears in the terminal:
   • Open WhatsApp on your phone → Settings → Linked Devices → Link a Device
   • Scan the QR code
   • The status updates to “Connected” automatically
6. When already paired, press R on the Connection field to reset and re-pair
7. Press Enter to save

The pairing session persists across restarts: no need to re-scan.

Manual Configuration (advanced)

# config.toml
[channels.whatsapp]
enabled = true
allowed_phones = ["+15551234567"]

Configuration

WhatsApp options live under [channels.whatsapp] in ~/.opencrabs/config.toml:

[channels.whatsapp]
enabled = true
allowed_phones = ["+15551234567"]      # E.164 format
session_idle_hours = 24.0              # idle timeout for non-owner sessions

How it works

One account per instance. Each OpenCrabs instance supports one WhatsApp account (one companion device). You run the bot AS whatever account you scan: your own number (talk via “Message Yourself”), or any other number you own, including a WhatsApp Business account.

The bot talks to itself. If you message the bot’s own paired number, the bot replies to you. This is by design. The paired account’s self-chat is always allowed, regardless of response_policy or allowed_phones.

Allowlist behavior. Anyone messaging the paired number who is on the allowed_phones list gets a reply. The response_policy controls who else can interact beyond the allowlist.

Ownership (v0.5.1, deny-by-default). Before v0.5.1 an empty allowed_phones under response_policy = "auto" answered every contact and elevated them all to owner: one forgotten allowlist away from handing strangers /evolve and /cd. That elevation is gone: being answered no longer means being in charge. Owner status comes from the paired account’s self-chat, a configured bot_owner, or ownership resolution over allowed_phones + bot_owner: never from an empty list. Tool-approval replies (Yes/Always/No/YOLO) resolve only for the owner on all four channels.

• Personal and group chats: Works in DMs and group conversations
• Image support: Send and receive images
• Voice messages: STT transcription + TTS response
• Plain text UI: No buttons (WhatsApp limitation), uses text-based menus
• Slash commands: All built-in and custom commands work

Outbound rate limiting

WhatsApp is the channel with the heaviest ban consequences, so every outbound send goes through a budget (since v0.5.1):

[channels.whatsapp.rate_limit]
messages_per_minute = 30   # token bucket: sustained sends per minute
daily_cap = 800            # rolling 24h hard cap

Streaming answers used to post every chunk as its own message, exactly the volume pattern Meta’s heuristics hunt. Outbound replies now edit one message in place (since v0.5.1), which keeps chunked turns well inside the budget; the limiter is the safety net underneath.

Formatting Notes

• No markdown tables: use bullet lists
• No headers: use bold or CAPS for emphasis
• Links render natively

Voice Message Handling

When receiving a voice message:

1. Agent downloads and transcribes via STT
2. Sends text response first (searchable)
3. Optionally generates TTS audio response

Features

• Personal and group chats: Works in DMs and group conversations
• Image support: Send and receive images
• Voice messages: STT transcription + TTS response
• Plain text UI: No buttons (WhatsApp limitation), uses text-based menus
• Slash commands: All built-in and custom commands work

Surface (v0.5.2)

The WhatsApp channel grew to match the phone app’s surface:

• Outbound: native voice notes (opus), edit-in-place streaming for long replies, pin, forward, and profile actions
• Inbound: video, stickers, location, contacts, reactions, and poll votes are parsed into the turn; presence events and media recovery fill gaps after reconnects
• Sessions: disappearing messages honored per chat, contact blocking, per-chat history with reaction acknowledgements
• Surfaces: status updates and newsletter discovery, native-flow buttons for interactive prompts; follow-up suggestion sets that exceed the native button cap render as a poll, and a vote selects the option (#1616)

Troubleshooting

Wrong number replying

Each OpenCrabs instance supports one WhatsApp account (one companion device). If you connected multiple numbers or the wrong number is replying, you need a full reset. The bot always uses the last number you connected.

Critical: Always reset the connection before connecting a new number. OpenCrabs only keeps the last paired number.

Full reset steps:

1. Remove ALL linked devices from WhatsApp. Open WhatsApp on your phone, go to Settings > Linked Devices, and remove every device in the list. Don’t bother hunting for the opencrabs one. A stale device left over from an earlier pairing is the usual reason the old number keeps replying, so the reliable fix is to clear them all and start fresh.
2. Reset the connection in OpenCrabs: in the TUI or from a channel, go to /onboard:channels and press R to reset the WhatsApp connection. Wait for confirmation that the reset is complete.
3. Re-pair from scratch: after the reset is confirmed, go to WhatsApp > Settings > Linked Devices > Link a Device and scan the new QR code shown by OpenCrabs.

If the bot still shows the old number after resetting, make sure you completed step 1 (removing the device from WhatsApp) before step 2.

Common issues

Trello

OpenCrabs integrates with Trello for board and card management via the trello_send tool.

Setup

Step 1: Get Trello Credentials

1. Go to trello.com/power-ups/admin
2. Create a new Power-Up to get your API Key
3. Click the “Token” link next to your API key to generate an API Token

Step 2: Configure via the Onboarding Wizard

Run /onboard:channels (or /onboard and navigate to the Channels step):

1. Use ↑/↓ to focus Trello
2. Press Space to toggle it on
3. Press Enter to open the Trello setup screen
4. Fill in the fields:
   • API Key: from the Trello Power-Up admin page
   • API Token: generated alongside the API key
   • Board ID: board name or 24-character hex ID (names are resolved automatically)
   • Allowed Users: Trello member IDs allowed to interact with the bot (leave empty for all members)
5. Press Enter on Test Connection to verify board access
6. Press Enter to save

Manual Configuration (advanced)

# keys.toml
[channels.trello]
api_key = "your-api-key"
token = "your-token"

# config.toml
[channels.trello]
enabled = true
boards = ["Board Name or ID"]
allowed_users = []
# poll_interval_secs = 30  # Poll for new card comments

Configuration

All Trello options live under [channels.trello] in ~/.opencrabs/config.toml:

[channels.trello]
enabled = true
token = "your-trello-api-token"        # or store in keys.toml
app_token = "your-trello-api-key"      # stored as app_token for keys.toml symmetry
allowed_users = ["memberId1"]           # Trello member IDs
board_ids = ["boardId1", "boardId2"]   # boards to monitor (also accepts allowed_channels)
poll_interval_secs = 60                 # polling interval (absent or 0 = tool-only mode)
session_idle_hours = 24.0               # idle timeout for non-owner sessions

Tool Actions

The trello_send tool supports 22 actions:

Perilaku

• Tool-only by default: The agent acts on Trello only when explicitly asked
• Optional polling: Set poll_interval_secs to enable monitoring for @bot_username mentions
• Image attachments: Generated images are sent as card attachments with embedded previews
• File attachments: Card attachments (images, documents) are fetched and processed through the vision pipeline

Built-in Tools

OpenCrabs ships with 50+ tools available to the agent out of the box, plus support for user-defined dynamic tools.

File Operations

Code Execution

Web & Network

Document Parsing

Document Generation

Session & Memory

Image & Video

Channel Integrations

Sub-Agent Orchestration

Agents can spawn independent child agents for parallel task execution:

Agent Types

When spawning, agent_type selects a specialized role with a curated tool registry:

ALWAYS_EXCLUDED tools (no agent type has these): spawn_agent, resume_agent, wait_agent, send_input, close_agent, rebuild, evolve – no recursive spawning, no self-modification from subagents.

Browser Automation

Native headless Chrome control via Chrome DevTools Protocol (CDP):

Auto-detects your default Chromium browser. Feature-gated under browser (enabled by default).

Dynamic Tools

Define custom tools at runtime via ~/.opencrabs/tools.toml. See Dynamic Tools for details.

System

Error Handling

v0.2.92 improved error surfacing across all tool connections. Channel connect tools (slack_connect, whatsapp_connect, trello_connect) now surface actual connection errors instead of silently swallowing them. Tool call status correctly transitions from “running” to success/failure instead of showing a perpetual spinner.

System CLI Tools

OpenCrabs runs in a TUI with full terminal access. The agent can execute any CLI tool installed on the host via the bash tool – no plugins, no wrappers. If it’s on your system, the agent can use it. Common ones:

GitHub CLI (gh)

Authenticated GitHub CLI for full repo management:

gh issue list / view / create / close / comment
gh pr list / view / create / merge / checks
gh release list / create
gh run list / view / watch

Google CLI (gog)

OAuth-authenticated Google Workspace CLI. Supports Gmail and Calendar:

gog calendar events --max 10
gog gmail search "is:unread" --max 20
gog gmail send --to user@email.com --subject "Subject" --body "Body"

Requires GOG_KEYRING_PASSWORD and GOG_ACCOUNT env vars.

Companion Tools

SocialCrabs: Social Media Automation

SocialCrabs is a social media automation tool with human-like behavior simulation (Playwright). Supports Twitter/X, Instagram, and LinkedIn.

The agent calls SocialCrabs CLI commands via bash:

node dist/cli.js x tweet "Hello world"
node dist/cli.js x mentions -n 5
node dist/cli.js ig like <post-url>
node dist/cli.js linkedin connect <profile-url>

Read operations are safe. Write operations (tweet, like, follow, comment) require explicit user approval.

WhisperCrabs: Floating Voice-to-Text

WhisperCrabs is a floating voice-to-text widget controllable via D-Bus. Click to record, click to stop, text goes to clipboard. The agent can start/stop recording, switch providers, and view transcription history via D-Bus commands.

Custom Commands

Define your own slash commands in ~/.opencrabs/commands.toml. Commands work from the TUI and all channels (Telegram, Discord, Slack, WhatsApp).

Configuration

# ~/.opencrabs/commands.toml

[commands.credits]
description = "Show remaining API credits"
action = "prompt"
value = "Check my API credit balance across all providers and give me a summary"

[commands.deploy]
description = "Deploy to production"
action = "prompt"
value = "Run the production deployment pipeline: git pull, build, test, deploy"

[commands.status]
description = "Show system status"
action = "system"
value = "System is operational. All channels connected."

Action Types

Using Commands

Type /commandname in the TUI or any connected channel:

/credits     → agent checks API balances
/deploy      → agent runs deployment
/status      → shows static system message

Visibility

Custom commands appear in:

• /help output (TUI and channels) under a “Custom Commands” section
• TUI slash autocomplete when typing /

Commands are sorted alphabetically and show their description.

Memory System

OpenCrabs uses a 3-tier memory system for persistent context across sessions.

Memory Tiers

1. Daily Notes (memory/YYYY-MM-DD.md)

Automatic daily files for session-specific observations:

~/.opencrabs/memory/2026-03-07.md

The agent writes here during conversations: new integrations, bugs fixed, decisions made, server changes.

2. Long-term Memory (MEMORY.md)

Curated knowledge that persists across all sessions:

• Server details, SSH access, credentials locations
• User preferences and workflows
• Integration configurations
• Lessons learned from debugging

3. Semantic Search (session_search)

Full-text search across all past sessions stored in SQLite. The agent can query:

• Previous conversations
• Tool execution history
• Past decisions and context

Memory Search

The agent uses session_search for fast memory lookups (~500 tokens) instead of reading full memory files (~15K tokens). This is the primary recall mechanism.

Chunk-Hash Caching (v0.3.82)

Embedding is skipped for chunks whose content has not changed (#1107). Each chunk carries a hash; on write, only chunks whose hash differs from the stored one are re-embedded. Editing one line of a large brain file no longer re-embeds the whole document.

Scoped Search (v0.3.80)

memory_search takes a scope that picks which corpus to search (#1020):

Picking the wrong scope is the usual reason a search comes back with nothing useful. Daily logs outnumber brain files and reuse the same words for unrelated things, so searching memory for a rule usually fails: history outranks policy and you get confident irrelevant hits. Search brain before appending any rule: a hit tells you WHICH file owns it, and then load_brain_file with a query reads the whole section.

Chunked Retrieval and Index-on-Write (v0.3.80)

Memory retrieval was rebuilt around chunking (#998-1002, #1018):

• Documents are chunked before embedding, so chunks past the first are searchable. Previously a long document effectively hid everything after its opening.
• Lexical hits are narrowed to the matching chunk, so keyword results point at the relevant slice instead of the whole document.
• The index updates on write: memory is searchable immediately, not from a boot-time snapshot. Brain files are indexed into the brain collection on write too.
• The store resolves per profile, so profiles never share or cache each other’s memory index.
• The chunker is multi-byte safe: no more panics on UTF-8 boundaries.
• MEMORY.md recall is ranked with BM25 instead of shared-word counts (#996), and recall folds Latin diacritics so accented queries match.

In-tree Memory Store (v0.3.81)

The qmd binary dependency is gone (#1032). OpenCrabs now owns its memory store in-tree (src/memory/): SQLite FTS5 for lexical search plus vector embeddings in one store, resolved per profile. One fewer external binary to install or break, and the store schema ships with the binary.

External Index Paths (v0.3.81)

Memory search can read indexes that live outside the profile directory (#1051, #1055):

[memory]
# Each entry is a bare path string or a { path, pattern } table.
# Relative paths resolve against the OpenCrabs home (not the session cwd),
# so the index stays stable across /cd and profile switches.
extra_paths = [
  "~/knowledge/product-docs",
  { path = "~/knowledge/website-mirror", pattern = "docs/**/*.md" },
]

Indexed files are searchable within one sweep interval (~5 min), no restart needed. Results come back as ranked excerpts with file paths via memory_search scope="external"; the agent can then read the full file for verbatim quotes.

Gotchas: UTF-8 text only (binary files are skipped with a warning); HTML files index as raw markup, so mirror sites to .md first; nested roots and symlinks are skipped by design; test external scope from an owner session, group sessions return nothing unless you set external_allowed_in_shared = true.

Build a knowledge base from any docs site

web_scrape sitemap mode pairs with extra_paths into a complete, zero-cost pipeline: scrape a site to markdown, index it, then ask questions answered verbatim from those docs (see Web Scraping):

[memory]
extra_paths = ["scrapes/docs.example.com"]

1. web_scrape url="https://docs.example.com" mode=sitemap export=true: every sitemap page saved as clean markdown under scrapes/, local extraction, no AI/API cost (hard cap: 100 pages per scrape)
2. Point extra_paths at the scrapes directory (relative paths resolve against the OpenCrabs home)
3. Ask anything: answers are grounded in and quoted from the indexed docs

Structural Code Search Upgrades (v0.5.1)

The code-graph answers (who calls X, what does X call, impact of X) got four upgrades:

• Truncation is now visible. Caller sets in real repos are unbounded (5,000+ call sites exist), so every structural listing that had to cut ends with a marker line ( “… and N more callers of X (re-query with higher n or offset)”) and sets beyond 500 collapse into a per-file rollup instead of one-liners. Nothing is silently chopped anymore.
• Offset pagination. memory_search accepts an offset alongside n for structural listings, so the full set can be walked page by page. Ranked text/vector results stay rank-truncated: the window applies to listings only.
• Depth-2 impact chains. impact of X now walks two hops over the call-edge graph, surfacing the callers-of-callers that a direct query misses.
• Cleaner hits. External code hits render repo-relative paths instead of absolute machine paths, and every scope=all hit carries a corpus provenance tag (which index the fact came from), so a memory answer and a code-graph answer can be told apart (#89).

Embedding Hardening (v0.3.81)

Embedding API calls now carry timeouts, a vector gate (malformed or empty vectors never reach the store), and non-blocking writes (embedding failures never stall the turn) (#1062). /doctor reports embedding health, and a sweep finds unembedded documents and backfills them (#1069, #1067).

Embedding Modes

OpenCrabs supports three embedding configurations:

1. Local GGUF (default): downloads a 300MB embedding model and runs it locally via llama.cpp
2. OpenAI-compatible API: configure external embedding providers (OpenAI text-embedding-3-small, Ollama nomic-embed-text, Jina, LM Studio, or any /v1/embeddings endpoint) via [memory.embedding] config with url, model, api_key, dimensions
3. FTS5-only: pure keyword search with zero RAM overhead. Set [memory] vector_enabled = false. Auto-detects VPS environments and configures automatically

Context Compaction

When context reaches ~80% capacity, OpenCrabs automatically compacts:

1. Summarizes the conversation so far into a comprehensive continuation document
2. Clears old messages from context
3. Continues with the summary as context

Manual compaction: type /compact in chat.

Auto-Save Triggers

The agent saves to memory when:

• New integrations are connected
• Server/infrastructure changes occur
• Bugs are found and fixed
• New tools are configured
• Credentials are rotated
• Architecture decisions are made
• You say “remember this”
• Errors take >5 minutes to debug

Proactive Memory Surfacing (v0.3.76)

The agent now surfaces relevant memory without being asked. When a conversation topic matches something stored in MEMORY.md or daily notes, the relevant context is loaded and injected automatically. Previously, memory was only recalled when the agent explicitly called memory_search or load_brain_file. Now the system proactively checks for relevant context on each turn, so the agent brings up past decisions, server details, or preferences that apply to the current conversation without you having to say “check your memory.”

Confidence, Decay and Pruning (v0.5.3)

MEMORY.md facts carry confidence and decay over time (#1643): a belief’s trust drops as it goes unused and unverified, so stale claims stop outranking fresh ones when memory is recalled. Decay is config-driven through the [epistemic] section.

Cold content is managed in two passes (#1657):

• Archive pass: cold MEMORY.md sections move to memory/archive/ with a backup and reindex, instead of silently accumulating forever.
• opencrabs memory prune: a dry-run preview (the default) of cold beliefs (key, confidence, hits, age) and cold sections (heading, bytes). --apply archives the sections first, then sweeps the remaining cold beliefs. --max-age-days <N> overrides the cold threshold (default: 90).

Brain Files

See Brain Files for the full list of files the agent reads on startup.

Brain Files

Brain files define the agent’s personality, knowledge, and behavior. They live at ~/.opencrabs/ and are loaded on every session start.

Startup Read Order

1. SOUL.md: Personality and values
2. USER.md: Your profile and preferences
3. memory/YYYY-MM-DD.md: Today’s notes
4. MEMORY.md: Long-term memory
5. AGENTS.md: Agent behavior guidelines
6. TOOLS.md: Tool reference and custom notes
7. CODE.md: Coding standards and file organization
8. SECURITY.md: Security policies
9. HEARTBEAT.md: Periodic check tasks

File Reference

SOUL.md

Agent personality. Core truths: strong opinions, brevity, resourcefulness, honesty. Hard rules: never delete files without approval, never send emails without request, never commit code directly.

USER.md

Your profile: name, location, timezone, role, specialties, communication preferences, pet peeves.

AGENTS.md

Comprehensive agent behavior docs: memory system, safety rules, git rules, workspace vs repository separation, cron best practices, platform formatting, heartbeat guidelines.

TOOLS.md

Tool parameter reference, system CLI tools, provider configuration, integration details for all channels and services.

CODE.md

Coding standards brain template. Enforces: no file over 500 lines (target 100–250), types in types.rs, one responsibility per file, mandatory tests for every feature, security-first patterns. Rust-first philosophy, single binary, no runtime dependencies. The agent follows these rules when writing or reviewing code.

SECURITY.md

Security policies: third-party code review, attack playbook awareness, network security, data handling, incident response.

HEARTBEAT.md

Tasks for periodic proactive checks. Keep empty to skip heartbeat API calls. Add tasks for the agent to rotate through (email checks, calendar, weather, etc.).

BOOT.md

Startup procedures: check git log, verify build, greet human with context awareness.

Query-Based Loading (v0.3.76)

load_brain_file now accepts an optional query parameter that returns only the sections matching the query instead of the entire file. This saves significant context budget:

load_brain_file(name="TOOLS.md", query="telegram")
→ Returns only the Telegram-related sections, not the full 2000-line file

Whole sections are returned (never cut mid-section), so a rule is never truncated. This is especially useful for large brain files like TOOLS.md and AGENTS.md where loading the full file wastes 10K+ tokens on irrelevant content.

Customization

These files are yours. The agent reads them but you control the content. Templates are at src/docs/reference/templates/ in the source repo, compare your local files against templates when updating to pick up new sections without losing custom content.

New installs (v0.2.72+): CODE.md and SECURITY.md are automatically seeded on first run. Existing users can ask their crab: “Check my brain templates and update them if any are missing or outdated.”

Upgrading: Brain files are never overwritten by /evolve or /rebuild. After updating, ask your crab to compare templates against local files and patch in new sections.

User-owned files are never synced (v0.3.82)

SOUL.md, USER.md and MEMORY.md are excluded from upstream template sync (#1119). They hold your agent’s personality, your identity, and what it has learned about you, so upstream has no authority over them. Before this, every startup appended upstream sections into them, which grew one user’s SOUL.md from under 2 KB to nearly 5 KB, re-appending after each manual prune.

Seeding is unaffected: all three are still created on first run. Only the merge is forbidden. The remaining brain files (AGENTS, TOOLS, CODE, SECURITY, BOOT, HEARTBEAT) continue to sync normally.

Related (#1121): rules belong in AGENTS.md, not MEMORY.md. MEMORY.md is on-demand, reached only through memory_search, so a rule written there does not bind on a cold session and does not survive compaction. Facts go in MEMORY.md; anything that must always hold goes in AGENTS.md, which is always loaded.

Sessions

Sessions as Isolated Agents

A session in OpenCrabs is not a tab, not a window, not a chat thread. Each session is a fully independent agent with its own brain: conversation history, provider, model, working directory, tool state, approval policy, and context window. When you create a new session, you are spinning up a separate agent that knows nothing about any other session and shares nothing with them.

This is the core mental model: one session = one agent = one context. You can run dozens of sessions in parallel and they will never interfere with each other.

Zero Context Contamination

Sessions are completely isolated at every layer:

• Separate message queues: each session has its own queue. Messages are routed strictly to their originating session. No cross-session bleeding, even when 10 sessions are processing simultaneously.
• Separate provider and model: switching to Gemini in session A does not affect session B running Claude. Each session remembers its own provider independently.
• Separate working directory: /cd in one session does not change the working directory of any other session.
• Separate conversation history: full SQLite-backed history per session. No shared memory, no prompt pollution, no context bleed.
• Separate token tracking: cumulative usage, cost, and context window are tracked per session.

This isolation is guaranteed by Rust’s thread safety and async runtime. Each session runs as an independent tokio task with its own state, and the type system prevents accidental sharing at compile time. You can run split panes, channel sessions, background agents, and sub-agents all at once with zero risk of one session’s output leaking into another.

Switching Sessions Keeps the Transcript

Switching sessions with /sessions and coming back does not fold your transcript away. The fold state for every turn is keyed by a stable role and timestamp anchor, so a turn you had opened stays open across a reload, and a turn you had folded stays folded (#2155). A turn that is still running also stays unfolded while it runs, so the work in flight stays visible instead of hiding behind a collapsed header.

The display window keeps a bounded number of recent messages in the pane rather than trimming by token budget, so one huge tool result can no longer evict the rest of the conversation. The hidden-count marker still tells you how many older rows are out of view, and Ctrl+O pages back through them.

Workflow Patterns: One Session Per Context

The power of isolated sessions becomes clear when you treat each one as a dedicated agent for a specific domain:

Pattern 1: DevOps for a Server

Create a session for a specific server or infrastructure concern. Send a first message like "Devops for server XYZ, monitor nginx builds, manage cronjobs, handle deployments, run log cleanups". The session locks into that context: working directory set to the server’s codebase, provider set to a fast model for quick ops tasks, history filled with that server’s deployment patterns. Come back to it days later and the agent remembers every previous deploy, every cron change, every nginx config tweak.

Pattern 2: Mobile App Development with a Co-Founder

Create a session named mybrand-mobile and connect it to a Telegram group with your co-founder. The agent is locked into the Dart/Flutter codebase, the product design context, and the mobile-specific toolchain. Your co-founder can ask questions, request design changes, or review PRs directly in Telegram while you work on backend tasks in a separate session. The two contexts never mix.

Pattern 3: Production Logs with a Team on Slack

Create a session named mybrand-prod-logs-debug and connect it to a Slack channel. Your team can ask questions about production, staging, or dev logs without you having to context-switch. The agent stays locked into log analysis mode with the right SSH aliases, the right log paths, and the right debugging tools. Meanwhile, your main TUI session is free for development work.

The key insight: you never have to explain the full context again. Once a session is locked into a domain, every follow-up message inherits that context automatically.

Session Context Integrity (v0.3.78)

Two fixes harden session_context (the tool agents use to store key-value state):

• Atomic writes: context writes now use atomic file operations, eliminating trailing-character corruption that could occur when a write was interrupted mid-flush. Previously, a crashed write could leave a JSON file with a truncated trailing character, making the entire context unreadable.
• Concurrency pinning: concurrent session_context calls from parallel tool executions no longer race on the same file. A concurrency pin serializes writes, and temp files are cleaned up after each operation.

Creating Sessions

• TUI: Press Ctrl+N or type /new
• Channels: Type /new in any channel

The First Message Matters

When you create a new session, the first message you send becomes the seed for the entire session’s context. OpenCrabs uses it to:

1. Auto-generate a session title: a background LLM call extracts a 3-8 word descriptive title from your first message. This runs asynchronously and never enters the conversation context.
2. Anchor the agent’s context: the initial message establishes what this session is about, what codebase it should focus on, what tools it should prioritize.

Good first messages are specific and contextual:

• "Devops for server XYZ: nginx, cronjobs, deployments, log cleanups"
• "Flutter mobile app for mybrand: Dart codebase at ~/srv/mobile/mybrand"
• "Debug production logs for mybrand staging and dev environments"

The auto-title will generate something like Devops Server XYZ, Mybrand Mobile Flutter, or Mybrand Prod Logs Debug. You can always rename it later.

Switching Sessions

• TUI: Press Ctrl+L to open the sessions screen, navigate with arrow keys, press Enter to select
• Channels: Type /sessions to see recent sessions with inline buttons

Renaming Sessions

Auto-generated titles are a starting point, not a final name. You can rename any session:

• TUI: Press Ctrl+L, navigate to the session, press r to rename
• Agent-initiated: the rename_session tool lets the agent rename the current session with a descriptive title when the conversation evolves beyond its original scope

Empty or whitespace-only titles are rejected (v0.3.30, #128).

Session Screen

The sessions screen shows:

• Session name
• Created date
• Provider/model badge
• Working directory
• Token usage
• Context window usage (current session)
• Status indicators (processing spinner, pending approval, unread)

Sub-Agent Sessions Stay Out of Your Way (v0.3.79)

Every spawned sub-agent creates a session titled subagent: {label}, and a busy turn can create several. They are an implementation detail of one tool call, so since v0.3.79:

• Sub-agent sessions are hidden from session lists the moment they exist, your session screen only ever shows your sessions.
• They are automatically purged once past agent.subagent_session_ttl_days (default 7; set 0 to keep them forever).
• Your own sessions are never touched: the cleanup sweep matches the subagent: title prefix only.

Per-Session State

Each session remembers:

• Provider and model: Switch to Claude in one, Gemini in another
• Working directory: /cd persists per session
• Conversation history: Full message history in SQLite
• Token count and cost: Cumulative usage tracking

v0.3.74 hardened per-session isolation:

• Per-session working directory: the working directory is isolated per session so it can’t leak across concurrent sessions (#703).
• Restore session provider: a session’s saved provider is restored before its turn, so it never accidentally runs on the global default (#704).
• Don’t persist involuntary remap: an involuntary provider/model remap is not persisted over a session’s saved pair (#705).

Session Management

Background Processing

Sessions can process in the background while you work in another session. The sessions screen shows:

• Spinner for actively processing sessions
• ! for sessions waiting for tool approval
• Dot for sessions with unread messages

Background Tasks (v0.3.74)

Long-running shell commands no longer block your session. When the agent runs a known-long command (cargo test, cargo build, npx remotion render, gh run watch, and similar), OpenCrabs auto-promotes it to a background task (#722): the command runs detached, the session is freed immediately, and the agent can keep working (or you can switch away) while it finishes.

When the task completes, the result is injected back into the originating session and resumes it automatically. On the TUI the session picks up at the next tool-call boundary; on Telegram the resume is delivered to the same chat (#722). No polling loops, no re-running the command to “check”, the completion report arrives on its own.

The agent is told via its preamble that long tasks run in the background and resume the session when done, so it wraps up or moves on instead of sitting in a wait loop (#722).

Two related session fixes landed in the same release:

• No perpetual resume: a completed session no longer resumes on every restart. Resume turns are not re-tracked as pending requests, so a finished background task stays finished across restarts (#729).
• No lingering cancelled query: a query cancelled before the agent replied, plus its empty assistant placeholder, are dropped as a pair so they don’t linger in context and duplicate on resend (#730).

Background-Task Resume Everywhere (v0.3.75)

v0.3.74 introduced background-task resume on the TUI and Telegram. v0.3.75 extends it to every channel: Discord, Slack, WhatsApp, and the interactive CLI agent now resume your session the moment a long task finishes, powered by a shared bg_resume helper so the behaviour is identical across surfaces.

A few refinements make background tasks easier to live with:

• Indicator on the input border: the background-task indicator moved onto the input border, and a detached command shows what it’s currently doing.
• No scaffolding in chat: a background task’s system scaffolding no longer reaches the chat.
• Restart-killed tasks reported: background tasks a restart killed are reported instead of leaving the session waiting forever.

Split Panes

Run multiple sessions side by side with tmux-style pane splitting. Each pane is a fully isolated agent, see Split Panes for details.

State Management

v0.2.92 improved session state tracking:

• Session reload after cancellation: After Esc+Esc cancel, session context reloads from DB to pick up any changes made during the cancelled operation
• Cached state cleanup: Deleting a session now clears stale pane cache entries, preventing phantom state on restart
• CLI tool segment persistence: Tool results from CLI providers (Claude CLI, OpenCode CLI) are now saved to DB alongside regular messages, preserving correct text/tool interleaving across restarts
• Case-insensitive tool input: Tool input descriptions use case-insensitive key lookup, fixing failures when providers return different casing

Channel Sessions

All channels (Telegram, Discord, Slack, WhatsApp, Trello) persist sessions in SQLite by channel/group title. Sessions survive process restarts, no more lost context after daemon restart. Each channel group gets its own isolated session, while owner DMs share the TUI session. Cross-channel stable session suffixes ([chat:<id>]) ensure reliable session resolution across Discord, Slack, and WhatsApp (v0.3.29).

Session-Routed Recovery Reports (v0.3.81)

Crash-recovery reports route by session (#1037): a resumed turn reports back to the session that owned it, not to whichever session happened to boot the recovery. Multi-session setups no longer cross-deliver recovery noise.

Split Panes

OpenCrabs supports tmux-style pane splitting in the TUI. Run multiple sessions side by side, each with its own provider, model, and context, all processing in parallel.

Splitting

How It Works

Each pane runs an independent session. You can have one pane writing code with Claude while another reviews tests with Gemini. The status bar shows [n/total] to indicate which pane is focused.

• Independent providers: Each pane can use a different AI provider and model
• Independent context: Conversation history is isolated per pane
• Parallel processing: All panes process concurrently via Tokio
• Persistent sessions: Each pane’s session is saved to SQLite like any other session

Example Layout

┌──────────────────────┬──────────────────────┐
│  Session 1 (Claude)  │  Session 2 (Gemini)  │
│  Writing code...     │  Reviewing PR...     │
├──────────────────────┴──────────────────────┤
│  Session 3 (OpenRouter)                      │
│  Running tests...                            │
└──────────────────────────────────────────────┘

Split vertically with _, then horizontally with | in the top pane.

Persistent Layout

Split pane configuration (splits, sizes, focused pane) saves to ~/.opencrabs/pane_layout.json on quit and Ctrl+C. On restart, your layout is restored exactly as you left it. Each restored pane preloads its session messages from the database, so content is visible immediately instead of blank.

Non-Focused Panes

Non-focused panes show compact tool call summaries and stripped reasoning text. Tool groups display as single collapsed lines matching the focused pane style. All panes auto-scroll to the bottom when new messages arrive.

v0.2.92 fixed several rendering issues:

• Tool calls no longer show a perpetual “running” spinner after completion
• Scroll position correctly tracks for inactive panes
• Stale cache is cleared when sessions are updated or deleted

State Management

Deleting a session now properly cleans up cached pane state. Previously, deleting a session left stale entries in the pane cache, which could cause phantom panes on restart.

Live Background Updates (v0.3.36)

Inactive panes now update live in the background. Previously, non-focused panes only refreshed when you switched focus to them. Now a background-session live-state cache routes IntermediateText and QueuedUserMessage events into per-session deltas, so you can watch tool calls and responses appearing in other panes in real time without switching focus.

Provider/model contamination prevention: When closing or switching panes, the old session’s provider is captured before the switch. This blocks cross-provider model leaks at 27 call sites throughout the codebase. The footer always shows the correct provider+model for the focused pane.

Ctrl+N binds the focused pane and live-refreshes the footer title, so new sessions show up immediately in the status bar.

Reasoning Expand (v0.3.74)

Reasoning blocks now cycle through three states instead of toggling open/closed. Click a reasoning block (or press Ctrl+O) to cycle: collapsed → capped → full. The capped middle state shows a bounded preview so a long chain-of-thought never floods the viewport (#727, #726).

Two refinements make expanding predictable:

• Anchor block on expand: the clicked block’s header is pinned to its screen row, so expanding or collapsing grows the block in place instead of jumping the viewport (#728).
• Click vs drag on mouse-up: click-vs-drag is decided on mouse-up, so a click-drag selects text (for copying) instead of toggling the expand state (#726).

Version in the UI (v0.3.74)

The running OpenCrabs version now shows on the TUI header and in channel /help and /usage output (#696), so you always know which build a session is on.

Double-Escape Returns the Query (v0.3.74)

Pressing Esc twice before any reply now returns the query to the input box and removes it from the conversation (#698), so a half-typed prompt you cancel doesn’t linger as an empty turn.

Per-Turn Headers (v0.3.75)

Every turn now gets a one-line header summarising the work that turn did, and the turn’s working-out folds up into it. OpenCrabs infers turn boundaries so each turn can be grouped, then folds the narration, intermediate text, and tool calls underneath the header.

The view stays clean by default:

• Fold every turn by default: turns fold as soon as they settle (and even while still running), so settled work collapses out of the way instead of scrolling off screen.
• Fold live: intermediate text folds while the turn is still running, and stale narration the model kept thinking past is collapsed.
• Readable folded turn: a folded turn stays readable and holds its place when toggled, and the tool-call summary stays at full visibility.
• Short live-thinking excerpt: live thinking shows a short excerpt with room to finish a thought, not a scrolling wall.
• Labelled token counter: the live token counter is labelled as a turn total and shows the ctx budget; ctx dropped from the spinner since it already shows under the input.

Expanding a turn is smooth: the header is kept after expand, and expanding no longer scrolls the view up by its own size.

TUI Improvements (v0.3.76–v0.3.78)

Steps AND Tools Display (v0.3.76)

The TUI now shows both steps and tool calls in the turn view. Previously it was either/or: if tool calls existed, steps were hidden. Now both render, with steps providing the narrative and tool calls showing the mechanical detail.

Background Task Position (v0.3.77)

Background task feedback moved from the left border to the right border of the input box. This prevents it from colliding with the context budget footer on the left.

Duplicate-Submit Guard (v0.3.76)

Pressing Enter twice quickly no longer submits the same message twice. The TUI drops a re-submitted message if the running turn is already answering it.

Command Labelling (v0.3.76)

Commands in the TUI are now labelled by what they run (e.g. “cargo test”) instead of the working directory. Makes the activity feed readable at a glance.

Deliverable Report Visibility (v0.3.78)

When a turn produces a deliverable report (audit, comparison, analysis), the report stays visible even when the turn folds. Previously, folding a turn would hide the report along with the working-out.

Background Running Indicator (v0.3.78)

The “running” indicator is now cleared before delivering the final response. Previously, the indicator could linger for a moment after the response appeared, creating a visual glitch.

Limits

There is no hard limit on pane count – you can run as many as your terminal fits. Each pane is a full session with its own token tracking and working directory.

Dynamic Tools

Define custom tools at runtime without recompiling. Tools are defined in ~/.opencrabs/tools.toml and can be created, removed, and reloaded on the fly.

Defining Tools

Create ~/.opencrabs/tools.toml:

[[tools]]
name = "deploy"
description = "Deploy the application to production"
executor = "shell"
command = "cd {{project_dir}} && ./deploy.sh {{environment}}"

[[tools]]
name = "check-status"
description = "Check service health"
executor = "http"
method = "GET"
url = "https://api.example.com/health"

Executors

Template Parameters

Use {{param}} syntax for dynamic values. The agent fills these in when calling the tool:

[[tools]]
name = "search-logs"
description = "Search application logs for a pattern"
executor = "shell"
command = "grep -r '{{pattern}}' /var/log/myapp/ --include='*.log' -l"

Runtime Management

The tool_manage meta-tool lets the agent manage dynamic tools during a session:

• Create: Add a new tool definition
• Remove: Delete an existing dynamic tool
• Reload: Re-read tools.toml without restarting

Dynamic tools appear alongside built-in tools in the agent’s tool list. Enable or disable individual tools without restarting the process.

Per-Parameter Value Coercion (v0.3.24)

Dynamic tools defined in tools.toml can now handle empty-string or null parameters gracefully. When a parameter arrives as "" or null, the engine substitutes a configured value before rendering the command template.

[[tools]]
name = "deploy"
description = "Deploy to environment with optional verbose flag"
executor = "shell"
command = "cd {{project_dir}} && ./deploy.sh --env {{environment}} {{verbose}}"

[[tools.deploy.params]]
name = "verbose"
type = "string"
required = false
coerce_empty_to = "--quiet"

A shell tool with an optional --verbose flag no longer breaks when the parameter is omitted. The engine substitutes --quiet (or any configured default) instead of passing an empty string.

(#95)

External contributions now enable tools.toml to be loaded in run mode and agent mode (not just the TUI). Previously, dynamic tools only worked in the interactive TUI session. Now they’re available across all modes, allowing headless automation and scripted workflows to use custom tools.

(#79: thanks @leshchenko)

Shell Parameter Escaping (v0.3.35)

Dynamic shell tool parameters now properly escape single quotes, preventing command injection edge cases when user-supplied values contain quotes. Contributed by @leshchenko1979.

Browser Automation

OpenCrabs includes native headless Chrome control via the Chrome DevTools Protocol (CDP). No Selenium, no Playwright, direct browser control built into the binary.

Requirements

• A Chromium-based browser installed (Chrome, Brave, Edge, or Chromium)
• Feature flag: browser (enabled by default)

OpenCrabs auto-detects your default Chromium browser, no manual path configuration needed.

Browser Tools

How It Works

The browser is lazy-initialized as a singleton, it only launches when the agent first needs it. It runs in stealth mode with a persistent profile directory, so cookies and sessions survive across tool calls.

On macOS, display auto-detection enables headed mode when a display is available, falling back to headless in CI or daemon environments.

Contoh

Ask the agent:

“Go to our staging site, log in with the test account, navigate to the dashboard, and take a screenshot”

The agent will chain navigate → type (username) → type (password) → click (login button) → navigate (dashboard) → screenshot: all autonomously.

Inventory Mode (v0.3.80)

browser_find now works without a pattern (#1022). Call it bare and it enumerates every visible interactive element on the page (links, buttons, inputs, selects, textareas, role=button elements, onclick handlers, tabindex elements, labels, and disclosure widgets) each stamped with a selector and index you can click directly.

This is the structural fix for the screenshot-as-discovery loop: instead of screenshotting repeatedly and guessing selectors, the agent gets the page’s clickable inventory in one call. When browser_screenshot reports an identical page, the hint now nudges toward inventory mode.

Shadow-DOM Resolution (v0.5.2)

Selector resolution is shadow-DOM aware: an element inside one or more shadow roots is reached by piercing the roots along the path, so web components and widget libraries that host their UI in shadow trees are automatable like light-DOM content. Applies across the browser tools (click, type, find, screenshot targeting).

Configuration

No configuration needed. The browser feature is enabled by default. To disable it at build time:

cargo build --release --no-default-features --features "telegram,discord,slack"

Cron Jobs

Schedule tasks to run on a recurring schedule. Cron jobs can run in isolated sessions or wake the main session.

CLI Management

# Add a job
opencrabs cron add \
  --name "Morning Report" \
  --cron "0 9 * * *" \
  --tz "Europe/London" \
  --prompt "Check emails, calendar, and give me a morning briefing" \
  --deliver-to telegram:123456

# List all jobs
opencrabs cron list

# Enable/disable (accepts name or ID)
opencrabs cron enable "Morning Report"
opencrabs cron disable "Morning Report"

# Remove (accepts name or ID)
opencrabs cron remove "Morning Report"

Agent Management

The agent can also manage cron jobs via the cron_manage tool:

"Create a cron job that checks my emails every morning at 9am"

Since v0.3.80, cron_manage supports an update action that patches an existing job in place (#966), change the schedule, prompt, model, or delivery target without deleting and recreating the job.

Options

Multi-Target Delivery

deliver_to accepts comma-separated targets to send results to multiple destinations simultaneously:

opencrabs cron add \
  --name "Morning Report" \
  --cron "0 9 * * *" \
  --prompt "Give me a morning briefing" \
  --deliver-to "telegram:-12345,http://webhook.example.com/notify"

Supported targets in any combination:

• telegram:CHAT_ID or telegram:-GROUP_ID
• discord:CHANNEL_ID
• slack:CHANNEL_ID
• whatsapp:PHONE_OR_JID
• http://... or https://... (webhook URL)

Target URLs (v0.5.1)

Since v0.5.1 every delivery field also speaks a unified oc:// target scheme, resolved by a central resolver against the live channel bindings (issue #148):

Target URLs are resolved once, at create/update time, and the concrete channel target is baked into the job; if an unbaked URL ever reaches fire time the run fails loudly instead of resolving against a possibly-changed world.

Forum-topic delivery (v0.5.1, opt-in)

telegram:CHAT_ID:THREAD_ID (or the oc://telegram/<chat>/<thread> form) delivers into a specific topic of a forum group. It is deliberately opt-in: the chat must actually be a forum and the topic must exist: an invalid thread target is rejected loudly at fire time, never silently re-routed to the general topic. When a job is created from inside a thread (here/oc:// form), the origin thread id is persisted so the result lands back in the same topic (#104).

Results are stored in the DB via the cron_results table regardless of delivery target, so you can query past execution results with opencrabs cron results <name>.

Trigger-gated jobs (v0.5.3)

A job can carry a pre-flight trigger: at each fire time the scheduler runs a shell command first, and only executes the prompt when a condition on that command’s result is met. This turns scheduled jobs from “fires into the void every hour” into “acts when something actually happened” (a file appeared, a health check failed, a log line matched) (#233).

Set it through the cron_manage tool at create or update time:

trigger_on conditions

Semantics

• Condition not met → the run is short-circuited at 0 tokens and recorded as a skipped/success run. The prompt never executes, nothing is delivered.
• Trigger command errors or times out → the run is recorded as an error; the prompt still does not execute.
• Empty prompt with a trigger → direct 0-token delivery: the formatted trigger output (goal_template, or the raw output) is delivered to deliver_to without an agent turn at all.
• set_goal → the fired trigger dispatches into the target session as an active goal, so the session’s agent works the condition it detected rather than just echoing output.

Put the watching in trigger_cmd (deterministic, cheap, script-runner pattern), the condition in trigger_on, and the acting in the prompt or goal.

Scheduler Lock (v0.3.65)

The cron scheduler uses a file lock to prevent duplicate job execution. Only one scheduler instance can run per profile at a time. If you accidentally start OpenCrabs twice, the second instance won’t fire duplicate cron jobs.

Heartbeat vs Cron

Use heartbeat (HEARTBEAT.md) when:

• Checks are periodic but timing is flexible (~30 min)
• You want to reduce API calls by batching
• Tasks share the main session context

Use cron when:

• Exact timing matters (“9:00 AM every Monday”)
• Task needs isolation from main session
• You want a different model or thinking level
• Output should deliver to a specific channel

Plans

Plans provide structured multi-step task execution with a live progress widget in the TUI.

Creating a Plan

Ask the agent to plan a complex task:

"Plan the migration from PostgreSQL to SQLite"

The agent uses the plan tool internally to create a plan with:

• Title and description
• Technical stack
• Risk assessment
• Test strategy
• Ordered tasks with dependencies and complexity ratings

Plan Lifecycle

1. Draft: Agent creates the plan and adds tasks
2. Finalize: Agent calls finalize which triggers the tool approval dialog
3. Approved: You approve in the tool dialog, plan status becomes Approved, and the agent begins executing tasks immediately
4. In Progress: Tasks execute in dependency order
5. Completed: All tasks done

In ask mode (default), the finalize step triggers the tool approval dialog, you review the full plan before execution begins. In auto-approve mode, finalize is auto-approved and the agent plans and executes without pausing.

Plan Requirement Gate

A turn that crosses a threshold of tool calls has to stop and write a plan before it continues (#2128). This is what keeps a sprawling refactor from being discovered after twenty files have already changed: you see the shape of the work, and you get a chance to say no before it lands.

The gate is configurable under [agent]. A turn that already has a live plan is never gated again, and a session configured to run autonomously is not stalled by an approval prompt it was told to skip.

Task States

Each task in a plan can be:

• Pending (·): Waiting for dependencies
• InProgress (▶): Currently executing
• Completed (✓): Done
• Skipped (✓): Manually skipped
• Failed (✗): Execution failed
• Blocked (·): Dependencies not met

TUI Plan Widget

When a plan is active, a live checklist panel appears above the input box showing:

• Plan title and progress counter (e.g. 3/7)
• Progress bar: Visual ██████░░░░ bar with percentage
• Task list: Up to 6 tasks visible with status icons and task numbers
• Overflow indicator: ... (N more) when tasks exceed the visible limit

The widget updates in real-time as the agent completes each task.

Managing Plans

Plans are managed through natural language:

"Approve the plan"
"Reject the plan"
"What's the plan status?"
"Skip task 3"

The agent handles plan creation, approval, execution, and status reporting through the plan tool.

Mid-Plan Insertion (v0.3.36)

Tasks can be inserted at any position in an existing plan using insert_after:

plan(operation: "add_task", insert_after: 3, title: "Re-run tests after fix", ...)

This inserts the new task as task #4, and all existing tasks from #4 onward are renumbered automatically. Dependencies between tasks are preserved through the renumber.

This is useful when a later task introduces a bug caught by an earlier test. Instead of re-opening the completed test task, insert a fresh re-test task right after the fix.

Finished Checklist Persistence (v0.3.76)

When a plan completes all tasks, the finished checklist now stays on screen instead of disappearing. You can review the final state (all tasks marked ✓) without having to ask “what was the plan?” again. The completed card renders its final state with the full task list and progress bar at 100%.

Epistemic Orient Gate (v0.3.78)

Plan execution is now gated behind an epistemic Orient phase before any task starts. The agent must:

1. Observe: gather ground truth (read files, check state)
2. Orient: map observations against current beliefs and goals
3. Decide: form intention, confirm alignment and safety
4. Act: execute through mechanical gates