codesavant 1.0.0

package/README.md

@@ -0,0 +1,610 @@
+# CodeSavant
+
+<div align="center">
+
+```
+ ██████╗ ██████╗ ██████╗ ███████╗███████╗ █████╗ ██╗   ██╗ █████╗ ███╗   ██╗████████╗
+██╔════╝██╔═══██╗██╔══██╗██╔════╝██╔════╝██╔══██╗██║   ██║██╔══██╗████╗  ██║╚══██╔══╝
+██║     ██║   ██║██║  ██║█████╗  ███████╗███████║██║   ██║███████║██╔██╗ ██║   ██║
+██║     ██║   ██║██║  ██║██╔══╝  ╚════██║██╔══██║╚██╗ ██╔╝██╔══██║██║╚██╗██║   ██║
+╚██████╗╚██████╔╝██████╔╝███████╗███████║██║  ██║ ╚████╔╝ ██║  ██║██║ ╚████║   ██║
+ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚══════╝╚═╝  ╚═╝  ╚═══╝  ╚═╝  ╚═╝╚═╝  ╚═══╝   ╚═╝
+```
+
+**Multi-Provider AI Coding Assistant for Your Terminal**
+
+[![npm version](https://badge.fury.io/js/codesavant.svg)](https://www.npmjs.com/package/codesavant)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/codesavant.svg)](https://nodejs.org)
+
+</div>
+
+---
+
+## What is CodeSavant?
+
+CodeSavant is a powerful AI coding assistant that runs directly in your terminal. Unlike cloud-based solutions, CodeSavant gives you the flexibility to choose from multiple AI providers (DeepSeek, Groq, Gemini, OpenAI, Anthropic, or local Ollama) while keeping your code and conversations private.
+
+**Key Benefits:**
+- **Cost Effective**: Use providers like DeepSeek at $0.14/1M tokens vs $15/1M for GPT-4
+- **Provider Choice**: Switch between 7+ AI providers based on your needs
+- **Privacy First**: Run locally with Ollama, or use any cloud provider
+- **Full Tooling**: Read, write, edit files, run commands, search codebases
+- **Session Persistence**: Continue conversations across terminal sessions
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Supported Providers](#supported-providers)
+- [Usage](#usage)
+  - [Interactive Mode](#interactive-mode)
+  - [Commands](#commands)
+  - [Multi-line Input](#multi-line-input)
+- [Configuration](#configuration)
+- [Project Memory (SAVANT.md)](#project-memory-savantmd)
+- [Tools](#tools)
+- [Permission System](#permission-system)
+- [Skills](#skills)
+- [MCP Integration](#mcp-integration)
+- [VS Code Extension](#vs-code-extension)
+- [Environment Variables](#environment-variables)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18.0.0 or higher
+- At least one AI provider API key (or Ollama installed locally)
+
+### Install via npm
+
+```bash
+npm install -g codesavant
+```
+
+### Verify Installation
+
+```bash
+codesavant --version
+```
+
+---
+
+## Quick Start
+
+### 1. Set up an API key
+
+Choose at least one provider and set the API key:
+
+```bash
+# DeepSeek (Recommended - Best cost/performance ratio)
+export DEEPSEEK_API_KEY="your-api-key"
+
+# Groq (Fastest response times)
+export GROQ_API_KEY="your-api-key"
+
+# Google Gemini (Large context window)
+export GEMINI_API_KEY="your-api-key"
+
+# OpenAI
+export OPENAI_API_KEY="your-api-key"
+
+# Anthropic
+export ANTHROPIC_API_KEY="your-api-key"
+
+# Or use Ollama locally (no API key needed)
+# Just ensure Ollama is running: ollama serve
+```
+
+### 2. Start CodeSavant
+
+```bash
+codesavant
+```
+
+### 3. Start Coding!
+
+```
+> Explain the structure of this codebase
+
+> Create a function to validate email addresses
+
+> Fix the bug in src/utils.ts
+
+> Write tests for the authentication module
+```
+
+---
+
+## Supported Providers
+
+| Provider | Cost (per 1M tokens) | Speed | Best For | API Key Variable |
+|----------|---------------------|-------|----------|------------------|
+| **DeepSeek** | $0.14 in / $0.28 out | Medium | Primary coding tasks | `DEEPSEEK_API_KEY` |
+| **Groq** | $0.59 in / $0.79 out | Fastest | Quick queries, chat | `GROQ_API_KEY` |
+| **Gemini** | $0.15 in / $0.60 out | Fast | Large context tasks | `GEMINI_API_KEY` |
+| **OpenAI** | $5.00 in / $15.00 out | Medium | Complex reasoning | `OPENAI_API_KEY` |
+| **Anthropic** | $3.00 in / $15.00 out | Medium | Code review, analysis | `ANTHROPIC_API_KEY` |
+| **Vertex AI** | Varies | Medium | Enterprise/GCP users | `GOOGLE_APPLICATION_CREDENTIALS` |
+| **Ollama** | Free (local) | Variable | Offline, privacy | None (local) |
+
+**Estimated Monthly Cost**: $2-10 for typical individual usage with DeepSeek/Groq.
+
+### Smart Routing
+
+CodeSavant automatically routes requests to the best available provider based on:
+- Task complexity
+- Provider availability
+- Cost optimization
+- Response speed requirements
+
+---
+
+## Usage
+
+### Interactive Mode
+
+```bash
+# Start a new session
+codesavant
+
+# Continue the last session
+codesavant -c
+codesavant --continue
+
+# Resume a specific session
+codesavant -r <session-id>
+codesavant --resume <session-id>
+
+# Start with an initial prompt
+codesavant "Explain this codebase"
+
+# Use a specific provider
+codesavant --provider deepseek
+codesavant --provider groq
+
+# Use a specific model
+codesavant --model gpt-4o
+```
+
+### Commands
+
+Inside the CodeSavant REPL, use these slash commands:
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show all available commands |
+| `/clear` | Clear conversation history |
+| `/history` | Show conversation history |
+| `/session` | Show current session ID |
+| `/sessions` | List all saved sessions |
+| `/providers` | Show available AI providers |
+| `/stats` | Show token usage and cost statistics |
+| `/compact` | Manually compact conversation context |
+| `/export` | Export conversation to file |
+| `/config` | Show current configuration |
+| `/doctor` | Diagnose configuration issues |
+| `/init` | Initialize CodeSavant in current project |
+| `/exit` | Exit CodeSavant |
+
+### Multi-line Input
+
+Use triple quotes `"""` to enter multi-line input:
+
+```
+> """
+Create a React component that:
+- Displays a list of users
+- Supports pagination
+- Has a search filter
+- Shows loading states
+"""
+```
+
+Press Enter after the closing `"""` to submit.
+
+---
+
+## Configuration
+
+### Configuration File
+
+CodeSavant stores configuration in `~/.codesavant/config.json`:
+
+```json
+{
+  "provider": "deepseek",
+  "model": "deepseek-coder",
+  "maxTokens": 4096,
+  "temperature": 0.7,
+  "permissions": {
+    "mode": "default",
+    "allowedPaths": ["."],
+    "deniedPaths": ["node_modules", ".git", ".env"]
+  }
+}
+```
+
+### Configuration Commands
+
+```bash
+# View all configuration
+codesavant config
+
+# View specific setting
+codesavant config get provider
+
+# Set a value
+codesavant config set provider deepseek
+codesavant config set maxTokens 8192
+
+# Show available providers
+codesavant config --providers
+```
+
+### Directory Structure
+
+```
+~/.codesavant/
+├── config.json      # Global configuration
+├── sessions/        # Saved conversation sessions
+├── skills/          # Custom skills
+└── SAVANT.md        # Global project memory
+```
+
+---
+
+## Project Memory (SAVANT.md)
+
+Create a `SAVANT.md` file in your project root to give CodeSavant context about your project. This file is automatically read when you start CodeSavant in that directory.
+
+### Example SAVANT.md
+
+```markdown
+# Project: MyApp
+
+## Overview
+E-commerce platform built with Next.js and PostgreSQL.
+
+## Tech Stack
+- Frontend: Next.js 14, React 18, TailwindCSS
+- Backend: Node.js, Express, Prisma ORM
+- Database: PostgreSQL
+- Testing: Jest, Playwright
+
+## Project Structure
+- `/src/app` - Next.js app router pages
+- `/src/components` - Reusable React components
+- `/src/lib` - Utility functions and helpers
+- `/src/api` - API route handlers
+- `/prisma` - Database schema and migrations
+
+## Coding Conventions
+- Use TypeScript strict mode
+- Prefer functional components with hooks
+- Use async/await over promises
+- Run `npm run lint` before committing
+
+## Common Commands
+- `npm run dev` - Start development server
+- `npm run build` - Build for production
+- `npm run test` - Run test suite
+- `npm run db:migrate` - Run database migrations
+
+## Important Notes
+- Never commit .env files
+- Always run tests before pushing
+- Use conventional commits format
+```
+
+---
+
+## Tools
+
+CodeSavant has access to powerful tools for interacting with your codebase:
+
+### File Operations
+
+| Tool | Description |
+|------|-------------|
+| **Read** | Read file contents |
+| **Write** | Create or overwrite files |
+| **Edit** | Make precise edits with search/replace |
+| **Glob** | Find files using glob patterns |
+| **Grep** | Search file contents with regex |
+
+### System Operations
+
+| Tool | Description |
+|------|-------------|
+| **Bash** | Execute shell commands |
+| **ListDir** | List directory contents |
+
+### Examples
+
+```
+> Read the package.json file
+
+> Find all TypeScript files in src/
+
+> Search for "TODO" comments in the codebase
+
+> Run the test suite
+
+> Create a new component file at src/components/Button.tsx
+```
+
+---
+
+## Permission System
+
+CodeSavant asks for permission before potentially dangerous operations to keep your system safe.
+
+### Permission Modes
+
+| Mode | Description |
+|------|-------------|
+| `default` | Ask for dangerous operations, auto-allow safe ones |
+| `strict` | Ask for all file writes and commands |
+| `permissive` | Auto-allow most operations (use with caution) |
+
+### Auto-Allowed Operations
+- Reading files
+- Searching with glob/grep
+- Git status, log, diff commands
+- npm/yarn info commands
+
+### Auto-Denied Operations
+- `rm -rf /` and similar destructive commands
+- `sudo` commands
+- Writing to `.env` files
+- Commands with shell injection risks
+
+### Interactive Prompts
+
+When prompted for permission, you can respond:
+- `y` or `yes` - Allow this once
+- `n` or `no` - Deny this once
+- `a` or `always` - Allow for this session
+- `never` - Deny for this session
+
+---
+
+## Skills
+
+Skills are pre-built prompt templates for common tasks. Use them with the `/` prefix:
+
+| Skill | Description |
+|-------|-------------|
+| `/commit` | Generate a git commit message |
+| `/review` | Review code for issues |
+| `/test` | Generate tests for code |
+| `/explain` | Explain how code works |
+| `/refactor` | Suggest refactoring improvements |
+
+### Using Skills
+
+```
+> /commit
+
+> /review src/auth.ts
+
+> /test src/utils/validation.ts
+```
+
+---
+
+## MCP Integration
+
+CodeSavant supports the Model Context Protocol (MCP) for extending functionality with external tools.
+
+### Configure MCP Servers
+
+Create `.codesavant/mcp.json` in your project:
+
+```json
+{
+  "servers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-server-filesystem", "/path/to/allowed/dir"]
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### View MCP Status
+
+```bash
+codesavant mcp status
+```
+
+---
+
+## VS Code Extension
+
+CodeSavant includes a VS Code extension for integrated development.
+
+### Features
+- Start CodeSavant chat from VS Code
+- Explain selected code
+- Fix code issues
+- Generate tests
+- Code review
+
+### Installation
+
+```bash
+cd vscode-extension
+npm install
+npm run compile
+```
+
+Then press F5 in VS Code to launch in debug mode.
+
+---
+
+## Environment Variables
+
+### API Keys
+
+| Variable | Description |
+|----------|-------------|
+| `DEEPSEEK_API_KEY` | DeepSeek API key |
+| `GROQ_API_KEY` | Groq API key |
+| `GEMINI_API_KEY` | Google Gemini API key |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `ANTHROPIC_API_KEY` | Anthropic API key |
+| `GOOGLE_APPLICATION_CREDENTIALS` | Path to GCP credentials for Vertex AI |
+
+### Configuration
+
+| Variable | Description |
+|----------|-------------|
+| `CODESAVANT_PROVIDER` | Default AI provider |
+| `CODESAVANT_MODEL` | Default model to use |
+| `CODESAVANT_CONFIG_PATH` | Custom config file path |
+
+### Shell Configuration
+
+Add to your `~/.bashrc` or `~/.zshrc`:
+
+```bash
+# API Keys
+export DEEPSEEK_API_KEY="your-key-here"
+
+# Aliases
+alias cs="codesavant"
+alias csc="codesavant -c"
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### "No AI providers available"
+
+```bash
+# Check which providers are configured
+codesavant config --providers
+
+# Verify API key is set
+echo $DEEPSEEK_API_KEY
+```
+
+#### "Permission denied" errors
+
+```bash
+# Run the doctor command
+codesavant doctor
+
+# Check file permissions
+ls -la ~/.codesavant/
+```
+
+#### Session not persisting
+
+```bash
+# Check sessions directory exists
+ls ~/.codesavant/sessions/
+
+# List available sessions
+codesavant --list-sessions
+```
+
+#### Slow responses
+
+- Try a faster provider like Groq
+- Reduce `maxTokens` in config
+- Use `/compact` to reduce context size
+
+### Debug Mode
+
+```bash
+# Run with verbose logging
+DEBUG=codesavant* codesavant
+```
+
+### Reset Configuration
+
+```bash
+# Remove config and start fresh
+rm -rf ~/.codesavant/config.json
+codesavant
+```
+
+---
+
+## CLI Reference
+
+```
+Usage: codesavant [options] [prompt]
+
+Options:
+  -V, --version          Output version number
+  -c, --continue         Continue last session
+  -r, --resume <id>      Resume specific session
+  -p, --provider <name>  Use specific provider
+  -m, --model <name>     Use specific model
+  --list-sessions        List all saved sessions
+  --no-memory            Disable project memory (SAVANT.md)
+  -h, --help             Display help
+
+Commands:
+  config                 Manage configuration
+  doctor                 Diagnose issues
+  init                   Initialize project
+  mcp                    Manage MCP servers
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## Acknowledgments
+
+- Built with [Commander.js](https://github.com/tj/commander.js/)
+- Terminal UI powered by [Chalk](https://github.com/chalk/chalk) and [Ink](https://github.com/vadimdemedes/ink)
+- AI integrations via [OpenAI SDK](https://github.com/openai/openai-node) and [Google Generative AI](https://github.com/google/generative-ai-js)
+
+---
+
+<div align="center">
+
+**Made with love by [Vishal Aggarwal](https://github.com/burnisback)**
+
+[Report Bug](https://github.com/burnisback/code-savant-ai/issues) · [Request Feature](https://github.com/burnisback/code-savant-ai/issues)
+
+</div>