@benzsiangco/jarvis 1.1.0 → 1.1.26

package/README.md

@@ -1,65 +1,487 @@
-# Jarvis AI CLI
+# JARVIS - AI Coding Assistant
 
 [![npm version](https://img.shields.io/npm/v/@benzsiangco/jarvis.svg)](https://www.npmjs.com/package/@benzsiangco/jarvis)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-An AI coding agent with TUI, Web, and Desktop support.
+**Just A Rather Very Intelligent System** - An advanced AI coding agent with Terminal UI, Web UI, and Desktop support.
 
-> **Note:** This tool requires [Bun](https://bun.sh) to be installed on your system.
+> **Latest:** v1.1.1 - Now with Brain system, OAuth configuration, enhanced skills, and Electron desktop support!
 
-## Installation
+## ✨ Features
 
-### From npm (Stable)
+- 🧠 **Brain System** - Customize JARVIS's core identity and personality
+- 🔐 **OAuth Configuration** - Deploy in containers with Cloudflare Tunnel support
+- 📚 **Enhanced Skills** - 10+ skill categories (DevOps, Security, Development, etc.)
+- 🖥️ **Three Modes** - Terminal UI, Web UI, or Desktop app
+- 🤖 **Multi-Provider** - OpenAI, Anthropic, Google AI, and more
+- 🔧 **12 Built-in Tools** - bash, read, write, edit, grep, and more
+- 🎨 **Beautiful UI** - Modern, responsive design with dark theme
 
+## 🚀 Quick Start
+
+### Installation
+
+**Full Install (with Desktop app):**
+```bash
+npm install -g @benzsiangco/jarvis electron
+```
+
+**CLI Only (smaller install):**
 ```bash
 npm install -g @benzsiangco/jarvis
 ```
 
-### From GitHub (Latest)
+### Launch JARVIS
+
+**Terminal UI:**
+```bash
+jarvis
+# or
+jarvis tui
+```
+
+**Web UI:**
+```bash
+jarvis web
+# Opens at http://localhost:5533
+```
+
+**Desktop App:**
+```bash
+jarvis electron
+# Requires: npm install -g electron
+```
+
+## 📖 Usage Guide
+
+### Terminal UI (TUI)
+
+Launch the interactive terminal interface:
+
+```bash
+jarvis tui
+```
+
+**Key Bindings:**
+- `Ctrl+P` - Open Commands Menu
+- `Ctrl+T` - Switch Model Variants
+- `Ctrl+L` - Clear Chat
+- `Ctrl+N` - New Session
+- `Ctrl+C` - Exit
+- `Up/Down` - Cycle Prompt History
+
+**Slash Commands:**
+- `/skills` - Manage skills
+- `/auth` - Connect AI providers
+- `/help` - Show all commands
+
+### Web UI
+
+Start the web interface:
+
+```bash
+jarvis web --port 5533
+```
+
+**Access at:** http://localhost:5533
+
+**Features:**
+- Modern chat interface
+- Integrated terminal
+- Settings panel
+- Session management
+- Model selector
+- File operations
+
+### Desktop App
+
+Launch the Electron desktop app:
+
+```bash
+jarvis electron
+```
+
+**Requirements:**
+- Electron installed (`npm install -g electron`)
+
+**Features:**
+- Native window controls
+- System tray integration
+- All web UI features
+
+## 🧠 Brain System
+
+Customize JARVIS's core identity and behavior:
+
+### Via Web UI (Recommended)
+1. Open `jarvis web`
+2. Click Settings (⚙️)
+3. Go to **Brain** tab
+4. Edit JARVIS.md
+5. Click **Commit** to save
+
+### Via File
+Edit `JARVIS.md` in your project directory:
+
+```markdown
+# JARVIS - Just A Rather Very Intelligent System
+
+You are JARVIS, an advanced AI coding assistant...
+
+## Core Principles
+- Be precise and thorough
+- Explain your reasoning
+- Prioritize security
+```
+
+Changes apply to all new conversations.
+
+## 📚 Skills System
+
+JARVIS includes 10+ skill categories:
+
+- **DevOps & Infrastructure** - Linux, Docker, Proxmox
+- **Security & Hacking** - Penetration testing, network security
+- **Software Development** - TypeScript, React, APIs
+- **Automation & Scripting** - SSH, CI/CD pipelines
+- **Database Management** - PostgreSQL, Redis
+- **Monitoring & Observability** - Logging, metrics
+
+### Customize Skills
+
+1. Open Settings → Intelligence tab
+2. Edit `skills.md`
+3. Add your own skills using markdown:
+
+```markdown
+### Your Skill Name
+- Skill description
+- Key capabilities
+- Best practices
+```
+
+## 🔐 OAuth Configuration
+
+Perfect for container deployments with Cloudflare Tunnel:
+
+### Setup Custom OAuth Callback
+
+1. **Configure in JARVIS:**
+   - Settings → Accounts → OAuth Callback Configuration
+   - Enter: `https://jarvis.yourdomain.com/oauth-callback`
+   - Save
+
+2. **Configure Cloudflare Tunnel:**
+```yaml
+# ~/.cloudflared/config.yml
+ingress:
+  - hostname: jarvis.yourdomain.com
+    service: http://localhost:5533
+  
+  - hostname: jarvis.yourdomain.com
+    path: /oauth-callback
+    service: http://localhost:51121
+```
+
+3. **Test OAuth:**
+   - Settings → Accounts → Link Google
+   - Should redirect to your custom domain
+
+### Environment Variable
+```bash
+export JARVIS_OAUTH_CALLBACK_URL="https://jarvis.yourdomain.com/oauth-callback"
+jarvis web
+```
+
+## 🐳 Container Deployment
+
+### Docker
+
+```dockerfile
+FROM oven/bun:1
+
+WORKDIR /app
+
+# Install JARVIS
+RUN npm install -g @benzsiangco/jarvis
+
+# Expose ports
+EXPOSE 5533 51121
+
+# Start web UI
+CMD ["jarvis", "web"]
+```
 
+Run:
 ```bash
-npm install -g git+https://github.com/benzsiangco/jarvis.git
+docker build -t jarvis .
+docker run -p 5533:5533 -p 51121:51121 \
+  -e JARVIS_OAUTH_CALLBACK_URL="https://jarvis.yourdomain.com/oauth-callback" \
+  jarvis
 ```
 
-## Usage
+### Docker Compose
 
-Simply run:
+```yaml
+version: '3.8'
+services:
+  jarvis:
+    image: oven/bun:1
+    ports:
+      - "5533:5533"
+      - "51121:51121"
+    environment:
+      - JARVIS_OAUTH_CALLBACK_URL=https://jarvis.yourdomain.com/oauth-callback
+    command: >
+      sh -c "npm install -g @benzsiangco/jarvis && jarvis web"
+```
+
+## 🛠️ CLI Commands
 
 ```bash
+# Terminal UI (default)
 jarvis
+jarvis tui
+
+# Web UI
+jarvis web [--port 5533]
+
+# Desktop app
+jarvis electron
+
+# Single prompt
+jarvis run "your question here"
+
+# Account management
+jarvis auth
+
+# List providers
+jarvis providers
+
+# List models
+jarvis models
+
+# Configuration
+jarvis config [--show] [--path]
+
+# Sessions
+jarvis sessions [--list] [--clear]
+
+# Initialize project
+jarvis init
+```
+
+## ⚙️ Configuration
+
+### Global Config Location
+
+- **Linux/macOS:** `~/.config/jarvis/config.json`
+- **Windows:** `%APPDATA%\jarvis\config.json`
+
+### View Config
+```bash
+jarvis config --show
+```
+
+### Edit Config
+Via Web UI: Settings → Config tab
+
+Or edit directly:
+```json
+{
+  "model": "gpt-4o",
+  "persona": "hacker",
+  "oauth": {
+    "callbackUrl": "https://jarvis.yourdomain.com/oauth-callback"
+  }
+}
+```
+
+## 🤖 Supported AI Providers
+
+- **OpenAI** - GPT-4, GPT-4 Turbo, GPT-3.5
+- **Anthropic** - Claude 3.5 Sonnet, Claude 3 Opus
+- **Google** - Gemini 1.5 Pro, Gemini 1.5 Flash
+- **Local** - Ollama, LM Studio
+
+### Connect Provider
+
+**Via Web UI:**
+1. Settings → Accounts
+2. Click "Setup Key" or "Link Google"
+3. Enter API key or authenticate
+
+**Via CLI:**
+```bash
+jarvis auth
 ```
 
-This will launch the Terminal User Interface (TUI) where you can:
-- Chat with AI models (Claude, GPT-4, Gemini, etc.)
-- Use slash commands (Type `/` to see options)
-- Manage skills (`/skills`)
-- Connect accounts (`/auth` or via menu)
+## 🔧 Built-in Tools
 
-## Key Bindings
+JARVIS has 12 powerful tools:
 
-- **Ctrl+P**: Open Commands Menu
-- **Ctrl+T**: Switch Model Variants (if available)
-- **Ctrl+L**: Clear Chat
-- **Ctrl+N**: New Session
-- **Ctrl+C**: Exit (with summary)
-- **Up/Down**: Cycle Prompt History
+- `bash` - Execute shell commands
+- `read` - Read file contents
+- `write` - Create/overwrite files
+- `edit` - Edit existing files
+- `glob` - Find files by pattern
+- `grep` - Search file contents
+- `list` - List directory contents
+- `webfetch` - Fetch web content
+- `task` - Spawn sub-agents
+- `question` - Ask user questions
+- `todoread` - Read todo list
+- `todowrite` - Manage todos
 
-## Development
+View in: Settings → Tools tab
 
-To install dependencies:
+## 📦 Package Details
 
+**Size:**
+- CLI Only: 3.5 MB
+- With Electron: ~200 MB
+
+**What's Included:**
+- Complete source code
+- Web UI (built)
+- Electron app (compiled)
+- CLI bundle
+- Enhanced skills
+- Documentation
+
+## 🧪 Development
+
+### Prerequisites
+- [Bun](https://bun.sh) runtime
+- Node.js 20+
+- TypeScript 5+
+
+### Install Dependencies
 ```bash
+git clone https://github.com/benzsiangco/jarvis.git
+cd jarvis
 bun install
 ```
 
-To run in development:
+### Development Mode
+```bash
+bun run dev          # TUI
+bun run web          # Web UI dev server
+bun run electron:dev # Electron dev mode
+```
+
+### Build
+```bash
+bun run build              # CLI bundle
+bun run web:build          # Web UI
+bun run electron:compile   # Electron app
+```
 
+### Run Tests
 ```bash
-bun run dev
+bun run typecheck
 ```
 
-To build:
+## 📚 Documentation
 
+- [Installation Guide](./INSTALLATION.md) - Detailed installation instructions
+- [Quick Reference](./QUICK_REFERENCE_v1.1.0.md) - Quick start guide
+- [Release Notes](./RELEASE_v1.1.0.md) - Version history
+- [Changelog](./CHANGELOG.md) - All changes
+
+## 🆘 Troubleshooting
+
+### Electron not found
 ```bash
-bun run build
+npm install -g electron
+jarvis electron
 ```
+
+### OAuth callback not working
+- Ensure server binds to `0.0.0.0` (automatic in v1.1.0+)
+- Check Cloudflare Tunnel routes `/oauth-callback` to port 51121
+- Verify firewall allows port 51121
+
+### Brain/Skills not applying
+- Click "Commit" to save changes in Settings
+- Start new conversation to see changes
+- Check console for errors
+
+### Web UI won't start
+```bash
+# Check if Bun is installed
+bun --version
+
+# Install Bun if needed
+curl -fsSL https://bun.sh/install | bash
+```
+
+## 🌟 What's New
+
+### v1.1.1 (Latest)
+- ✅ `jarvis electron` command
+- ✅ Electron as optional dependency
+- ✅ Installation guide
+- ✅ Better error messages
+
+### v1.1.0
+- ✅ Brain System (JARVIS.md editor)
+- ✅ OAuth Callback Configuration
+- ✅ Enhanced Skills (10+ categories)
+- ✅ Tools Tab in Settings
+
+### v1.0.x
+- ✅ Initial release
+- ✅ TUI, Web, Desktop modes
+- ✅ Multi-provider support
+
+## 🤝 Contributing
+
+Contributions welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## 📄 License
+
+MIT License - see [LICENSE](./LICENSE) file for details
+
+## 🔗 Links
+
+- **NPM Package:** https://www.npmjs.com/package/@benzsiangco/jarvis
+- **GitHub:** https://github.com/benzsiangco/jarvis
+- **Issues:** https://github.com/benzsiangco/jarvis/issues
+- **Releases:** https://github.com/benzsiangco/jarvis/releases
+
+## 💡 Tips
+
+**Customize Brain:**
+```bash
+jarvis web
+# Settings → Brain → Edit JARVIS.md
+```
+
+**Add Domain Skills:**
+```bash
+# Settings → Intelligence → Edit skills.md
+```
+
+**Deploy with Custom Domain:**
+```bash
+# Settings → Accounts → OAuth Config
+# Enter: https://jarvis.yourdomain.com/oauth-callback
+```
+
+**Use Desktop App:**
+```bash
+npm install -g @benzsiangco/jarvis electron
+jarvis electron
+```
+
+---
+
+**Made with ❤️ by Benz Siangco**
+
+For help: `jarvis --help` or visit [Documentation](./INSTALLATION.md)