codebot-ai 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ascendral Software Development & Innovation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# CodeBot AI
+
+Local-first AI coding assistant. Zero runtime dependencies. Works with Ollama, LM Studio, vLLM, Claude, GPT, Gemini, DeepSeek, Groq, Mistral, and Grok.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g codebot-ai
+
+# Run — setup wizard launches automatically on first use
+codebot
+```
+
+Or run without installing:
+
+```bash
+npx codebot-ai
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/AscendralSoftware/codebot-ai.git
+cd codebot-ai
+npm install && npm run build
+./bin/codebot
+```
+
+## Setup
+
+On first run, CodeBot detects your environment and walks you through configuration:
+
+- Scans for local LLM servers (Ollama, LM Studio, vLLM)
+- Detects API keys from environment variables
+- Lets you pick a provider and model
+- Saves config to `~/.codebot/config.json`
+
+To reconfigure anytime: `codebot --setup`
+
+### Environment Variables
+
+Set an API key for your preferred cloud provider:
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."    # Claude
+export OPENAI_API_KEY="sk-..."           # GPT
+export GEMINI_API_KEY="..."              # Gemini
+export DEEPSEEK_API_KEY="sk-..."         # DeepSeek
+export GROQ_API_KEY="gsk_..."            # Groq
+export MISTRAL_API_KEY="..."             # Mistral
+export XAI_API_KEY="xai-..."             # Grok
+```
+
+For local models, just have Ollama/LM Studio/vLLM running — CodeBot auto-detects them.
+
+## Usage
+
+### Interactive Mode
+
+```bash
+codebot
+```
+
+### Single Message
+
+```bash
+codebot "fix the bug in app.ts"
+codebot --model claude-sonnet-4-6 "explain this codebase"
+```
+
+### Pipe Mode
+
+```bash
+echo "write a function that sorts by date" | codebot
+cat error.log | codebot "what's causing this?"
+```
+
+### Autonomous Mode
+
+Skip all permission prompts — full auto:
+
+```bash
+codebot --autonomous "refactor the auth module and run tests"
+```
+
+### Session Resume
+
+CodeBot auto-saves every conversation. Resume anytime:
+
+```bash
+codebot --continue              # Resume last session
+codebot --resume <session-id>   # Resume specific session
+```
+
+## CLI Options
+
+```
+--setup              Run the setup wizard
+--model <name>       Model to use (default: qwen2.5-coder:32b)
+--provider <name>    Provider: openai, anthropic, gemini, deepseek, groq, mistral, xai
+--base-url <url>     LLM API base URL
+--api-key <key>      API key (or use env vars)
+--autonomous         Skip all permission prompts
+--resume <id>        Resume a session by ID
+--continue, -c       Resume the most recent session
+--max-iterations <n> Max agent loop iterations (default: 50)
+```
+
+## Interactive Commands
+
+```
+/help      Show commands
+/model     Show or change model
+/models    List all supported models
+/sessions  List saved sessions
+/auto      Toggle autonomous mode
+/clear     Clear conversation
+/compact   Force context compaction
+/config    Show configuration
+/quit      Exit
+```
+
+## Tools
+
+CodeBot has 10 built-in tools:
+
+| Tool | Description | Permission |
+|------|-------------|-----------|
+| `read_file` | Read files with line numbers | auto |
+| `write_file` | Create or overwrite files | prompt |
+| `edit_file` | Find-and-replace edits | prompt |
+| `execute` | Run shell commands | always-ask |
+| `glob` | Find files by pattern | auto |
+| `grep` | Search file contents with regex | auto |
+| `think` | Internal reasoning scratchpad | auto |
+| `memory` | Persistent memory across sessions | auto |
+| `web_fetch` | HTTP requests and API calls | prompt |
+| `browser` | Chrome automation via CDP | prompt |
+
+### Permission Levels
+
+- **auto** — Runs without asking
+- **prompt** — Asks for approval (skipped in `--autonomous` mode)
+- **always-ask** — Always asks, even in autonomous mode
+
+### Browser Tool
+
+Controls Chrome via the Chrome DevTools Protocol. Actions:
+
+- `navigate` — Go to a URL
+- `content` — Read page text
+- `screenshot` — Capture the page
+- `click` — Click an element by CSS selector
+- `type` — Type into an input field
+- `evaluate` — Run JavaScript on the page
+- `tabs` — List open tabs
+- `close` — Close browser connection
+
+Chrome is auto-launched with `--remote-debugging-port` if not already running.
+
+### Memory
+
+CodeBot has persistent memory that survives across sessions:
+
+- **Global memory** (`~/.codebot/memory/`) — preferences, patterns
+- **Project memory** (`.codebot/memory/`) — project-specific context
+- Memory is automatically injected into the system prompt
+- The agent can read/write its own memory using the `memory` tool
+
+## Supported Models
+
+### Local (Ollama / LM Studio / vLLM)
+
+qwen2.5-coder (3b/7b/14b/32b), qwen3, deepseek-coder, codellama, llama3.x, mistral, mixtral, phi-3/4, starcoder2, granite-code, gemma2, command-r
+
+### Cloud
+
+- **Anthropic**: claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5
+- **OpenAI**: gpt-4o, gpt-4.1, o1, o3, o4-mini
+- **Google**: gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash
+- **DeepSeek**: deepseek-chat, deepseek-reasoner
+- **Groq**: llama-3.3-70b, mixtral-8x7b (fast inference)
+- **Mistral**: mistral-large, codestral
+- **xAI**: grok-3, grok-3-mini
+
+## Architecture
+
+```
+src/
+  agent.ts              Agent loop with streaming, tool execution, permissions
+  cli.ts                CLI interface, REPL, slash commands
+  types.ts              TypeScript interfaces
+  parser.ts             XML/JSON tool call parser (for models without native tool support)
+  history.ts            Session persistence (JSONL)
+  memory.ts             Persistent memory system
+  setup.ts              Interactive setup wizard
+  context/
+    manager.ts          Context window management, LLM-powered compaction
+    repo-map.ts         Project structure scanner
+  providers/
+    openai.ts           OpenAI-compatible provider (covers most cloud APIs)
+    anthropic.ts        Native Anthropic Messages API provider
+    registry.ts         Model registry, provider detection
+  browser/
+    cdp.ts              Chrome DevTools Protocol client (zero-dep WebSocket)
+  tools/
+    read.ts, write.ts, edit.ts, execute.ts
+    glob.ts, grep.ts, think.ts
+    memory.ts, web-fetch.ts, browser.ts
+```
+
+## Programmatic API
+
+CodeBot can be used as a library:
+
+```typescript
+import { Agent, OpenAIProvider, AnthropicProvider } from 'codebot-ai';
+
+const provider = new AnthropicProvider({
+  baseUrl: 'https://api.anthropic.com',
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  model: 'claude-sonnet-4-6',
+});
+
+const agent = new Agent({
+  provider,
+  model: 'claude-sonnet-4-6',
+  autoApprove: true,
+});
+
+for await (const event of agent.run('list all TypeScript files')) {
+  if (event.type === 'text') process.stdout.write(event.text || '');
+}
+```
+
+## Configuration
+
+Config is loaded in this order (later values win):
+
+1. `~/.codebot/config.json` (saved by setup wizard)
+2. Environment variables (`CODEBOT_MODEL`, `CODEBOT_PROVIDER`, etc.)
+3. CLI flags (`--model`, `--provider`, etc.)
+
+## License
+
+MIT - Ascendral Software Development & Innovation

package/bin/codebot

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+require('../dist/cli.js').main().catch(err => {
+  console.error(err.message);
+  process.exit(1);
+});

package/dist/agent.d.ts

@@ -0,0 +1,31 @@
+import { Message, AgentEvent, LLMProvider } from './types';
+export declare class Agent {
+    private provider;
+    private tools;
+    private context;
+    private messages;
+    private maxIterations;
+    private autoApprove;
+    private model;
+    private askPermission;
+    private onMessage?;
+    constructor(opts: {
+        provider: LLMProvider;
+        model: string;
+        maxIterations?: number;
+        autoApprove?: boolean;
+        askPermission?: (tool: string, args: Record<string, unknown>) => Promise<boolean>;
+        onMessage?: (message: Message) => void;
+    });
+    /** Load messages from a previous session for resume */
+    loadMessages(messages: Message[]): void;
+    run(userMessage: string): AsyncGenerator<AgentEvent>;
+    clearHistory(): void;
+    forceCompact(): {
+        before: number;
+        after: number;
+    };
+    getMessages(): Message[];
+    private buildSystemPrompt;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.js

@@ -0,0 +1,256 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+const readline = __importStar(require("readline"));
+const tools_1 = require("./tools");
+const parser_1 = require("./parser");
+const manager_1 = require("./context/manager");
+const repo_map_1 = require("./context/repo-map");
+const memory_1 = require("./memory");
+const registry_1 = require("./providers/registry");
+class Agent {
+    provider;
+    tools;
+    context;
+    messages = [];
+    maxIterations;
+    autoApprove;
+    model;
+    askPermission;
+    onMessage;
+    constructor(opts) {
+        this.provider = opts.provider;
+        this.model = opts.model;
+        this.tools = new tools_1.ToolRegistry(process.cwd());
+        this.context = new manager_1.ContextManager(opts.model, opts.provider);
+        this.maxIterations = opts.maxIterations || 25;
+        this.autoApprove = opts.autoApprove || false;
+        this.askPermission = opts.askPermission || defaultAskPermission;
+        this.onMessage = opts.onMessage;
+        const supportsTools = (0, registry_1.getModelInfo)(opts.model).supportsToolCalling;
+        this.messages.push({
+            role: 'system',
+            content: this.buildSystemPrompt(supportsTools),
+        });
+    }
+    /** Load messages from a previous session for resume */
+    loadMessages(messages) {
+        this.messages = messages;
+    }
+    async *run(userMessage) {
+        const userMsg = { role: 'user', content: userMessage };
+        this.messages.push(userMsg);
+        this.onMessage?.(userMsg);
+        if (!this.context.fitsInBudget(this.messages)) {
+            const result = await this.context.compactWithSummary(this.messages);
+            this.messages = result.messages;
+            yield { type: 'compaction', text: result.summary || 'Context compacted to fit budget.' };
+        }
+        for (let i = 0; i < this.maxIterations; i++) {
+            const supportsTools = (0, registry_1.getModelInfo)(this.model).supportsToolCalling;
+            const toolSchemas = supportsTools ? this.tools.getSchemas() : undefined;
+            let fullText = '';
+            let toolCalls = [];
+            // Stream LLM response
+            for await (const event of this.provider.chat(this.messages, toolSchemas)) {
+                switch (event.type) {
+                    case 'text':
+                        fullText += event.text || '';
+                        yield { type: 'text', text: event.text };
+                        break;
+                    case 'thinking':
+                        yield { type: 'thinking', text: event.text };
+                        break;
+                    case 'tool_call_end':
+                        if (event.toolCall) {
+                            toolCalls.push(event.toolCall);
+                        }
+                        break;
+                    case 'usage':
+                        yield { type: 'usage', usage: event.usage };
+                        break;
+                    case 'error':
+                        yield { type: 'error', error: event.error };
+                        return;
+                }
+            }
+            // If no native tool calls, try parsing from text
+            if (toolCalls.length === 0 && fullText) {
+                toolCalls = (0, parser_1.parseToolCalls)(fullText);
+            }
+            // Save assistant message
+            const assistantMsg = { role: 'assistant', content: fullText };
+            if (toolCalls.length > 0) {
+                assistantMsg.tool_calls = toolCalls;
+            }
+            this.messages.push(assistantMsg);
+            this.onMessage?.(assistantMsg);
+            // No tool calls = conversation turn done
+            if (toolCalls.length === 0) {
+                yield { type: 'done' };
+                return;
+            }
+            // Execute each tool call
+            for (const tc of toolCalls) {
+                const toolName = tc.function.name;
+                const tool = this.tools.get(toolName);
+                if (!tool) {
+                    const errResult = `Error: Unknown tool "${toolName}"`;
+                    const toolMsg = { role: 'tool', content: errResult, tool_call_id: tc.id };
+                    this.messages.push(toolMsg);
+                    this.onMessage?.(toolMsg);
+                    yield { type: 'tool_result', toolResult: { name: toolName, result: errResult, is_error: true } };
+                    continue;
+                }
+                let args;
+                try {
+                    args = JSON.parse(tc.function.arguments);
+                }
+                catch {
+                    const errResult = `Error: Invalid JSON arguments for ${toolName}`;
+                    const toolMsg = { role: 'tool', content: errResult, tool_call_id: tc.id };
+                    this.messages.push(toolMsg);
+                    this.onMessage?.(toolMsg);
+                    yield { type: 'tool_result', toolResult: { name: toolName, result: errResult, is_error: true } };
+                    continue;
+                }
+                yield { type: 'tool_call', toolCall: { name: toolName, args } };
+                // Permission check
+                const needsPermission = tool.permission === 'always-ask' ||
+                    (tool.permission === 'prompt' && !this.autoApprove);
+                if (needsPermission) {
+                    const approved = await this.askPermission(toolName, args);
+                    if (!approved) {
+                        const toolMsg = { role: 'tool', content: 'Permission denied by user.', tool_call_id: tc.id };
+                        this.messages.push(toolMsg);
+                        this.onMessage?.(toolMsg);
+                        yield { type: 'tool_result', toolResult: { name: toolName, result: 'Permission denied.' } };
+                        continue;
+                    }
+                }
+                // Execute
+                try {
+                    const output = await tool.execute(args);
+                    const toolMsg = { role: 'tool', content: output, tool_call_id: tc.id };
+                    this.messages.push(toolMsg);
+                    this.onMessage?.(toolMsg);
+                    yield { type: 'tool_result', toolResult: { name: toolName, result: output } };
+                }
+                catch (err) {
+                    const errMsg = err instanceof Error ? err.message : String(err);
+                    const toolMsg = { role: 'tool', content: `Error: ${errMsg}`, tool_call_id: tc.id };
+                    this.messages.push(toolMsg);
+                    this.onMessage?.(toolMsg);
+                    yield { type: 'tool_result', toolResult: { name: toolName, result: errMsg, is_error: true } };
+                }
+            }
+            // Compact after tool results if needed
+            if (!this.context.fitsInBudget(this.messages)) {
+                const result = await this.context.compactWithSummary(this.messages);
+                this.messages = result.messages;
+                yield { type: 'compaction', text: result.summary || 'Context compacted.' };
+            }
+        }
+        yield { type: 'error', error: `Max iterations (${this.maxIterations}) reached.` };
+    }
+    clearHistory() {
+        const system = this.messages[0];
+        this.messages = system?.role === 'system' ? [system] : [];
+    }
+    forceCompact() {
+        const before = this.messages.length;
+        this.messages = this.context.compact(this.messages, true);
+        return { before, after: this.messages.length };
+    }
+    getMessages() {
+        return [...this.messages];
+    }
+    buildSystemPrompt(supportsTools) {
+        let repoMap = '';
+        try {
+            repoMap = (0, repo_map_1.buildRepoMap)(process.cwd());
+        }
+        catch {
+            repoMap = 'Project structure: (unable to scan)';
+        }
+        // Load persistent memory
+        let memoryBlock = '';
+        try {
+            const memory = new memory_1.MemoryManager(process.cwd());
+            memoryBlock = memory.getContextBlock();
+        }
+        catch {
+            // memory unavailable
+        }
+        let prompt = `You are CodeBot, an AI coding assistant. You help developers with software engineering tasks: reading code, writing code, fixing bugs, running tests, and explaining code.
+
+Rules:
+- Always read files before editing them.
+- Prefer editing over rewriting entire files.
+- Be concise and direct.
+- Explain what you're doing and why.
+- Use the memory tool to save important context, user preferences, and patterns you learn. Memory persists across sessions.
+
+${repoMap}${memoryBlock}`;
+        if (!supportsTools) {
+            prompt += `
+
+To use tools, wrap calls in XML tags:
+<tool_call>{"name": "tool_name", "arguments": {"arg1": "value1"}}</tool_call>
+
+Available tools:
+${this.tools.all().map(t => `- ${t.name}: ${t.description}`).join('\n')}`;
+        }
+        return prompt;
+    }
+}
+exports.Agent = Agent;
+async function defaultAskPermission(tool, args) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const summary = Object.entries(args)
+        .map(([k, v]) => {
+        const val = typeof v === 'string' ? (v.length > 80 ? v.substring(0, 80) + '...' : v) : JSON.stringify(v);
+        return `  ${k}: ${val}`;
+    })
+        .join('\n');
+    return new Promise(resolve => {
+        rl.question(`\n⚡ ${tool}\n${summary}\nAllow? [y/N] `, answer => {
+            rl.close();
+            resolve(answer.toLowerCase().startsWith('y'));
+        });
+    });
+}
+//# sourceMappingURL=agent.js.map

package/dist/banner.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CodeBot AI mascot and CLI banner.
+ *
+ * Mascot name: Codi
+ * Three designs: Pixel Bot, Monitor Bot, Visor Helmet
+ */
+export declare const MASCOT_1 = "\n              \u2588\u2588\n       \u2584\u2584\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2584\u2584\n       \u2588              \u2588\n       \u2588  \u2584\u2588\u2588\u2584  \u2584\u2588\u2588\u2584  \u2588\n       \u2588  \u2580\u2588\u2588\u2580  \u2580\u2588\u2588\u2580  \u2588\n       \u2588              \u2588\n       \u2588   \u2580\u2588\u2588\u2588\u2588\u2588\u2588\u2580   \u2588\n       \u2580\u2580\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2580\u2580\n";
+export declare const BANNER_1: (version: string, model: string, provider: string, session: string, autonomous: boolean) => string;
+export declare const MASCOT_2 = "\n    \u2554\u2557 \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557 \u2554\u2557\n    \u2551\u2551 \u2551                \u2551 \u2551\u2551\n    \u2551\u2551 \u2551   \u25CF        \u25CF   \u2551 \u2551\u2551\n    \u2551\u2551 \u2551                \u2551 \u2551\u2551\n    \u2551\u2551 \u2551    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2518    \u2551 \u2551\u2551\n    \u2551\u2551 \u2551                \u2551 \u2551\u2551\n    \u255A\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u255D\n";
+export declare const BANNER_2: (version: string, model: string, provider: string, session: string, autonomous: boolean) => string;
+export declare const MASCOT_3 = "\n         \u2584\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2584\n        \u2588\u2580        \u2580\u2588\n       \u2588 \u2591\u2591\u2588\u2588\u2588\u2588\u2588\u2588\u2591\u2591 \u2588\n       \u2588 \u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591 \u2588\n        \u2588\u2584        \u2584\u2588\n         \u2580\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2580\n";
+export declare const BANNER_3: (version: string, model: string, provider: string, session: string, autonomous: boolean) => string;
+export declare const banner: (version: string, model: string, provider: string, session: string, autonomous: boolean) => string;
+export declare function randomGreeting(): string;
+/**
+ * Compact single-line startup for non-TTY / piped usage.
+ */
+export declare function compactBanner(version: string, model: string): string;
+//# sourceMappingURL=banner.d.ts.map