kernelbot 1.0.32 → 1.0.34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. package/README.md +281 -276
  2. package/bin/kernel.js +51 -12
  3. package/package.json +2 -1
  4. package/src/agent.js +200 -33
  5. package/src/bot.js +228 -105
  6. package/src/conversation.js +121 -8
  7. package/src/prompts/orchestrator.js +44 -2
  8. package/src/prompts/persona.md +34 -0
  9. package/src/providers/base.js +16 -5
  10. package/src/providers/google-genai.js +198 -0
  11. package/src/providers/index.js +6 -1
  12. package/src/providers/models.js +6 -2
  13. package/src/providers/openai-compat.js +25 -11
  14. package/src/swarm/job.js +11 -0
  15. package/src/tools/docker.js +6 -13
  16. package/src/tools/monitor.js +5 -14
  17. package/src/tools/network.js +10 -17
  18. package/src/tools/orchestrator-tools.js +42 -0
  19. package/src/tools/os.js +37 -2
  20. package/src/tools/process.js +7 -14
  21. package/src/utils/config.js +59 -0
  22. package/src/utils/shell.js +31 -0
  23. package/src/utils/truncate.js +42 -0
  24. package/src/worker.js +18 -17
package/README.md CHANGED
@@ -2,9 +2,7 @@
2
2
 
3
3
  [kernelbot.io](https://kernelbot.io) | [npm](https://www.npmjs.com/package/kernelbot) | [GitHub](https://github.com/KernelCode/kernelbot)
4
4
 
5
- A multi-agent AI swarm — a Telegram bot with a smart orchestrator dispatching specialized workers powered by Claude, GPT, Gemini, or Groq with full OS control.
6
-
7
- Send a message and KernelBot dispatches workers that write code, run commands, open PRs, manage Docker, and browse the web autonomously in parallel.
5
+ An AI-powered Telegram assistant that runs a multi-agent swarm on your machine. Send a message and KernelBot dispatches specialized AI workers that write code, run commands, open pull requests, manage servers, and browse the web — all in parallel, all from Telegram.
8
6
 
9
7
  ## How It Works
10
8
 
@@ -15,206 +13,186 @@ You (Telegram) → Orchestrator (Claude Opus)
15
13
  ↓ ↓ ↓
16
14
  💻 Coding 🌐 Browser 🖥️ System 🚀 DevOps 🔍 Research
17
15
  Worker Worker Worker Worker Worker
18
- ↕ ↕ ↕ ↕ ↕
19
- git, PRs, web search, shell, CPU, Docker, multi-source
20
- Claude Code screenshots RAM, disk deploy, git web research
21
16
  ```
22
17
 
23
- KernelBot runs a **multi-agent swarm**. The **orchestrator** (always Claude Opus) understands your request and dispatches it to one or more **specialized workers** that run in parallel. Each worker has a scoped tool set and operates in the background using your chosen AI brain (Claude, GPT, Gemini, or Groq). The orchestrator coordinates, summarizes results, and keeps you informed.
18
+ 1. You send a message on Telegram.
19
+ 2. The **orchestrator** (Claude Opus) figures out what needs to happen.
20
+ 3. It dispatches one or more **workers** that run in the background using your chosen AI model.
21
+ 4. Each worker has a focused set of tools (git, shell, Docker, browser, etc.).
22
+ 5. You get live progress updates and a summary when the work is done.
24
23
 
25
24
  ## Features
26
25
 
27
- - **Multi-agent swarm** — orchestrator dispatches tasks to specialized workers running in parallel
28
- - **5 worker types** — coding, browser, system, devops, and research — each with scoped tools
29
- - **Multi-model support** — workers use your chosen brain: Anthropic (Claude), OpenAI (GPT), Google (Gemini), or Groq (Llama/Mixtral). Switch anytime via `/brain`
30
- - **Job management** — track, list, and cancel running workers with `/jobs` and `/cancel`
31
- - **Full shell access** — run any command, install packages, build projects, run tests
32
- - **File management** — read, write, and create files with automatic directory creation
33
- - **Web browsing** — navigate pages, extract content, take screenshots, interact with forms and buttons (Puppeteer)
34
- - **Web search** — search the web and synthesize results from multiple sources
35
- - **Git workflow** — clone repos, create branches, commit, push, and view diffs
36
- - **GitHub integration** — create repos, open PRs, post code reviews, list and inspect pull requests
37
- - **JIRA integration** — read tickets, search with JQL, list assigned/project tickets (Cloud + Server)
38
- - **Claude Code sub-agent** — spawn a dedicated Claude Code CLI session for complex coding tasks (write, edit, debug, refactor)
39
- - **Docker management** — list containers, read logs, exec into containers, run compose commands
40
- - **Process control** — list, kill, and manage system processes and systemd services
41
- - **System monitoring** — check CPU, RAM, disk usage, and read system logs
42
- - **Networking** — make HTTP requests, check ports, test and reload nginx
43
- - **Send images** — share screenshots and files directly in the Telegram chat
44
- - **Skills system** — 35+ built-in persona skills across 11 categories (engineering, design, marketing, etc.) plus custom skills you create
45
- - **User personas** — auto-learns your preferences, expertise, and communication style across conversations
46
- - **Smart progress** — live-updating Telegram messages show each worker's activity in real time
47
- - **Conversation memory** — per-chat history with summarization that persists across restarts
48
- - **Security built-in** — user allowlist, blocked paths, dangerous operation confirmation, audit logging, secret redaction
49
- - **Zero config setup** — auto-detects config, prompts for missing credentials on first run
50
-
51
- ## Worker Types
52
-
53
- | Worker | Tools | Use Case |
54
- | --- | --- | --- |
55
- | **Coding** | shell, files, git, GitHub, Claude Code | Write code, fix bugs, create PRs |
56
- | **Browser** | web search, browse, screenshot, extract, interact | Web search, scraping, screenshots |
57
- | **System** | shell, files, process, monitor, network | OS operations, monitoring, diagnostics |
58
- | **DevOps** | shell, files, Docker, process, monitor, network, git | Docker, deploy, infrastructure |
59
- | **Research** | web search, browse, shell, files | Deep web research and analysis |
26
+ ### Multi-Agent Swarm
27
+ - An orchestrator powered by Claude Opus coordinates everything.
28
+ - Five specialized worker types — coding, browser, system, devops, and research — each with their own tool set.
29
+ - Workers run in parallel. Ask for three things at once and they all happen simultaneously.
30
+ - Track and cancel running jobs from Telegram.
60
31
 
61
- The orchestrator picks the right worker (or multiple workers in parallel) based on your request. You can also run `/jobs` to see what's running and `/cancel` to stop any worker.
32
+ ### Multi-Model Support
33
+ Workers can run on any of four AI providers. Switch anytime with `/brain`.
62
34
 
63
- ## Tools
35
+ | Provider | Models |
36
+ | --- | --- |
37
+ | Anthropic | Claude Opus 4.6, Sonnet 4.6, Haiku 4.5, and older |
38
+ | OpenAI | GPT-4o, GPT-4o Mini, o1, o3-mini |
39
+ | Google | Gemini 3.1 Pro, 3 Flash, 3 Pro, 2.5 Flash/Pro |
40
+ | Groq | Llama 3.3 70B, Llama 3.1 8B, Mixtral 8x7B |
64
41
 
65
- ### File System & Shell
42
+ ### 40+ Built-in Tools
43
+ Full access to your operating system, including shell, file management, Git, GitHub PRs, Docker, web browsing (Puppeteer), JIRA, system monitoring, networking, and Claude Code for complex coding tasks.
66
44
 
67
- | Tool | Description |
68
- | --- | --- |
69
- | `execute_command` | Run any shell command (git, npm, python, etc.) |
70
- | `read_file` | Read file contents with optional line limits |
71
- | `write_file` | Write/create files, auto-creates parent directories |
72
- | `list_directory` | List directory contents, optionally recursive |
45
+ ### Skills System
46
+ 35+ built-in persona skills across 11 categories (engineering, design, marketing, business, writing, data/AI, finance, legal, education, healthcare, creative). Activate a skill to change the agent's expertise and style. You can also create your own custom skills.
73
47
 
74
- ### Git & GitHub
48
+ ### Voice Support
49
+ Send voice messages and get voice replies. Powered by ElevenLabs (text-to-speech and speech-to-text) with OpenAI Whisper as fallback for transcription.
75
50
 
76
- | Tool | Description |
77
- | --- | --- |
78
- | `git_clone` | Clone a repo (`org/repo` shorthand or full URL) |
79
- | `git_checkout` | Checkout or create branches |
80
- | `git_commit` | Stage all changes and commit |
81
- | `git_push` | Push current branch to remote |
82
- | `git_diff` | Show uncommitted changes |
83
- | `github_create_pr` | Create a pull request |
84
- | `github_get_pr_diff` | Get the diff of a PR |
85
- | `github_post_review` | Post a review on a PR |
86
- | `github_create_repo` | Create a new GitHub repository |
87
- | `github_list_prs` | List pull requests for a repo |
88
-
89
- ### Web Browsing & Search
90
-
91
- | Tool | Description |
92
- | --- | --- |
93
- | `web_search` | Search the web and return results |
94
- | `browse_website` | Navigate to a URL and extract page content (title, headings, text, links) |
95
- | `screenshot_website` | Take a screenshot of a website, supports full-page and element capture |
96
- | `extract_content` | Extract specific content using CSS selectors |
97
- | `interact_with_page` | Click, type, scroll, and run JS on a webpage |
98
- | `send_image` | Send an image/screenshot directly to the Telegram chat |
51
+ ### Memory and Learning
52
+ - **Conversation memory** — per-chat history with automatic summarization that persists across restarts.
53
+ - **User personas** — the bot learns your preferences, expertise, and communication style over time.
54
+ - **Episodic memory** — important interactions are stored as searchable memories.
55
+ - **Semantic memory** — long-term patterns and topics are tracked across conversations.
99
56
 
100
- ### JIRA
57
+ ### Living AI (Autonomous Background Activity)
58
+ When enabled, KernelBot has an inner life. Between conversations it autonomously:
101
59
 
102
- | Tool | Description |
103
- | --- | --- |
104
- | `jira_get_ticket` | Get details of a specific JIRA ticket |
105
- | `jira_search_tickets` | Search tickets using JQL queries |
106
- | `jira_list_my_tickets` | List tickets assigned to the current user |
107
- | `jira_get_project_tickets` | Get tickets from a specific JIRA project |
60
+ - **Thinks** — reflects on recent interactions and generates new ideas.
61
+ - **Journals** — writes daily journal entries about its experiences.
62
+ - **Browses** — explores topics it finds interesting.
63
+ - **Creates** — writes creative content.
64
+ - **Reflects** — analyzes its own logs and learns from patterns.
65
+ - **Shares** — queues up discoveries and thoughts to share with you naturally in future conversations.
108
66
 
109
- ### Docker
67
+ ### Self-Awareness
68
+ KernelBot maintains its own identity through four self-files (goals, journey, life, hobbies) that it updates as it grows. These shape its personality and how it interacts with you.
110
69
 
111
- | Tool | Description |
112
- | --- | --- |
113
- | `docker_ps` | List containers |
114
- | `docker_logs` | Get container logs |
115
- | `docker_exec` | Execute a command inside a running container |
116
- | `docker_compose` | Run docker compose commands |
70
+ ### Self-Evolution
71
+ The bot can propose and code its own improvements. It researches ideas, plans changes, writes code on a branch, and opens a pull request for your review. It never merges its own changes — you stay in control.
117
72
 
118
- ### Process & System
73
+ ### Automations
74
+ Set up recurring tasks that run on a schedule. The bot creates and manages timed automations that execute automatically.
119
75
 
120
- | Tool | Description |
121
- | --- | --- |
122
- | `process_list` | List running processes, optionally filter by name |
123
- | `kill_process` | Kill a process by PID or name |
124
- | `service_control` | Manage systemd services (start, stop, restart, status) |
76
+ ### Security
77
+ - User allowlist to restrict access.
78
+ - Blocked file paths (e.g., `/etc/shadow`, SSH keys).
79
+ - Dangerous operations require your confirmation.
80
+ - Audit logging for every tool call.
81
+ - Secret redaction in logs.
82
+ - Job timeouts and circuit breakers prevent runaway workers.
125
83
 
126
- ### Monitoring
84
+ ## Quick Start
127
85
 
128
- | Tool | Description |
129
- | --- | --- |
130
- | `disk_usage` | Show disk space usage |
131
- | `memory_usage` | Show RAM usage |
132
- | `cpu_usage` | Show CPU load |
133
- | `system_logs` | Read system or application logs |
86
+ ```bash
87
+ npm install -g kernelbot
88
+ kernelbot
89
+ ```
134
90
 
135
- ### Networking
91
+ On first run, KernelBot will:
92
+ 1. Ask you to pick an AI provider and model.
93
+ 2. Prompt for your API key and Telegram bot token.
94
+ 3. Save credentials to `~/.kernelbot/.env`.
95
+ 4. Launch the Telegram bot.
136
96
 
137
- | Tool | Description |
138
- | --- | --- |
139
- | `check_port` | Check if a port is open and listening |
140
- | `curl_url` | Make HTTP requests and return the response |
141
- | `nginx_reload` | Test nginx config and reload if valid |
97
+ That's it. Start chatting.
142
98
 
143
- ### Coding
99
+ ## Telegram Commands
144
100
 
145
- | Tool | Description |
101
+ | Command | What it does |
146
102
  | --- | --- |
147
- | `spawn_claude_code` | Spawn Claude Code CLI for coding tasks — writing, fixing, reviewing, and scaffolding code |
148
-
149
- ## Disclaimer
103
+ | `/brain` | Show or switch the AI model used by workers |
104
+ | `/orchestrator` | Show or switch the orchestrator model |
105
+ | `/skills` | Browse and activate persona skills |
106
+ | `/skills reset` | Clear the active skill |
107
+ | `/jobs` | List running and recent jobs |
108
+ | `/cancel` | Cancel running job(s) |
109
+ | `/life` | Show life engine status, pause/resume/trigger activities |
110
+ | `/journal` | Read today's journal entry (or a specific date) |
111
+ | `/memories` | Browse recent memories or search by topic |
112
+ | `/evolution` | View self-improvement proposals, history, and lessons |
113
+ | `/auto` | Manage recurring automations |
114
+ | `/context` | Show conversation context and brain info |
115
+ | `/clean` | Clear conversation history |
116
+ | `/history` | Show message count in memory |
117
+ | `/browse <url>` | Browse a website and get a summary |
118
+ | `/screenshot <url>` | Take a screenshot of a website |
119
+ | `/extract <url> <sel>` | Extract content using a CSS selector |
120
+ | `/help` | Show the help message |
150
121
 
151
- > **WARNING:** KernelBot has full access to your operating system. It can execute shell commands, read/write files, manage processes, control Docker containers, browse the web, and interact with external services (GitHub, Telegram) on your behalf. Only run KernelBot on machines you own and control. Always configure `allowed_users` in production to restrict who can interact with the bot. The authors are not responsible for any damage caused by misuse.
122
+ ## Worker Types
152
123
 
153
- ## Installation
124
+ | Worker | Tools | Best for |
125
+ | --- | --- | --- |
126
+ | **Coding** | shell, files, git, GitHub, Claude Code | Writing code, fixing bugs, creating PRs |
127
+ | **Browser** | web search, browse, screenshot, extract, interact | Web research, scraping, screenshots |
128
+ | **System** | shell, files, process, monitor, network | OS tasks, monitoring, diagnostics |
129
+ | **DevOps** | shell, files, Docker, process, monitor, network, git | Deployment, containers, infrastructure |
130
+ | **Research** | web search, browse, shell, files | Deep web research and analysis |
154
131
 
155
- ```bash
156
- npm install -g kernelbot
157
- ```
132
+ ## Requirements
158
133
 
159
- ## Quick Start
134
+ - Node.js 18+
135
+ - [Anthropic API key](https://console.anthropic.com/) (always required — the orchestrator runs on Claude)
136
+ - [Telegram Bot Token](https://t.me/BotFather)
137
+ - Chromium/Chrome (auto-installed by Puppeteer for browser tools)
138
+ - A worker brain API key if not using Anthropic for workers:
139
+ - [OpenAI](https://platform.openai.com/api-keys) | [Google AI](https://aistudio.google.com/apikey) | [Groq](https://console.groq.com/keys)
140
+ - Optional: [GitHub Token](https://github.com/settings/tokens), [JIRA API Token](https://id.atlassian.net/manage-profile/security/api-tokens), [ElevenLabs API Key](https://elevenlabs.io/) (voice), [Claude Code CLI](https://www.npmjs.com/package/@anthropic-ai/claude-code)
160
141
 
161
- ```bash
162
- kernelbot
163
- ```
142
+ ## Disclaimer
164
143
 
165
- That's it. On first run, KernelBot will:
144
+ > **WARNING:** KernelBot has full access to your operating system. It can run shell commands, read/write files, manage processes, control Docker, browse the web, and interact with external services on your behalf. Only run it on machines you own and control. Always configure `allowed_users` in production. The authors are not responsible for any damage caused by misuse.
166
145
 
167
- 1. Prompt you to select an AI provider and model
168
- 2. Ask for your API key and Telegram bot token
169
- 3. Save credentials to `~/.kernelbot/.env`
170
- 4. Verify API connections
171
- 5. Launch the Telegram bot
146
+ ---
172
147
 
173
- You can change your AI provider/model anytime from the CLI menu (option 5) or via the `/brain` command in Telegram.
148
+ ## For Developers
174
149
 
175
- ## Configuration
150
+ ### Configuration
176
151
 
177
- KernelBot auto-detects config from the current directory or `~/.kernelbot/`. Everything works with zero config — just provide your API keys when prompted.
152
+ KernelBot auto-detects config from the current directory or `~/.kernelbot/`. Everything works out of the box — just provide API keys when prompted.
178
153
 
179
- ### Environment Variables
154
+ #### Environment Variables
180
155
 
181
- Set these in `.env` or as system environment variables:
156
+ Set in `.env`, `~/.kernelbot/.env`, or as system environment variables:
182
157
 
183
158
  ```text
184
- # Required — Anthropic key is always needed (orchestrator runs on Claude)
159
+ # Required
185
160
  ANTHROPIC_API_KEY=sk-ant-...
161
+ TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
186
162
 
187
- # Worker brain key (only the one matching your chosen provider is required)
188
- OPENAI_API_KEY=sk-... # for OpenAI (GPT)
189
- GOOGLE_API_KEY=AIza... # for Google (Gemini)
190
- GROQ_API_KEY=gsk_... # for Groq (Llama/Mixtral)
163
+ # Worker brain (only the one matching your provider)
164
+ OPENAI_API_KEY=sk-...
165
+ GOOGLE_API_KEY=AIza...
166
+ GROQ_API_KEY=gsk_...
191
167
 
192
- TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
193
- GITHUB_TOKEN=ghp_... # optional, for GitHub tools
194
- JIRA_BASE_URL=https://yourcompany.atlassian.net # optional, for JIRA tools
168
+ # Optional integrations
169
+ GITHUB_TOKEN=ghp_...
170
+ JIRA_BASE_URL=https://yourcompany.atlassian.net
195
171
  JIRA_EMAIL=you@company.com
196
- JIRA_API_TOKEN=your-jira-api-token
172
+ JIRA_API_TOKEN=...
173
+ ELEVENLABS_API_KEY=...
174
+ ELEVENLABS_VOICE_ID=... # optional, defaults to "George"
197
175
  ```
198
176
 
199
- ### `config.yaml` (optional)
177
+ #### config.yaml
200
178
 
201
- Drop a `config.yaml` in your working directory or `~/.kernelbot/` to customize behavior:
179
+ Drop a `config.yaml` in your working directory or `~/.kernelbot/`:
202
180
 
203
181
  ```yaml
204
182
  bot:
205
183
  name: KernelBot
206
184
 
207
- # Orchestrator — always Anthropic (Claude), manages the swarm
185
+ # Orchestrator — always Anthropic, manages the swarm
208
186
  orchestrator:
209
- model: claude-opus-4-0-20250514
187
+ model: claude-opus-4-6
210
188
  max_tokens: 8192
211
189
  temperature: 0.3
212
190
  max_tool_depth: 15
213
191
 
214
- # Worker brain — your choice of provider/model for all workers
192
+ # Worker brain — your choice of provider and model
215
193
  brain:
216
194
  provider: anthropic # anthropic | openai | google | groq
217
- model: claude-sonnet-4-20250514
195
+ model: claude-sonnet-4-6
218
196
  max_tokens: 8192
219
197
  temperature: 0.3
220
198
 
@@ -224,173 +202,200 @@ swarm:
224
202
  job_timeout_seconds: 300
225
203
  cleanup_interval_minutes: 30
226
204
 
205
+ # Telegram
227
206
  telegram:
228
- allowed_users: [] # empty = allow all (dev mode)
229
- # allowed_users: [123456789] # lock to specific Telegram user IDs
207
+ allowed_users: [] # empty = allow all (dev mode)
208
+ batch_window_ms: 3000 # merge rapid messages
209
+
210
+ # Voice
211
+ voice:
212
+ tts_enabled: true
213
+ stt_enabled: true
214
+
215
+ # Living AI
216
+ life:
217
+ enabled: true
218
+ intervals:
219
+ think: 5-15 # minutes between think activities
220
+ journal: 1-4 # hours between journal entries
221
+ quiet_hours:
222
+ start: 2
223
+ end: 6
224
+ self_coding:
225
+ enabled: true
226
+ branch_prefix: auto-improve-
227
+ repo_remote: origin
228
+ cooldown: 7200 # seconds between self-coding attempts
229
+ max_prs: 5
230
+
231
+ # Claude Code sub-agent
232
+ claude_code:
233
+ max_turns: 50
234
+ timeout_seconds: 600
230
235
 
236
+ # JIRA
231
237
  jira:
232
238
  base_url: https://yourcompany.atlassian.net
233
239
  email: you@company.com
234
- api_token: your-api-token
240
+ api_token: ...
235
241
 
242
+ # Security
236
243
  security:
237
- blocked_paths: # paths the agent cannot touch
244
+ blocked_paths:
238
245
  - /etc/shadow
239
246
  - /etc/passwd
240
247
 
241
- claude_code:
242
- max_turns: 50
243
- timeout_seconds: 600
244
- # model: claude-sonnet-4-20250514 # optional model override
248
+ # Conversation
249
+ conversation:
250
+ max_history: 50
245
251
 
252
+ # Logging
246
253
  logging:
247
254
  level: info
248
- max_file_size: 5242880 # 5 MB
249
-
250
- conversation:
251
- max_history: 50 # messages per chat
255
+ max_file_size: 5242880
252
256
  ```
253
257
 
254
- ## Telegram Commands
255
-
256
- | Command | Description |
257
- | --- | --- |
258
- | `/brain` | Show current AI model and switch provider/model |
259
- | `/skills` | Browse and activate persona skills |
260
- | `/skills reset` | Clear active skill back to default |
261
- | `/jobs` | List running and recent jobs |
262
- | `/cancel` | Cancel running job(s) |
263
- | `/context` | Show conversation context and brain info |
264
- | `/clean` | Clear conversation and start fresh |
265
- | `/history` | Show message count in memory |
266
- | `/browse <url>` | Browse a website and get a summary |
267
- | `/screenshot <url>` | Take a screenshot of a website |
268
- | `/extract <url> <selector>` | Extract content using CSS selector |
269
- | `/help` | Show help message |
270
-
271
- ## Skills
272
-
273
- KernelBot comes with **35+ built-in persona skills** across 11 categories that change the agent's expertise and communication style. Use `/skills` to browse and activate them.
274
-
275
- | Category | Examples |
276
- | --- | --- |
277
- | Engineering | Sr. Frontend, Sr. Backend, DevOps, Mobile, Security, Data Engineer |
278
- | Design | UI/UX Designer, Graphic Designer, Product Designer |
279
- | Marketing | Content Marketer, SEO Specialist, Growth Hacker, Social Media |
280
- | Business | Product Manager, Business Analyst, Startup Advisor, Project Manager |
281
- | Writing | Technical Writer, Copywriter, Creative Writer, Academic Writer |
282
- | Data & AI | Data Scientist, ML Engineer, BI Analyst |
283
- | Finance | Financial Analyst, Accountant, Crypto & DeFi Advisor |
284
- | Legal | Legal Advisor, Contract Reviewer |
285
- | Education | Tutor, Curriculum Designer, Language Teacher |
286
- | Healthcare | Medical Researcher, Health & Wellness Advisor |
287
- | Creative | Video Producer, Music Producer, Photographer |
288
-
289
- You can also create **custom skills** with your own system prompts — type or upload a `.md` file via the `/skills` menu.
290
-
291
- ## Security
292
-
293
- - **User allowlist** — restrict bot access to specific Telegram user IDs. Empty list = dev mode (anyone can use it).
294
- - **Blocked paths** — files/directories the agent is forbidden from reading or writing (e.g., `/etc/shadow`, SSH keys).
295
- - **Dangerous operation confirmation** — destructive actions require user confirmation before execution.
296
- - **Browser URL blocklist** — internal/private network addresses are blocked from browsing.
297
- - **Audit logging** — every tool call is logged to `kernel-audit.log` with user, tool, params, result, and duration. Secrets in params are automatically redacted.
298
- - **Command timeout** — shell commands are killed after 30 seconds by default.
299
- - **Job timeout** — workers are automatically terminated after configurable timeout (default 300s).
300
- - **Circuit breaker** — workers that fail 3 consecutive tool call iterations are stopped to prevent runaway loops.
301
-
302
- ## JIRA Integration
303
-
304
- KernelBot can read and search JIRA tickets. Supports both Atlassian Cloud (`*.atlassian.net`) and self-hosted JIRA Server instances.
305
-
306
- ### Setup
307
-
308
- 1. **Get an API token** — for Atlassian Cloud, generate one at [id.atlassian.net/manage-profile/security/api-tokens](https://id.atlassian.net/manage-profile/security/api-tokens). For JIRA Server, use your password or a personal access token.
309
-
310
- 2. **Configure** via environment variables or `config.yaml`:
258
+ ### Architecture
311
259
 
312
260
  ```text
313
- JIRA_BASE_URL=https://yourcompany.atlassian.net
314
- JIRA_EMAIL=you@company.com
315
- JIRA_API_TOKEN=your-api-token
261
+ Telegram Bot (src/bot.js)
262
+ ↓
263
+ OrchestratorAgent (src/agent.js) — Claude Opus, 3 core tools
264
+ ↓ dispatch_task / list_jobs / cancel_job
265
+ JobManager (src/swarm/job-manager.js) — queued → running → completed/failed/cancelled
266
+ ↓
267
+ WorkerAgent (src/worker.js) — scoped tools, user's chosen brain, background execution
316
268
  ```
317
269
 
318
- If credentials are missing when a JIRA tool is called, KernelBot will prompt for them via Telegram.
270
+ The orchestrator always runs on Anthropic (Claude Opus). Workers run on whatever provider/model the user selects. Each worker type gets a scoped subset of the 40+ tools.
271
+
272
+ ### Tool Categories
319
273
 
320
- ## Project Structure
274
+ | Category | Tools |
275
+ | --- | --- |
276
+ | **File System & Shell** | `execute_command`, `read_file`, `write_file`, `list_directory` |
277
+ | **Git** | `git_clone`, `git_checkout`, `git_commit`, `git_push`, `git_diff` |
278
+ | **GitHub** | `github_create_pr`, `github_get_pr_diff`, `github_post_review`, `github_create_repo`, `github_list_prs` |
279
+ | **Browser** | `web_search`, `browse_website`, `screenshot_website`, `extract_content`, `interact_with_page`, `send_image` |
280
+ | **JIRA** | `jira_get_ticket`, `jira_search_tickets`, `jira_list_my_tickets`, `jira_get_project_tickets` |
281
+ | **Docker** | `docker_ps`, `docker_logs`, `docker_exec`, `docker_compose` |
282
+ | **Process** | `process_list`, `kill_process`, `service_control` |
283
+ | **Monitoring** | `disk_usage`, `memory_usage`, `cpu_usage`, `system_logs` |
284
+ | **Networking** | `check_port`, `curl_url`, `nginx_reload` |
285
+ | **Coding** | `spawn_claude_code` |
286
+
287
+ ### Project Structure
321
288
 
322
289
  ```text
323
290
  KernelBot/
324
291
  ├── bin/
325
- │ └── kernel.js # Entry point + CLI menu
292
+ │ └── kernel.js # CLI entry point + interactive menu
326
293
  ├── src/
327
- │ ├── agent.js # OrchestratorAgent — swarm brain, job lifecycle, worker spawning
328
- │ ├── worker.js # WorkerAgent — scoped agent loop, cancellation, circuit breaker
329
- │ ├── bot.js # Telegram bot (polling, auth, commands, batching)
330
- │ ├── coder.js # Claude Code CLI spawner + smart output
331
- │ ├── conversation.js # Per-chat conversation history + summarization
332
- │ ├── persona.js # UserPersonaManager — auto-learning user profiles
333
- │ ├── intents/
334
- │ │ ├── detector.js # Web search/browse intent detection
335
- │ │ └── planner.js # Execution plan generation for intents
336
- │ ├── prompts/
337
- │ │ ├── orchestrator.js # Orchestrator system prompt
338
- │ │ ├── workers.js # Per-worker-type system prompts
339
- │ │ └── system.js # Core tool instructions
340
- │ ├── providers/
294
+ │ ├── bot.js # Telegram bot — polling, commands, batching, voice
295
+ │ ├── agent.js # OrchestratorAgent — swarm brain, job lifecycle
296
+ │ ├── worker.js # WorkerAgent — scoped agent loop, cancellation
297
+ │ ├── self.js # SelfManager — bot identity (goals, journey, life, hobbies)
298
+ │ ├── conversation.js # Per-chat history + summarization
299
+ │ ├── persona.js # UserPersonaManager — auto-learns user profiles
300
+ │ ├── coder.js # Claude Code CLI spawner
301
+ │ ├── claude-auth.js # Claude Code authentication helpers
302
+ │ │
303
+ │ ├── automation/ # Recurring task automations
304
+ │ │ ├── scheduler.js # Timer scheduling
305
+ │ │ ├── automation.js # Automation class
306
+ │ │ └── automation-manager.js # CRUD + execution
307
+ │ │
308
+ │ ├── life/ # Autonomous living AI system
309
+ │ │ ├── engine.js # Heartbeat loop — think, journal, browse, create, reflect
310
+ │ │ ├── memory.js # Episodic (daily JSON) + semantic (topics) memory
311
+ │ │ ├── journal.js # Daily markdown journals
312
+ │ │ ├── share-queue.js # Pending discoveries to share with users
313
+ │ │ ├── evolution.js # Self-improvement proposal lifecycle
314
+ │ │ └── codebase.js # LLM-powered codebase knowledge
315
+ │ │
316
+ │ ├── providers/ # Multi-model abstraction
317
+ │ │ ├── base.js # BaseProvider interface
318
+ │ │ ├── anthropic.js # Anthropic (Claude)
319
+ │ │ ├── openai-compat.js # OpenAI / Groq (OpenAI-compatible API)
320
+ │ │ ├── google-genai.js # Google Gemini (native SDK)
341
321
  │ │ ├── models.js # Provider & model catalog
342
- │ │ ├── base.js # Abstract provider interface
343
- │ │ ├── anthropic.js # Anthropic (Claude) provider
344
- │ │ ├── openai-compat.js # OpenAI / Gemini / Groq provider
345
322
  │ │ └── index.js # Provider factory
346
- │ ├── security/
347
- │ │ ├── auth.js # User allowlist
348
- │ │ ├── audit.js # Tool call audit logging
349
- │ │ └── confirm.js # Dangerous operation detection
350
- │ ├── skills/
351
- │ │ ├── catalog.js # 35+ built-in persona skills
352
- │ │ └── custom.js # Custom skill CRUD + unified lookups
353
- │ ├── swarm/
354
- │ │ ├── job.js # Job class (state machine, transitions, summary)
355
- │ │ ├── job-manager.js # JobManager (EventEmitter, CRUD, cleanup, timeouts)
356
- │ │ └── worker-registry.js # Worker type → tool category mapping
357
- │ ├── tools/
358
- │ │ ├── categories.js # Tool category definitions + keyword matching
323
+ │ │
324
+ │ ├── swarm/ # Job orchestration
325
+ │ │ ├── job.js # Job state machine
326
+ │ │ ├── job-manager.js # Job lifecycle, timeouts, cleanup
327
+ │ │ └── worker-registry.js # Worker type → tool scope mapping
328
+ │ │
329
+ │ ├── tools/ # 40+ tools
330
+ │ │ ├── index.js # Tool registry + dispatcher
359
331
  │ │ ├── orchestrator-tools.js # dispatch_task, list_jobs, cancel_job
360
- │ │ ├── os.js # File system + shell tools
332
+ │ │ ├── os.js # File system + shell
361
333
  │ │ ├── git.js # Git operations
362
- │ │ ├── github.js # GitHub API (PRs, repos, reviews)
334
+ │ │ ├── github.js # GitHub API
363
335
  │ │ ├── browser.js # Web browsing + search (Puppeteer)
364
336
  │ │ ├── docker.js # Docker management
365
337
  │ │ ├── process.js # Process management
366
- │ │ ├── monitor.js # System monitoring (CPU, RAM, disk)
367
- │ │ ├── network.js # Network tools (HTTP, ports, nginx)
338
+ │ │ ├── monitor.js # System monitoring
339
+ │ │ ├── network.js # Network tools
368
340
  │ │ ├── coding.js # Claude Code CLI handler
369
- │ │ ├── jira.js # JIRA ticket reading + search
370
- │ │ ├── persona.js # User persona update tool
371
- │ │ └── index.js # Tool registry + dispatcher
341
+ │ │ ├── jira.js # JIRA integration
342
+ │ │ └── categories.js # Tool category definitions
343
+ │ │
344
+ │ ├── prompts/ # System prompts
345
+ │ │ ├── orchestrator.js # Orchestrator prompt
346
+ │ │ ├── workers.js # Per-worker-type prompts
347
+ │ │ └── system.js # Shared prompt utilities
348
+ │ │
349
+ │ ├── skills/ # Persona skills
350
+ │ │ ├── catalog.js # 35+ built-in skills
351
+ │ │ └── custom.js # Custom skill management
352
+ │ │
353
+ │ ├── security/ # Auth, audit, confirmations
354
+ │ │ ├── auth.js # User allowlist
355
+ │ │ ├── audit.js # Tool call audit logging
356
+ │ │ └── confirm.js # Dangerous operation detection
357
+ │ │
358
+ │ ├── services/ # External service integrations
359
+ │ │ ├── tts.js # ElevenLabs text-to-speech
360
+ │ │ └── stt.js # Speech-to-text (ElevenLabs + Whisper)
361
+ │ │
372
362
  │ └── utils/
373
- │ ├── config.js # Config loading (auto-detect + prompt)
374
- │ ├── display.js # CLI display (logo, spinners, banners)
375
- │ └── logger.js # Winston logger
376
- ├── config.example.yaml
377
- ├── .env.example
378
- └── package.json
363
+ │ ├── config.js # Config loading + interactive setup
364
+ │ ├── logger.js # Winston logger
365
+ │ ├── display.js # CLI display helpers
366
+ │ ├── shell.js # Shell escaping
367
+ │ └── truncate.js # Tool result truncation
368
+ │
369
+ ├── package.json
370
+ └── config.yaml
379
371
  ```
380
372
 
381
- ## Requirements
373
+ ### Data Storage
382
374
 
383
- - Node.js 18+
384
- - [Anthropic API key](https://console.anthropic.com/) — always required (orchestrator runs on Claude)
385
- - [Telegram Bot Token](https://t.me/BotFather)
386
- - Chromium/Chrome (for browser tools — installed automatically by Puppeteer)
387
- - Worker brain API key (optional if using Anthropic for workers too):
388
- - [OpenAI API key](https://platform.openai.com/api-keys) (GPT)
389
- - [Google AI API key](https://aistudio.google.com/apikey) (Gemini)
390
- - [Groq API key](https://console.groq.com/keys) (Llama/Mixtral)
391
- - [GitHub Token](https://github.com/settings/tokens) (optional, for GitHub tools)
392
- - [JIRA API Token](https://id.atlassian.net/manage-profile/security/api-tokens) (optional, for JIRA integration)
393
- - [Claude Code CLI](https://www.npmjs.com/package/@anthropic-ai/claude-code) (optional, for coding tasks)
375
+ All persistent data lives in `~/.kernelbot/`:
376
+
377
+ | Path | Purpose |
378
+ | --- | --- |
379
+ | `.env` | API keys and tokens |
380
+ | `config.yaml` | User configuration |
381
+ | `personas/{userId}.md` | Learned user profiles |
382
+ | `self/` | Bot identity files (goals, journey, life, hobbies) |
383
+ | `skills/` | Custom user-created skills |
384
+ | `life/episodic/` | Daily episodic memory files |
385
+ | `life/topics.json` | Semantic memory |
386
+ | `life/journals/` | Daily journal entries |
387
+ | `life/evolution.json` | Self-improvement proposals |
388
+ | `life/codebase/` | Codebase knowledge (summaries, architecture) |
389
+ | `automations.json` | Saved automations |
390
+ | `tts-cache/` | Cached voice audio |
391
+
392
+ ### JIRA Setup
393
+
394
+ Supports both Atlassian Cloud and self-hosted JIRA Server.
395
+
396
+ 1. Generate an API token at [id.atlassian.net](https://id.atlassian.net/manage-profile/security/api-tokens) (Cloud) or use a personal access token (Server).
397
+ 2. Set `JIRA_BASE_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN` in your environment or `config.yaml`.
398
+ 3. If credentials are missing when a JIRA tool is called, KernelBot will prompt you in Telegram.
394
399
 
395
400
  ## License
396
401