mono/packages/kbot

@plastichub/kbot

AI-powered command-line tool for code modifications and project management that supports multiple AI models and routers.

Overview

Code-bot is a powerful CLI tool that helps developers automate code modifications, handle project management tasks, and integrate with various AI models for intelligent code and content assistance.

Quick Start

Installation Steps

KBot requires Node.js to run. It's recommended to use Node.js version 18 or higher.

1. Visit the official Node.js website
2. Download the LTS (Long Term Support) version for your operating system
3. Follow the installation wizard
4. Verify installation by opening a terminal and running:

   node --version
   npm --version
   

API Keys

KBot supports both OpenRouter and OpenAI APIs. You'll need at least one of these set up.

OpenRouter API (Recommended)

1. Visit OpenRouter
2. Sign up for an account
3. Navigate to the API Keys section
4. Create a new API key

OpenAI API (Optional)

1. Go to OpenAI's platform
2. Create an account or sign in
3. Navigate to API keys section
4. Create a new secret key

Installation using Node NPM package manager

npm install -g @plastichub/kbot

Configuration

API Keys Setup

Create configuration at $HOME/.osr/.config.json (or export OSR_CONFIG with path to config.json):

{
  "openrouter": {
    "key": "your-openrouter-key"
  },
  "openai": {
    "key": "your-openai-key"
  },
   "email": {
      "newsletter": {
          "host": "host.org",
          "port": 465,
          "debug": true,
          "transactionLog": true,
          "auth": {
              "user": "foo@bar.com",
              "pass": "pass"
          }
      }
  },
  "google": {
      "cse": "custom search engine id",
      "api_key": "google custom search api key"
  },
  "serpapi": {
      "key": "your SerpAPI key (optional, used for web searches(places, google maps))"
  },
  "deepseek": {
      "key": "your SerpAPI key (optional, used for web searches(places, google maps))"
  },
}

Preferences Setup

Optionally, create .kbot/preferences.md in your project directory to customize AI interactions:

## My Preferences

Gender : male
Location : New York, USA (eg: `send me all saunas next to me`)
Language : English
Occupation : software developer, Typescript
Age : 30+

## Contacts

My email address : example@email.com (eg: `send me latest hacker news`)
My wife's email address ("Anne") : example@email.com (eg: `send email to my wife, with latest local news')

## Content

When creating content
- always Markdown
- always add links
- when sending emails, always add 'Best regards, [Your Name]'

Commands

Prompt

kbot "create Astro minimal boilerplate, use starlight theme. Install dependencies via NPM tool"

Fetch latest models

kbot fetch

Print examples

kbot examples

Print extended help

kbot help-md

Initialize folder

kbot init

Command Line Parameters

This document describes all available command line parameters.

Core Parameters

Parameter	Description	Default	Required
path	Target directory	.	No
prompt	The prompt. Supports file paths and environment variables	./prompt.md	No
output	Optional output path for modified files (Tool mode only)	-	No
dst	Optional destination path for the result, will substitute ${MODEL} and ${ROUTER} in the path.	-	No
model	AI model to use for processing	anthropic/claude-3.5-sonnet	No
router	Router to use: openai or openrouter	openrouter	No
mode	Chat completion mode: "completion" (without tools) or "tools"	tools	No

Advanced Parameters

Parameter	Description	Default	Required
each	Target directory	.	No
dry	Dry run - only write out parameters without making API calls	false	No

File Selection & Tools

Parameter	Description	Default	Required
include	Glob patterns to match files for processing. Supports multiple patterns, e.g. --include=src/*.tsx,src/*.ts --include=package.json	-	No
disable	Disable tools categories	[]	No
disableTools	List of specific tools to disable	[]	No

Configuration & Profiles

Parameter	Description	Default	Required
profile	Path to profile for variables. Supports environment variables	${POLYMECH-ROOT}/profile.json	No
env	Environment (in profile)	default	No
config	Path to JSON configuration file (API keys). Supports environment variables	-	No
preferences	Path to preferences file (location, email, gender, etc). Supports environment variables	./.kbot/preferences.md	No

Debugging & Logging

Parameter	Description	Default	Required
logLevel	Logging level for the application (0-4)	2	No
logs	Logging directory	./.kbot	No
dump	Create a script	-	No

Working on Larger Directories

Since LLMs (Large Language Models) and providers are limited to very small 'context windows', it's necessary to feed them with smaller chunks instead. This document explains how to process larger directories efficiently.

Directory Processing Example

Here's an example of how to walk through files and process them:

osr-cli each --main='kbot \"read ${KEY} and translate to german, save in docs/language code/filename.md\" --include=\"${REL}\" --include=\".kbot/preferences.md\"' --list="./docs/*.md" --cwd=.

Parameter Explanation

• each: Command to process multiple files iteratively
• --main: The main command (kbot) to execute for each file
  • --include=\"${REL}\" instructs kbot to include the current selected path
  • --include=\".kbot/preferences.md\" instructs kbot to include additional preferences about the task (eg: translation specifics)
• --list: Specifies the file pattern to match
  • Supports include patterns (e.g., "./docs/*.md")
• --cwd: Sets the current working directory for the command execution. Default is the current directory (.)

Note requires @plastichub/osr-cli-commons to be installed globally:

npm i -g @plastichub/osr-cli-commons