@majkapp/majk-chat-cli 1.0.0

package/README.md

@@ -0,0 +1,746 @@
+# @majkapp/majk-chat-cli
+
+A powerful command-line interface for interacting with multiple LLM providers. Features interactive chat mode, tool execution, credential management, and rich command-line options.
+
+## Features
+
+- 💬 **Interactive Chat Mode**: Real-time conversation with LLMs
+- 🛠️ **Tool Execution**: Execute bash commands and file operations with permission controls
+- 🔑 **Smart Credential Management**: Auto-detect credentials from multiple sources
+- 📁 **File I/O**: Read messages from files, save conversations
+- 🎨 **Rich CLI**: Colored output, progress indicators, intuitive commands
+- 🔄 **Multi-Provider**: Switch between providers on the fly
+- 💾 **Session Management**: Persistent conversation storage and continuation
+- 📂 **Directory-based Organization**: Sessions organized by working directory
+- 🎯 **Privacy-First**: Optional session tracking with explicit user control
+- ⚙️ **Configurable**: YAML/JSON configuration files
+
+## Installation
+
+### Global Installation via npm
+
+Install globally to use the `majk-chat` command anywhere:
+
+```bash
+npm install -g @majkapp/majk-chat-cli
+```
+
+After installation, you can use `majk-chat` from any directory:
+
+```bash
+majk-chat --help
+majk-chat chat -M "Hello!" --provider openai
+```
+
+### Local Development Installation
+
+```bash
+npm install -g @majkapp/majk-chat-cli
+```
+
+### Local Installation
+
+```bash
+npm install @majkapp/majk-chat-cli
+```
+
+## Quick Start
+
+> **Note**: All examples below use the `majk-chat` command, which is available globally after installing with `npm install -g @majkapp/majk-chat-cli`
+
+### Basic Chat
+
+```bash
+# Send a simple message
+majk-chat chat -M "Hello, how are you?"
+
+# Use a specific provider
+majk-chat chat -p anthropic -M "Explain quantum computing"
+
+# Use a specific model
+majk-chat chat -m gpt-4 -M "Write a haiku"
+```
+
+### Interactive Mode
+
+```bash
+# Start interactive chat
+majk-chat interactive
+
+# With specific provider and model
+majk-chat interactive -p openai -m gpt-4
+
+# With tools enabled
+majk-chat interactive --tools --auto-execute
+```
+
+### Session Management
+
+```bash
+# Create a session with title
+majk-chat chat --save-session --session-title "Web Development" -M "Help me build a React app"
+
+# Continue the most recent session
+majk-chat chat --continue -M "Add user authentication"
+
+# List all sessions in current directory
+majk-chat chat --list-sessions
+
+# Continue a specific session by UUID
+majk-chat chat --session 550e8400-e29b-41d4-a716-446655440000 -M "Let's add more features"
+
+# Delete a session
+majk-chat chat --delete-session 550e8400-e29b-41d4-a716-446655440000
+```
+
+## Commands
+
+### `chat` - Send a single message
+
+```bash
+majk-chat chat [options]
+```
+
+#### Options
+
+- `-p, --provider <provider>` - Provider to use (openai, anthropic, azure-openai, bedrock)
+- `-m, --model <model>` - Model to use
+- `-M, --message <message>` - Message to send
+- `-f, --file <file>` - Read message from file
+- `-s, --system <system>` - System message
+- `-S, --system-file <file>` - Read system message from file
+- `-t, --temperature <temp>` - Temperature (0-2)
+- `--max-tokens <tokens>` - Maximum tokens
+- `-j, --json` - Output JSON response
+- `--tools` - Enable tool execution
+- `--enable-core-tools` - Enable majk-chat-basic-tools (bash, ls, read, etc.)
+- `--tool-result-limit <limit>` - Truncate tool results over this character limit (default: 8000)
+- `--max-steps <steps>` - Maximum tool execution steps
+- `-c, --config <file>` - Configuration file
+- `--api-key <key>` - API key (overrides environment)
+- `--api-key-file <file>` - Read API key from file
+
+#### Session Management Options
+
+- `--save-session` - Save conversation to a persistent session
+- `--continue` - Continue the most recent session in current directory
+- `--session <uuid>` - Continue a specific session by UUID
+- `--session-title <title>` - Set title for new session
+- `--list-sessions` - List all sessions for current directory
+- `--delete-session <uuid>` - Delete a specific session by UUID
+
+#### Examples
+
+```bash
+# Simple message
+majk-chat chat -M "What is the capital of France?"
+
+# With system message
+majk-chat chat -s "You are a helpful assistant" -M "Hello"
+
+# Read from file
+majk-chat chat -f prompt.txt
+
+# With specific model and temperature
+majk-chat chat -m gpt-4 -t 0.7 -M "Write a creative story"
+
+# Enable tools
+majk-chat chat --tools -M "Create a file called test.txt with 'Hello World' in it"
+
+# JSON output
+majk-chat chat -j -M "Hello" > response.json
+
+# Create a session
+majk-chat chat --save-session --session-title "Code Review" -M "Review this Python function"
+
+# Continue a session
+majk-chat chat --continue -M "Fix the performance issues"
+
+# List sessions
+majk-chat chat --list-sessions
+
+# Load specific session
+majk-chat chat --session 550e8400-e29b-41d4-a716-446655440000 -M "Continue our discussion"
+```
+
+### `interactive` - Interactive chat mode
+
+```bash
+majk-chat interactive [options]
+```
+
+#### Options
+
+- `-p, --provider <provider>` - Provider to use
+- `-m, --model <model>` - Model to use
+- `-s, --system <system>` - System message
+- `-S, --system-file <file>` - Read system message from file
+- `--tools` - Enable tool execution
+- `--enable-core-tools` - Enable majk-chat-basic-tools (bash, ls, read, etc.)
+- `--tool-result-limit <limit>` - Truncate tool results over this character limit (default: 8000)
+- `--auto-execute` - Auto-execute tools without confirmation
+- `-c, --config <file>` - Configuration file
+
+#### Interactive Commands
+
+Once in interactive mode, you can use these commands:
+
+- `/help` - Show help message
+- `/exit`, `/quit` - Exit interactive mode
+- `/clear` - Clear conversation history
+- `/history` - Show conversation history
+- `/save <file>` - Save conversation to file
+- `/load <file>` - Load conversation from file
+- `/model <name>` - Set or show current model
+- `/provider <name>` - Set or show current provider
+- `/system <msg>` - Set or show system message
+- `/tools` - Toggle tool execution
+- `/auto` - Toggle auto-execute for tools
+- `/multiline` - Enter multiline input (end with 'END')
+
+#### Examples
+
+```bash
+# Start interactive mode
+majk-chat interactive
+
+# With specific configuration
+majk-chat interactive -p anthropic -m claude-3-sonnet
+
+# With tools enabled
+majk-chat interactive --tools
+
+You> /help
+[Shows available commands]
+
+You> Hello, how are you?
+Assistant: I'm doing well, thank you! How can I help you today?
+
+You> /model gpt-4
+✓ Model set to: gpt-4
+
+You> /save conversation.json
+✓ Conversation saved to conversation.json
+
+You> /multiline
+Enter multiline input. Type END on a new line to finish:
+... This is a
+... multiline
+... message
+... END
+
+You> /exit
+Goodbye! 👋
+```
+
+### `models` - List available models
+
+```bash
+majk-chat models [options]
+```
+
+#### Options
+
+- `-p, --provider <provider>` - Filter by provider
+- `-c, --config <file>` - Configuration file
+
+#### Examples
+
+```bash
+# List all models
+majk-chat models
+
+# List models for specific provider
+majk-chat models -p openai
+```
+
+### `config` - Configure providers and credentials
+
+```bash
+majk-chat config [options]
+```
+
+#### Options
+
+- `--init` - Initialize configuration
+- `--set <key=value>` - Set configuration value
+- `--get <key>` - Get configuration value
+- `--list` - List configuration
+
+#### Examples
+
+```bash
+# Initialize configuration
+majk-chat config --init
+
+# Set a value
+majk-chat config --set providers.openai.apiKey=sk-...
+
+# Get a value
+majk-chat config --get providers.openai.apiKey
+
+# List all configuration
+majk-chat config --list
+```
+
+## Core Tools Usage
+
+The `--enable-core-tools` flag provides access to a comprehensive set of tools for file system operations, process management, and utility functions:
+
+### Available Core Tools
+
+- **bash**: Execute bash commands with optional background execution
+- **kill_bash**: Terminate background bash processes
+- **bash_output**: Monitor and retrieve output from background processes
+- **ls**: List files and directories with filtering
+- **read**: Read file contents with configurable limits and offsets
+- **glob**: Fast file pattern matching using glob patterns
+- **grep**: Search for text patterns in files using regular expressions
+- **edit**: Perform exact string replacements in files
+- **multi_edit**: Make multiple edits to a single file atomically
+- **write**: Write content to files with encoding support
+- **web_fetch**: Fetch content from URLs using HTTP/HTTPS
+- **todo_write**: Manage structured task lists for session tracking
+- **read_tool_result**: Read back large tool results that were truncated
+
+### Basic Usage
+
+```bash
+# Enable core tools with basic usage
+majk-chat chat -M "List all JavaScript files in the src directory" --enable-core-tools
+
+# Enable with custom result limit (default: 8000 chars)
+majk-chat chat -M "Show me the contents of package.json" --enable-core-tools --tool-result-limit 4000
+
+# Filter specific tools (only allow file operations)
+majk-chat chat -M "Read and analyze config files" --enable-core-tools --allowed-tools "ls,read,glob,grep"
+
+# Exclude potentially dangerous tools
+majk-chat chat -M "Analyze the codebase" --enable-core-tools --disallowed-tools "bash,kill_bash,web_fetch"
+```
+
+### Interactive Mode with Core Tools
+
+```bash
+# Start interactive session with core tools
+majk-chat interactive --enable-core-tools
+
+# Example conversation:
+User: Find all TypeScript files and show me the first 50 lines of the main entry point
+
+# The LLM will use tools like:
+# 1. glob --pattern "**/*.ts" 
+# 2. read --file-path "./src/index.ts" --limit 2000
+```
+
+### Background Process Management
+
+```bash
+# Start a long-running task
+majk-chat chat -M "Start a development server in the background and monitor its output" --enable-core-tools
+
+# The LLM can use:
+# 1. bash --command "npm run dev" --run-in-background
+# 2. bash_output --process-id "bg_xxx" --list-all
+# 3. kill_bash --process-id "bg_xxx" (if needed)
+```
+
+### Tool Result Management
+
+When tool results exceed the `--tool-result-limit` (default: 8000 characters):
+
+1. **Automatic Truncation**: Large results are automatically truncated with preview + tail
+2. **Auto-Registration**: `read_tool_result` tool is automatically registered on first truncation
+3. **Full Access**: Complete results remain accessible through unique IDs
+
+```bash
+# Example with large output
+majk-chat chat -M "Find all log files and show their contents" --enable-core-tools --tool-result-limit 2000
+
+# Output will show:
+# "Result truncated (25000 chars). Use read_tool_result with ID: conv_1234567890_abcdef"
+
+# The LLM can then use:
+# read_tool_result --result-id "conv_1234567890_abcdef" --offset 0 --limit 5000
+```
+
+### Tool Filtering Examples
+
+```bash
+# Only filesystem operations
+--allowed-tools "ls,read,write,glob,grep,edit"
+
+# Everything except web access
+--disallowed-tools "web_fetch"
+
+# Wildcard patterns (bash tools only)
+--allowed-tools "bash*"
+
+# Multiple patterns
+--allowed-tools "ls,read,bash*" --disallowed-tools "*kill*"
+```
+
+### Configuration File Integration
+
+Add core tools to your configuration file:
+
+```yaml
+# ~/.majk-chat/config.yaml
+tools:
+  enableCoreTools: true
+  toolResultLimit: 10000
+  allowedTools: ["ls", "read", "glob", "grep", "edit", "write"]
+  
+defaultProvider: "anthropic"
+providers:
+  anthropic:
+    apiKey: "your-key-here"
+```
+
+### Best Practices
+
+1. **Start Conservative**: Begin with limited tools and expand as needed
+2. **Use Filtering**: Always consider `--allowed-tools` for security
+3. **Monitor Resources**: Large results are automatically managed with truncation
+4. **Background Tasks**: Use background execution for long-running operations
+5. **Result Management**: Let the system auto-register `read_tool_result` when needed
+
+### Security Considerations
+
+- Core tools have full filesystem access when enabled
+- `bash` tool can execute any system command
+- Use `--allowed-tools` to restrict capabilities
+- Consider running in isolated environments for untrusted operations
+- Tool results are stored in memory and cleaned up automatically
+
+## Session Management
+
+The CLI includes comprehensive session management for persistent conversations. Sessions allow you to save, continue, and organize your chat conversations across CLI invocations.
+
+### Key Features
+
+- **Privacy-First**: Sessions are only saved when explicitly requested with `--save-session`
+- **Directory Organization**: Sessions are automatically organized by working directory
+- **UUID-based**: Each session has a unique identifier for easy reference
+- **Auto-cleanup**: Old sessions are automatically cleaned up based on age and count limits
+- **Smart Titles**: Automatic title generation from first user message
+
+### Session Storage
+
+Sessions are stored in `~/.majk/chat-sessions/` organized by working directory:
+
+```
+~/.majk/chat-sessions/
+├── users_jules_projects_webapp/
+│   ├── 550e8400-e29b-41d4-a716-446655440000.json
+│   └── 6ba7b810-9dad-11d1-80b4-00c04fd430c8.json
+└── users_jules_documents/
+    └── f47ac10b-58cc-4372-a567-0e02b2c3d479.json
+```
+
+### Session Commands
+
+#### Creating Sessions
+
+```bash
+# Create session with auto-generated title
+majk-chat chat --save-session -M "Help me build a React app"
+
+# Create session with custom title
+majk-chat chat --save-session --session-title "React Tutorial" -M "Getting started with React"
+```
+
+#### Continuing Sessions
+
+```bash
+# Continue most recent session in current directory
+majk-chat chat --continue -M "Add user authentication"
+
+# Continue specific session by UUID
+majk-chat chat --session 550e8400-e29b-41d4-a716-446655440000 -M "Let's add more features"
+```
+
+#### Managing Sessions
+
+```bash
+# List all sessions in current directory
+majk-chat chat --list-sessions
+
+# Sample output:
+# Sessions in current directory:
+#   550e8400-e29b-41d4-a716-446655440000
+#     Title: React Tutorial
+#     Created: 12/1/2023 10:30:00 AM
+#     Updated: 12/1/2023 11:45:00 AM
+#     Messages: 8
+#     Last: Let's add error handling to the authentication
+
+# Delete a session
+majk-chat chat --delete-session 550e8400-e29b-41d4-a716-446655440000
+```
+
+### Session Workflow Examples
+
+#### Project Development Session
+
+```bash
+# Start a new project session
+cd ~/projects/my-app
+majk-chat chat --save-session --session-title "My App Development" -M "Help me design a REST API"
+
+# Continue working on it later
+cd ~/projects/my-app
+majk-chat chat --continue -M "Add database integration"
+
+# Work on it from another day
+cd ~/projects/my-app
+majk-chat chat --continue -M "How do I deploy this API?"
+```
+
+#### Learning Session
+
+```bash
+# Learning session
+majk-chat chat --save-session --session-title "Learning Python" -M "Explain Python decorators"
+
+# Continue learning
+majk-chat chat --continue -M "Show me practical examples of decorators"
+```
+
+### Session Data Format
+
+Each session file contains:
+
+```json
+{
+  "metadata": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "workingDirectory": "/Users/jules/projects/myapp",
+    "createdAt": "2024-01-15T10:30:00.000Z",
+    "updatedAt": "2024-01-15T11:45:00.000Z",
+    "title": "React Tutorial",
+    "provider": "anthropic",
+    "model": "claude-3-sonnet-20240229",
+    "totalMessages": 8
+  },
+  "messages": [
+    {
+      "role": "user",
+      "content": "Help me build a React app"
+    },
+    {
+      "role": "assistant",
+      "content": "I'll help you build a React app...",
+      "tool_calls": [...]
+    }
+  ]
+}
+```
+
+### Privacy and Control
+
+- **No tracking by default**: Conversations are not saved unless `--save-session` is used
+- **User explicit consent**: Sessions are only created when explicitly requested
+- **Local storage only**: All session data stays on your machine
+- **Easy cleanup**: Sessions can be deleted individually or cleaned up automatically
+## Configuration
+
+### Configuration File
+
+Create a configuration file at `~/.majk-chat/config.yaml`:
+
+```yaml
+providers:
+  openai:
+    apiKey: ${OPENAI_API_KEY}
+    organizationId: ${OPENAI_ORG_ID}
+  anthropic:
+    apiKey: ${ANTHROPIC_API_KEY}
+  azure-openai:
+    apiKey: ${AZURE_OPENAI_API_KEY}
+    endpoint: ${AZURE_OPENAI_ENDPOINT}
+    deploymentName: ${AZURE_OPENAI_DEPLOYMENT}
+  bedrock:
+    region: ${AWS_REGION}
+    accessKeyId: ${AWS_ACCESS_KEY_ID}
+    secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
+
+defaultProvider: openai
+
+tools:
+  autoExecute: false
+  maxSteps: 5
+```
+
+You can also use JSON format:
+
+```json
+{
+  "providers": {
+    "openai": {
+      "apiKey": "${OPENAI_API_KEY}"
+    }
+  },
+  "defaultProvider": "openai"
+}
+```
+
+### Credential Sources
+
+The CLI looks for credentials in the following order:
+
+1. **Command-line options** (`--api-key`, `--api-key-file`)
+2. **Environment variables**:
+   - OpenAI: `OPENAI_API_KEY`, `OPENAI_ORG_ID`
+   - Anthropic: `ANTHROPIC_API_KEY`
+   - Azure: `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`
+   - AWS: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`
+3. **Standard provider locations**:
+   - `~/.openai/api_key`
+   - `~/.anthropic/api_key`
+   - `~/.config/openai/api_key`
+   - `~/.config/anthropic/api_key`
+4. **Configuration file** (`~/.majk-chat/config.yaml`)
+
+## Tool Support
+
+### Bash Tool
+
+Execute bash commands with permission controls:
+
+```bash
+# In interactive mode with tools enabled
+You> Can you list the files in the current directory?
+
+⚠️  Tool execution request:
+Tool: bash
+Command: ls -la
+Do you want to execute this command? (y/n) y
+
+Executing: ls -la
+[Output shows files]
+```
+
+### File System Tool
+
+Perform file operations:
+
+```bash
+You> Create a file called hello.txt with "Hello World" in it
+
+⚠️  File system operation request:
+Operation: write
+Path: hello.txt
+Content: Hello World
+Do you want to write this file/directory? (y/n) y
+```
+
+### Auto-execution
+
+Enable auto-execution to skip confirmation prompts:
+
+```bash
+majk-chat interactive --tools --auto-execute
+```
+
+## Advanced Usage
+
+### Piping and Redirection
+
+```bash
+# Pipe input
+echo "Explain Docker" | majk-chat chat
+
+# Read from file, output to file
+majk-chat chat -f prompt.txt > response.txt
+
+# Use with other tools
+cat code.js | majk-chat chat -M "Review this code"
+```
+
+### Scripting
+
+```bash
+#!/bin/bash
+
+# Use in scripts
+response=$(majk-chat chat -M "Generate a random number between 1 and 100" -j)
+echo $response | jq '.choices[0].message.content'
+```
+
+### Multiple Providers
+
+```bash
+# Compare responses from different providers
+for provider in openai anthropic; do
+  echo "Provider: $provider"
+  majk-chat chat -p $provider -M "What is love?"
+  echo "---"
+done
+```
+
+## Environment Variables
+
+- `OPENAI_API_KEY` - OpenAI API key
+- `ANTHROPIC_API_KEY` - Anthropic API key
+- `AZURE_OPENAI_API_KEY` - Azure OpenAI API key
+- `AZURE_OPENAI_ENDPOINT` - Azure OpenAI endpoint
+- `AZURE_OPENAI_DEPLOYMENT` - Azure OpenAI deployment name
+- `AWS_ACCESS_KEY_ID` - AWS access key
+- `AWS_SECRET_ACCESS_KEY` - AWS secret key
+- `AWS_REGION` - AWS region
+- `NO_COLOR` - Disable colored output
+
+## Troubleshooting
+
+### No API Key Found
+
+```bash
+Error: No API key found for provider
+
+Solution:
+1. Set environment variable: export OPENAI_API_KEY=sk-...
+2. Use --api-key flag: majk-chat chat --api-key sk-...
+3. Create config file: majk-chat config --init
+```
+
+### Rate Limiting
+
+```bash
+Error: Rate limit exceeded
+
+Solution:
+1. Wait and retry
+2. Use a different provider
+3. Reduce request frequency
+```
+
+### Tool Execution Denied
+
+```bash
+Error: Permission denied for tool
+
+Solution:
+1. Review the command carefully
+2. Use --auto-execute with caution
+3. Ensure you trust the LLM's tool usage
+```
+
+## Security
+
+- **Credentials**: Never commit API keys to version control
+- **Tool Execution**: Always review commands before execution
+- **File Operations**: Be cautious with write/delete operations
+- **Auto-execution**: Only use in trusted environments
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.
+
+## Support
+
+For issues, questions, or suggestions, please file an issue on our GitHub repository.