{"_id":"@biznetgio/kalicode-cli","_rev":"2-7d6dfa1cc779b926ce886e54c1092645","name":"@biznetgio/kalicode-cli","dist-tags":{"latest":"0.3.3"},"versions":{"0.3.3":{"name":"@biznetgio/kalicode-cli","version":"0.3.3","keywords":["cli","agent","text-editor","kalicode","ai"],"author":{"name":"anak10thn","email":"anak10thn@gmail.com"},"license":"MIT","_id":"@biznetgio/kalicode-cli@0.3.3","maintainers":[{"name":"anak10thn","email":"anak10thn@gmail.com"}],"bin":{"kalicode":"dist/index.js"},"dist":{"shasum":"901afb9439381497b231286356c976e2d07ceb12","tarball":"https://registry.npmjs.org/@biznetgio/kalicode-cli/-/kalicode-cli-0.3.3.tgz","fileCount":154,"integrity":"sha512-LwP6wj4MKCFSclEaTdCml5xnVJvwtFNwdwz6SY0C1KsFPY6ei7gfOVMid0gpYEia6MKnJJk6oMtiqTqJjy2Lpg==","signatures":[{"sig":"MEUCID4qfnzalPjf2Bg5AxnJiIfwmXVjnQTGYMt7DoSMjbbmAiEA3q6gVbqllrIAPT50BFHYQNsw4Ve4FhQESGKhg9YG3JA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":735586},"main":"dist/index.js","types":"./dist/index.d.ts","engines":{"node":">=16.0.0"},"gitHead":"920055f73c7f22ab20a7d42ed29c08bcfa935223","scripts":{"dev":"tsx src/index.ts","lint":"eslint . --ext .js,.jsx,.ts,.tsx","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"anak10thn","email":"anak10thn@gmail.com"},"_npmVersion":"10.9.2","description":"KALICODE - An open-source AI agent that brings the power of AI directly into your terminal.","directories":{},"_nodeVersion":"22.16.0","dependencies":{"ink":"^3.2.0","axios":"^1.6.0","chalk":"^4.1.2","react":"^17.0.2","cfonts":"^3.3.0","dotenv":"^16.3.0","openai":"^5.10.1","enquirer":"^2.4.1","fs-extra":"^11.1.1","tiktoken":"^1.0.21","commander":"^11.1.0","mcp-client":"^1.13.0","ink-markdown":"^1.0.4","@anthropic-ai/sdk":"^0.24.3"},"preferGlobal":true,"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","eslint":"^9.31.0","typescript":"^4.9.5","@types/node":"^20.8.0","@types/react":"^17.0.0","@types/fs-extra":"^11.0.2","@typescript-eslint/parser":"^8.37.0","@typescript-eslint/eslint-plugin":"^8.37.0"},"_npmOperationalInternal":{"tmp":"tmp/kalicode-cli_0.3.3_1754493725693_0.479132178024708","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-08-06T15:22:05.592Z","modified":"2026-05-04T04:22:45.150Z","0.3.3":"2025-08-06T15:22:05.975Z"},"author":{"name":"anak10thn","email":"anak10thn@gmail.com"},"license":"MIT","keywords":["cli","agent","text-editor","kalicode","ai"],"description":"KALICODE - An open-source AI agent that brings the power of AI directly into your terminal.","maintainers":[{"email":"nofriiza@gmail.com","name":"nofriiza"},{"email":"anak10thn@gmail.com","name":"anak10thn"}],"readme":"# KALICODE CLI\n\nA conversational AI CLI tool with intelligent text editor capabilities and tool usage.\n\n<img width=\"1039\" height=\"490\" alt=\"Screenshot 2025-07-21 at 13 35 41\" src=\"blobs/welcome.png\" />\n\n## Features\n\n- **🤖 Multi-LLM Provider Support**: Choose from Anthropic Claude, OpenAI GPT, Grok, or Local LLM models\n- **🎯 Interactive Provider Selection**: Easy-to-use interface for selecting providers and models at startup\n- **🔌 MCP Integration**: Connect to Model Context Protocol servers for extended tool capabilities\n- **📝 Smart File Operations**: AI automatically uses tools to view, create, and edit files\n- **⚡ Bash Integration**: Execute shell commands through natural conversation\n- **🔧 Automatic Tool Selection**: AI intelligently chooses the right tools for your requests\n- **💬 Interactive UI**: Beautiful terminal interface built with Ink\n- **⚙️ Persistent Settings**: Save your preferred provider and model settings\n- **🌍 Global Installation**: Install and use anywhere with `npm i -g @biznetgio/kalicode-cli`\n\n## Installation\n\n### Prerequisites\n- Node.js 16+\n- API key from at least one supported provider (or a local LLM server):\n  - **Anthropic Claude**: Get your key from [console.anthropic.com](https://console.anthropic.com/)\n  - **OpenAI**: Get your key from [platform.openai.com/api-keys](https://platform.openai.com/api-keys)\n  - **Grok (X.AI)**: Get your key from [console.x.ai](https://console.x.ai/)\n  - **Local LLM**: Set up a local server (LM Studio, Ollama, llama.cpp, etc.)\n\n### Global Installation (Recommended)\n```bash\nnpm install -g @biznetgio/kalicode-cli\n```\n\n### Local Development\n```bash\ngit clone <repository>\ncd kalicode-cli\nnpm install\nnpm run build\nnpm link\n```\n\n## Setup\n\n### Multi-LLM Provider Support\n\nKALICODE supports multiple AI providers. You can set up API keys for any or all of them:\n\n**Method 1: Environment Variables**\n```bash\n# Anthropic Claude\nexport ANTHROPIC_API_KEY=your_anthropic_key_here\n\n# OpenAI\nexport OPENAI_API_KEY=your_openai_key_here\n\n# Grok (X.AI)\nexport GROK_API_KEY=your_grok_key_here\n\n# Local LLM (optional)\nexport LOCAL_API_KEY=your_local_api_key_here\nexport LOCAL_BASE_URL=http://localhost:1234/v1\n```\n\n**Method 2: .env File**\n```bash\ncp .env.example .env\n# Edit .env and add your API keys\n```\n\n**Method 3: Command Line Flags**\n```bash\nkalicode --anthropic-key your_anthropic_key_here\nkalicode --openai-key your_openai_key_here\nkalicode --grok-key your_grok_key_here\n```\n\n**Method 4: User Settings File**\nCreate `~/.kalicode/user-settings.json`:\n```json\n{\n  \"provider\": \"anthropic\",\n  \"model\": \"claude-3-7-sonnet-latest\",\n  \"apiKeys\": {\n    \"anthropic\": \"your_anthropic_key_here\",\n    \"openai\": \"your_openai_key_here\",\n    \"grok\": \"your_grok_key_here\",\n    \"local\": \"your_local_api_key_here\"\n  },\n  \"baseURLs\": {\n    \"local\": \"http://localhost:1234/v1\"\n  }\n}\n```\n\n### Local LLM Setup\n\nKALICODE supports connecting to local LLM servers that expose OpenAI-compatible APIs. This includes popular local LLM solutions like:\n\n- **LM Studio**: Download and run models locally with a user-friendly interface\n- **Ollama**: Lightweight, extensible framework for running LLMs locally\n- **llama.cpp**: Direct C++ implementation for running LLaMA models\n- **Text Generation WebUI**: Web interface for running various LLM models\n- **vLLM**: High-throughput LLM serving engine\n- **LocalAI**: OpenAI-compatible API for local models\n\n#### Quick Setup Examples\n\n**LM Studio:**\n1. Download and install [LM Studio](https://lmstudio.ai/)\n2. Download a model (e.g., Llama 2, Code Llama, Mistral)\n3. Start the local server (usually runs on `http://localhost:1234/v1`)\n4. Select \"Local\" provider in KALICODE and use the wizard\n\n**Ollama:**\n1. Install [Ollama](https://ollama.ai/)\n2. Pull a model: `ollama pull llama2`\n3. Start Ollama server: `ollama serve` (runs on `http://localhost:11434/v1`)\n4. Select \"Local\" provider in KALICODE and configure\n\n**llama.cpp:**\n1. Build llama.cpp with server support\n2. Start server: `./server -m model.gguf --port 8080`\n3. Use `http://localhost:8080/v1` as base URL in KALICODE\n\n#### Local LLM Configuration Wizard\n\nWhen you select \"Local\" as your provider, KALICODE will guide you through a 4-step configuration wizard:\n\n1. **Base URL**: Enter your local server URL (e.g., `http://localhost:1234/v1`)\n2. **Model Name**: Specify the model name your server uses\n3. **API Key**: Enter API key if your local server requires authentication (optional)\n4. **Save Configuration**: Choose whether to save settings for future use\n\nThe wizard includes helpful examples and validates your configuration before proceeding.\n\n### Provider Selection\n\nWhen you first run KALICODE, you'll be presented with an interactive interface to:\n\n1. **Select your preferred LLM provider** (Anthropic, OpenAI, Grok, or Local)\n2. **Choose a model** from the available options for that provider\n3. **Enter your API key** if not already configured\n4. **Save your preferences** for future sessions\n\nYou can change providers anytime by:\n- Typing `provider` or `switch` in the chat\n- Pressing `Ctrl+P` for quick provider switching\n- Running `kalicode` again to go through the selection process\n\n### Supported Models\n\n**Anthropic Claude:**\n- `claude-3-7-sonnet-latest` (Latest Claude 3.7 Sonnet)\n- `claude-sonnet-4-20250514` (Claude Sonnet 4)\n- `claude-opus-4-20250514` (Claude Opus 4)\n- `claude-3-5-sonnet-20241022` (Claude 3.5 Sonnet)\n- `claude-3-5-haiku-20241022` (Fast and efficient)\n- `claude-3-opus-20240229` (Most capable Claude 3)\n\n**OpenAI:**\n- `gpt-4o` (Latest GPT-4 Omni)\n- `gpt-4o-mini` (Fast and cost-effective)\n- `gpt-4-turbo` (High performance)\n- `gpt-3.5-turbo` (Fast and affordable)\n\n**Grok (X.AI):**\n- `grok-beta` (Latest Grok model)\n- `grok-vision-beta` (With vision capabilities)\n\n**Local LLM:**\n- `custom-model` (Your custom local model)\n- Configure any model name through the setup wizard\n\n## Usage\n\nStart the conversational AI assistant:\n```bash\nkalicode\n```\n\nOr specify a working directory:\n```bash\nkalicode -d /path/to/project\n```\n\n### Response Style Options\n\nControl the verbosity and communication style of KALICODE responses:\n\n```bash\n# Concise mode - short, direct responses (< 4 lines)\nkalicode --concise\n\n# Verbose mode - detailed explanations and context\nkalicode --verbose\n\n# Security level control\nkalicode --security-level high    # Strict validation\nkalicode --security-level medium  # Standard validation (default)\nkalicode --security-level low     # Basic validation\n```\n\n**Response Style Benefits:**\n- **Concise Mode**: Up to 65% reduction in response length, faster interactions\n- **Verbose Mode**: Full explanations for learning and complex tasks\n- **Balanced Mode** (default): Optimal mix of efficiency and helpfulness\n\n### Multi-Tool Batching\n\nEnable parallel execution of independent tools for improved performance:\n\n```bash\n# Enable batching (parallel execution)\nkalicode --enable-batching\n\n# Disable batching (sequential execution)\nkalicode --disable-batching\n```\n\nOr via environment variable:\n```bash\nexport KALICODE_ENABLE_BATCHING=true  # or 'false'\n```\n\n**Performance Benefits:**\n- **Up to 40% faster execution** when multiple independent tools are used\n- **Intelligent dependency detection** ensures file operations remain safe\n- **Automatic fallback** to sequential execution if parallel execution fails\n- **Smart categorization** of tools (read-only, write, compute, network, bash)\n\n**How it works:**\n- Read-only tools (like `view_file`) can run in parallel with each other\n- Write tools (like `create_file`, `str_replace_editor`) run sequentially for safety\n- Bash commands run sequentially to prevent conflicts\n- Network and compute tools are intelligently batched based on dependencies\n\n### Code Reference System\n\nEnhanced file navigation with clickable references inspired by Claude Code patterns:\n\n```bash\n# Enable code references (enabled by default)\nkalicode --enable-code-references\n\n# Disable code references\nkalicode --disable-code-references\n```\n\nOr via environment variable:\n```bash\nexport KALICODE_ENABLE_CODE_REFERENCES=true  # or 'false'\n```\n\n**Features:**\n- **Clickable file references**: All file mentions become clickable links\n- **Line-specific navigation**: Jump directly to specific lines in files\n- **VSCode integration**: Links open directly in VSCode editor\n- **Automatic enhancement**: Tool outputs automatically include clickable references\n- **Context awareness**: Shows code context around referenced lines\n\n**Examples:**\n- File reference: [`package.json`](vscode://file/package.json)\n- Line reference: [`src/index.ts:42`](vscode://file/src/index.ts:42)\n- Error reference: [`src/utils/helper.ts:15`](vscode://file/src/utils/helper.ts:15)\n\n### First Run Experience\n\nOn your first run, KALICODE will guide you through:\n\n1. **Provider Selection**: Choose from Anthropic, OpenAI, or Grok\n2. **Model Selection**: Pick the best model for your needs\n3. **API Key Setup**: Enter your API key (with option to save it)\n4. **Ready to Chat**: Start conversing with your chosen AI\n\n### Switching Providers\n\nYou can easily switch between providers and models:\n\n- Type `provider` or `switch` in the chat\n- Press `Ctrl+P` for quick access\n- Your preferences are automatically saved to `~/.kalicode/user-settings.json`\n\n### Custom Instructions\n\nYou can provide custom instructions to tailor KALICODE's behavior to your project by creating a `.kalicode/KALICODE.md` file in your project directory:\n\n```bash\nmkdir .kalicode\n```\n\nCreate `.kalicode/KALICODE.md` with your custom instructions:\n```markdown\n# Custom Instructions for KALICODE CLI\n\nAlways use TypeScript for any new code files.\nWhen creating React components, use functional components with hooks.\nPrefer const assertions and explicit typing over inference where it improves clarity.\nAlways add JSDoc comments for public functions and interfaces.\nFollow the existing code style and patterns in this project.\n```\n\nKALICODE will automatically load and follow these instructions when working in your project directory. The custom instructions are added to KALICODE's system prompt and take priority over default behavior.\n\n## Example Conversations\n\nInstead of typing commands, just tell KALICODE what you want to do:\n\n```\n💬 \"Show me the contents of package.json\"\n💬 \"Create a new file called hello.js with a simple console.log\"\n💬 \"Find all TypeScript files in the src directory\"\n💬 \"Replace 'oldFunction' with 'newFunction' in all JS files\"\n💬 \"Run the tests and show me the results\"\n💬 \"What's the current directory structure?\"\n```\n\n### Response Style Examples\n\n**Concise Mode (`--concise`):**\n```\n❯ view package.json\n[file contents displayed directly]\n\n❯ what files are in src?\n- index.ts\n- agent/\n- tools/\n- ui/\n```\n\n**Verbose Mode (`--verbose`):**\n```\n❯ view package.json\nI'll help you view the package.json file. Let me use the view_file tool to read the contents for you.\n\nThis will show you all the dependencies, scripts, and configuration details in your package.json file.\n\n[file contents with detailed explanations]\n\nThe package.json contains your project configuration including dependencies like React, TypeScript, and various development tools.\n```\n\n### Using with Local LLMs\n\nKALICODE works seamlessly with local LLM servers. Here are some examples:\n\n```bash\n# Using with LM Studio (Code Llama for coding tasks)\nkalicode  # Select Local provider, use http://localhost:1234/v1\n\n# Using with Ollama (Llama 2 for general tasks)\nollama serve\nkalicode  # Select Local provider, use http://localhost:11434/v1\n\n# Using with custom llama.cpp server\n./server -m codellama-7b.gguf --port 8080\nkalicode  # Select Local provider, use http://localhost:8080/v1\n```\n\nLocal LLMs are particularly useful for:\n- **Privacy-sensitive projects** where you don't want to send code to external APIs\n- **Offline development** when internet connectivity is limited\n- **Cost optimization** for high-volume usage\n- **Custom fine-tuned models** specific to your domain or coding style\n\n## MCP Integration\n\nKALICODE supports the Model Context Protocol (MCP), allowing you to connect to external tools and resources through MCP servers. This extends KALICODE's capabilities beyond built-in tools.\n\n### MCP Configuration\n\nCreate `~/.kalicode/mcp-settings.json` to configure MCP servers:\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/allowed/files\"],\n      \"enabled\": true\n    },\n    \"brave-search\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-brave-search\"],\n      \"env\": {\n        \"BRAVE_API_KEY\": \"your_brave_api_key_here\"\n      },\n      \"enabled\": true\n    },\n    \"example-sse\": {\n      \"type\": \"sse\",\n      \"url\": \"http://localhost:8080/sse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your_token_here\"\n      },\n      \"enabled\": true\n    },\n    \"example-http\": {\n      \"type\": \"httpStream\",\n      \"url\": \"http://localhost:8080/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your_token_here\"\n      },\n      \"enabled\": true\n    }\n  }\n}\n```\n\nExamples :\n\n```json\n{\n  \"mcpServers\": {\n    \"llmtxt\": {\n      \"type\": \"sse\",\n      \"url\": \"https://mcp.llmtxt.dev/sse\",\n      \"enabled\": true,\n      \"description\": \"LLMTXT MCP server for text processing and utilities\",\n      \"timeout\": 30000,\n      \"retryAttempts\": 3,\n      \"retryDelay\": 1000\n    }\n  },\n  \"globalTimeout\": 30000,\n  \"enableLogging\": true,\n  \"logLevel\": \"info\"\n}\n```\n\n### Supported MCP Server Types\n\n**Local MCP Servers (stdio):**\n- Run as child processes communicating via standard input/output\n- Examples: filesystem access, local databases, system tools\n- Use `command` and `args` to specify how to launch the server\n\n**HTTP Stream MCP Servers:**\n- Connect to HTTP-based servers using streaming\n- Examples: web APIs, cloud services\n- Use `url` and optional `headers` for authentication\n\n**SSE MCP Servers:**\n- Connect to HTTP-based servers using Server-Sent Events\n- Examples: real-time APIs, streaming services\n- Use `url` and optional `headers` for authentication\n\n### Available MCP Tools\n\nOnce configured, MCP tools become available in KALICODE with the naming pattern `mcp_{server}_{tool}`. For example:\n- `mcp_filesystem_read_file` - Read files through filesystem server\n- `mcp_brave_search_web_search` - Search the web using Brave Search\n- `mcp_weather_get_forecast` - Get weather data from a weather server\n\n### MCP Resources\n\nMCP servers can also provide resources (data sources) that KALICODE can access for context, such as:\n- File contents from filesystem servers\n- API responses from web services\n- Database query results\n- System information\n\nFor detailed MCP setup and troubleshooting, see [`docs/MCP_INTEGRATION.md`](docs/MCP_INTEGRATION.md).\n\n## Advanced Configuration\n\n### Token Management & Conversation Condensing\n\nKALICODE includes automatic conversation condensing to manage token usage efficiently. When conversations approach the model's token limit, KALICODE automatically summarizes older messages while preserving recent context.\n\n**Condense Threshold Configuration:**\n\nThe condense threshold determines when conversation condensing is triggered (default: 75% of model's token limit).\n\n```bash\n# Set via environment variable (highest priority)\nexport KALICODE_CONDENSE_THRESHOLD=80\nkalicode\n\n# Or set for single session\nKALICODE_CONDENSE_THRESHOLD=85 kalicode\n```\n\n**User Settings Configuration:**\n\nEdit `~/.kalicode/user-settings.json`:\n```json\n{\n  \"provider\": \"anthropic\",\n  \"model\": \"claude-3-5-sonnet-20241022\",\n  \"condenseThreshold\": 80\n}\n```\n\n**Recommended Thresholds:**\n- **Conservative (60-70%)**: Early condensing, lower token usage\n- **Balanced (75-80%)**: Default, good balance of context and efficiency  \n- **Aggressive (85-95%)**: Maximum context retention, higher token usage\n\nFor comprehensive configuration details, troubleshooting, and advanced usage patterns, see [`CONDENSE_THRESHOLD_GUIDE.md`](CONDENSE_THRESHOLD_GUIDE.md).\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Development mode\nnpm run dev\n\n# Build project\nnpm run build\n\n# Run linter\nnpm run lint\n\n# Type check\nnpm run typecheck\n\n# Test response styles\nnpm run test:response-style\n\n# Test concise mode\nnpm run test:concise\n\n# Test verbose mode\nnpm run test:verbose\n```\n\n## Architecture\n\n- **Multi-LLM Client**: Unified interface supporting Anthropic, OpenAI, Grok, and Local LLM APIs\n- **Provider Selection**: Interactive UI for choosing providers and models with local LLM wizard\n- **Agent**: Core command processing and execution logic with multi-provider support\n- **Tools**: Text editor and bash tool implementations\n- **UI**: Ink-based terminal interface components with provider management and local LLM configuration\n- **Settings**: Persistent user preferences, API key management, and local server configuration\n- **Types**: TypeScript definitions for the entire system including local LLM support\n\n## License\n\nMIT\n","readmeFilename":"README.md"}