Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (kernelbot) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

KernelBot

AI engineering agent — a Telegram bot backed by Claude Sonnet with full OS control via tool use.

Send a message in Telegram, and KernelBot will read files, write code, run commands, and respond with the results. It's your personal engineering assistant with direct access to your machine.

How It Works

You (Telegram) → KernelBot → Claude Sonnet (Anthropic API)
                                    ↕
                              OS Tools (shell, files, directories)

KernelBot runs a tool-use loop: Claude decides which tools to call, KernelBot executes them on your OS, feeds results back, and Claude continues until the task is done. One message can trigger dozens of tool calls autonomously.

Tools

Tool	Description
`execute_command`	Run any shell command (git, npm, python, etc.)
`read_file`	Read file contents with optional line limits
`write_file`	Write/create files, auto-creates parent directories
`list_directory`	List directory contents, optionally recursive

Installation

npm install -g kernelbot

This installs the kernelbot command globally.

Quick Start

# Interactive setup — creates .env and config.yaml
kernelbot init

# Verify everything works
kernelbot check

# Launch the bot
kernelbot start

Commands

Command	Description
`kernelbot start`	Start the Telegram bot
`kernelbot run "prompt"`	One-off agent call without Telegram (for testing/scripts)
`kernelbot check`	Validate config and test API connections
`kernelbot init`	Interactive setup wizard

Configuration

KernelBot looks for config.yaml in the current directory or ~/.kernelbot/. Secrets are loaded from .env.

`.env`

ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

`config.yaml`

bot:
  name: KernelBot

anthropic:
  model: claude-sonnet-4-20250514
  max_tokens: 8192
  temperature: 0.3
  max_tool_depth: 25 # max tool calls per message

telegram:
  allowed_users: [] # empty = allow all (dev mode)
  # allowed_users: [123456789]  # lock to specific Telegram user IDs

security:
  blocked_paths: # paths the agent cannot touch
    - /etc/shadow
    - /etc/passwd

logging:
  level: info
  max_file_size: 5242880 # 5 MB

conversation:
  max_history: 50 # messages per chat

Security

User allowlist — restrict bot access to specific Telegram user IDs. Empty list = dev mode (anyone can use it).
Blocked paths — files/directories the agent is forbidden from reading or writing (e.g., /etc/shadow, SSH keys).
Audit logging — every tool call is logged to kernel-audit.log with user, tool, params, result, and duration. Secrets in params are automatically redacted.
Command timeout — shell commands are killed after 30 seconds by default.

Project Structure

KernelBot/
├── bin/
│   └── kernel.js           # CLI entry point
├── src/
│   ├── agent.js            # Sonnet tool-use loop
│   ├── bot.js              # Telegram bot (polling, auth, message handling)
│   ├── conversation.js     # Per-chat conversation history
│   ├── prompts/
│   │   └── system.js       # System prompt
│   ├── security/
│   │   ├── auth.js         # User allowlist
│   │   └── audit.js        # Tool call audit logging
│   ├── tools/
│   │   ├── os.js           # OS tool definitions + handlers
│   │   └── index.js        # Tool registry + dispatcher
│   └── utils/
│       ├── config.js       # Config loading (yaml + env + defaults)
│       ├── display.js      # CLI display (logo, spinners, banners)
│       └── logger.js       # Winston logger
├── config.example.yaml
├── .env.example
└── package.json

Requirements

Author

Abdullah Al-Tahrei