ys-code-agent 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YS Code Agent
+
+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,252 @@
+# ◆ YS Code Agent
+
+**AI-Powered Terminal Coding Assistant — Built for Termux, Engineered for Production**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](package.json)
+[![npm](https://img.shields.io/npm/v/ys-code-agent)](https://www.npmjs.com/package/ys-code-agent)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/YSCodex/YSCode/pulls)
+
+---
+
+## 🚀 One-Line Install
+
+```bash
+# Termux / Linux / macOS — install globally instantly
+npm install -g ys-code-agent
+
+# Or directly from GitHub
+npm install -g git+https://github.com/YSCodex/YSCode.git
+
+# Then just run:
+ys
+```
+
+**Termux one-liner (full setup):**
+```bash
+pkg update -y && pkg install nodejs git -y && npm install -g ys-code-agent && ys
+```
+
+---
+
+## ✨ Features
+
+### 🎯 Core Capabilities
+- **Multi-Provider AI**: OpenRouter (free), Anthropic Claude, OpenAI GPT-4o, Google Gemini, Groq, DeepSeek, Ollama
+- **50+ Slash Commands**: File ops, git, memory, code review, debugging, planning, workspace management
+- **Rich Terminal UI**: Boxed dashboard, command popup, syntax highlighting, colored diffs
+- **Global Install**: `npm install -g ys-code-agent` — use `ys` anywhere
+
+### 📁 File System
+- `/read` — Read files with line numbers and directory trees
+- `/edit` — AI-powered editing with colored diff preview & confirm
+- `/create` — Smart file creation with language templates
+- `/search` — Ripgrep-style codebase search with filters
+- `/refactor` — AI-driven code refactoring
+- `/watch` — Watch files for real-time changes
+- `/project-index` — Full project indexing for semantic search
+
+### 🌿 Git Integration
+- `/git status diff commit log branch push pull stash` — Full git workflow
+- `/git commit --ai` — AI generates conventional commit messages from diffs
+
+### 🧠 Project Memory
+- `/init` — Creates `.ys/` folder with YS.md project context
+- `/memory` — Persistent memory across sessions
+- `/remember` / `/forget` — Quick save/remove knowledge
+- `/dream` — AI consolidates conversation into memory
+
+### 🤖 AI Modes
+- `/plan` — Plan-only mode (AI creates steps, no code)
+- `/goal` — Fully autonomous execution with progress tracking
+- `/review` — Code review with categorized findings (bugs, security, performance)
+- `/review --pr` — PR review mode
+- `/debug` — Auto-debug with root cause analysis
+- `/arena` — Multi-model competition (compare outputs side-by-side)
+- `/agents` — 10 built-in sub-agents (Architect, Coder, Reviewer, etc.)
+
+### ⚙️ Power Features
+- **Approval Modes**: `safe` / `normal` / `yolo` (control autonomy)
+- **Background Tasks**: Run commands in parallel while chatting
+- **Session Export**: HTML, Markdown, JSON, JSONL
+- **Context Management**: Token usage tracking, auto-compression
+- **Workspace Manager**: Save/load/switch between project directories
+- **Vim Mode**: j/k/h/l keybindings for power users
+- **Self-Update**: `/update` pulls latest code and rebuilds
+- **Project Index**: Full codebase scanning with semantic search
+- **File Watcher**: Real-time file change monitoring
+- **Themes**: Dark, Light, Matrix (green-on-black)
+
+### 📱 Termux Optimized
+- Automatic detection of Android Termux
+- Low-RAM mode (< 2GB detected automatically)
+- Narrow/portrait terminal support (< 60 chars)
+- Battery-friendly (animations disabled on low-end devices)
+- SIGWINCH handling for orientation changes
+
+---
+
+## 🎮 Usage Examples
+
+```bash
+# Start interactive session
+ys
+
+# Read and edit files
+/read src/index.ts
+/edit src/auth.ts add JWT validation
+
+# Git workflow with AI commit messages
+/git status
+/git add .
+/git commit --ai
+
+# Plan and execute autonomously
+/plan Add dark mode toggle
+/goal Create REST API for todo app
+
+# Debug errors with root cause analysis
+/debug "TypeError: Cannot read property 'id'"
+
+# Code review
+/review src/api/routes.ts
+/review --pr 42
+
+# Project indexing
+/project-index
+/project-index --search "auth"
+
+# Workspace management
+/workspace save my-app
+/workspace load my-app
+
+# Watch files
+/watch src/
+
+# Export documentation
+/export html
+
+# Self-update
+/update
+
+# Vim keybindings
+/vim on
+
+# Change themes
+/theme matrix
+```
+
+[📖 Complete Usage Guide →](USAGE.md)
+
+---
+
+## 📦 How to Install
+
+### Global npm (recommended)
+
+```bash
+npm install -g ys-code-agent
+ys
+```
+
+### From GitHub
+
+```bash
+npm install -g git+https://github.com/YSCodex/YSCode.git
+ys
+```
+
+### From source
+
+```bash
+git clone https://github.com/YSCodex/YSCode.git
+cd YSCode
+npm install
+npm run build
+npm link  # makes `ys` available globally
+ys
+```
+
+### Termux (Android)
+
+```bash
+pkg update -y && pkg install nodejs git -y
+npm install -g ys-code-agent
+ys
+```
+
+---
+
+## 🔧 API Key Setup
+
+Set at least one API key to use the agent:
+
+```bash
+# OpenRouter (recommended — free models available)
+export OPENROUTER_API_KEY="sk-or-v1-xxxxxxxx"
+
+# Or set via CLI
+ys key openrouter sk-or-v1-xxxxxxxx
+```
+
+Free models: `google/gemma-4-31b-it:free`, `qwen/qwen-3-coder-32b:free`, `meta-llama/llama-3.3-70b-instruct:free`, `deepseek/deepseek-chat:free`
+
+---
+
+## 🖥️ Interface
+
+```
+╔══════════════════════════════════════════════════════╗
+║                  ◆ YS CODE AGENT ◆                  ║
+║          AI-Powered Terminal Coding Assistant        ║
+╠══════════════════════════════════════════════════════╣
+║  Provider  : OpenRouter          Model: gemma-4-31b ║
+║  Tools     : 18 Active           Mode : Normal      ║
+║  Memory    : ✓ Enabled           Git  : ✓ Connected ║
+╠══════════════════════════════════════════════════════╣
+║  💡 Type / for commands  |  ? for shortcuts         ║
+║  📁 Project: /home/user/myapp   (Node.js detected)  ║
+╚══════════════════════════════════════════════════════╝
+
+◆ ys [gemma-4-31b-it:free] ›
+```
+
+---
+
+## 📦 Architecture
+
+```
+ys-agent/
+├── src/
+│   ├── cli/          # CLI entry, interactive mode
+│   ├── ui/           # Terminal UI (welcome, popup, themes)
+│   ├── commands/     # 50+ slash command handlers
+│   ├── agent/        # Core AI agent loop
+│   ├── providers/    # 9 API providers
+│   ├── tools/        # 12 tool implementations
+│   ├── memory/       # Memory management
+│   ├── session/      # Session persistence
+│   └── config/       # Configuration system
+├── .ys/              # Auto-created project memory
+├── SETUP.md          # Setup guide
+├── USAGE.md          # Usage guide
+└── LICENSE           # MIT License
+```
+
+---
+
+## 🔧 Requirements
+
+- **Node.js** ≥ 22.0.0
+- **npm** ≥ 10.0
+- One API key (OpenRouter recommended for free tier)
+
+---
+
+## 📄 License
+
+MIT © 2026 YS Code Agent. See [LICENSE](LICENSE).
+
+---
+
+*Built for developers who code from their phones.*

package/SETUP.md

@@ -0,0 +1,228 @@
+# YS Code Agent — Setup Guide
+
+> Version 2.0 | MIT License 2026
+
+---
+
+## Prerequisites
+
+- **Node.js** >= 22.0.0 (recommended: 22.12+)
+- **npm** >= 10.0
+- A terminal emulator (Termux on Android, or any standard terminal on Linux/macOS)
+
+---
+
+## Quick Install
+
+### Option 1: Global npm install (recommended)
+
+```bash
+# Clone the repository
+git clone https://github.com/YSCodex/YSCode.git
+cd YSCode
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Link globally (makes `ys` available everywhere)
+npm link
+
+# Or install globally directly
+npm install -g .
+```
+
+### Option 2: Direct execution
+
+```bash
+# Run without installing globally
+node dist/cli/index.cjs
+```
+
+### Option 3: Termux (Android)
+
+```bash
+# Install Node.js in Termux
+pkg update && pkg upgrade
+pkg install nodejs git
+
+# Clone and setup
+git clone https://github.com/YSCodex/YSCode.git
+cd YSCode
+npm install
+npm run build
+npm link
+
+# Optional: run setup script for Termux optimizations
+bash scripts/setup-termux.sh
+```
+
+---
+
+## API Key Configuration
+
+YS Code Agent needs at least one API key to function. Set one of these environment variables:
+
+### OpenRouter (recommended — free models available)
+
+```bash
+export OPENROUTER_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"
+```
+
+Free models available:
+- `google/gemma-4-31b-it:free` (default)
+- `qwen/qwen-3-coder-32b:free`
+- `meta-llama/llama-3.3-70b-instruct:free`
+- `deepseek/deepseek-chat:free`
+
+### Other providers
+
+```bash
+# Anthropic (Claude)
+export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"
+
+# OpenAI (GPT-4o, GPT-4o-mini)
+export OPENAI_API_KEY="sk-xxxxxxxx"
+
+# Google (Gemini)
+export GOOGLE_API_KEY="AIzaxxxxxxxx"
+
+# Groq (fastest inference)
+export GROQ_API_KEY="gsk_xxxxxxxx"
+
+# DeepSeek
+export DEEPSEEK_API_KEY="sk-xxxxxxxx"
+
+# Local Ollama
+export OLLAMA_HOST="http://localhost:11434"
+```
+
+### Set key via CLI (alternative)
+
+```bash
+ys key openrouter sk-or-v1-xxxxxxxxxxxx
+```
+
+---
+
+## Quick Start
+
+```bash
+# Start interactive mode
+ys
+
+# Or with a specific model
+ys --model google/gemma-4-31b-it:free
+
+# Or with a specific provider
+ys --provider openrouter
+
+# Execute a one-shot task
+ys run "Create a React component for a login form"
+
+# Run diagnostics
+ys doctor
+```
+
+---
+
+## First Run
+
+When you start `ys` for the first time:
+
+1. You'll see the welcome dashboard with system info
+2. Type `/` to see available commands
+3. Type your question or task to start coding
+4. Use `/help` for complete command reference
+
+### Tips for first-time users
+
+- Type `/?` or `/help files` to see file-related commands
+- Type `/provider` to check which AI providers are configured
+- Type `/doctor` to run a system diagnostic check
+- Type `/init` to create a `.ys/` project memory folder
+
+---
+
+## Platform-Specific Notes
+
+### Termux (Android)
+
+- YS Code Agent automatically detects Termux and optimizes UI
+- Narrow terminal mode activates if width < 60 characters
+- Animations are disabled on low-RAM devices (< 2GB)
+- Use portrait mode for best experience on phones
+
+### Linux / macOS
+
+- All features fully supported
+- 256-color terminal recommended
+- `Ctrl+X` opens external editor ($EDITOR or nano)
+
+### Windows
+
+- Best used via WSL2 or Git Bash
+- Some ANSI features may require Windows Terminal
+
+---
+
+## Updating
+
+```bash
+# Pull latest changes
+git pull origin main
+
+# Rebuild
+npm run build
+```
+
+---
+
+## Troubleshooting
+
+### "No API key configured"
+Set one of the environment variables listed above or use `/key <provider> <api_key>`.
+
+### "Provider not found"
+Run `/provider` to list available providers. Use `/provider <name>` to switch.
+
+### Build fails
+- Ensure Node.js >= 22.0.0: `node --version`
+- Clear npm cache: `npm cache clean --force`
+- Delete node_modules and reinstall: `rm -rf node_modules && npm install`
+
+### Termux issues
+- Run `bash scripts/setup-termux.sh` for Android-specific fixes
+- Ensure `pkg update` was run recently
+
+---
+
+## Project Structure
+
+```
+ys-agent/
+├── src/
+│   ├── cli/          # CLI entry, interactive mode, agent manager
+│   ├── ui/           # Terminal UI (welcome, popup, themes)
+│   ├── commands/     # Slash command handlers
+│   ├── agent/        # Core AI agent loop
+│   ├── providers/    # API providers (OpenRouter, Anthropic, etc.)
+│   ├── tools/        # Tool system (read/write/edit/git/search)
+│   ├── memory/       # Memory management
+│   ├── session/      # Session persistence
+│   ├── config/       # Configuration system
+│   └── utils/        # Utilities
+├── dist/             # Compiled output
+├── .ys/              # Auto-created project memory
+└── scripts/          # Build & setup scripts
+```
+
+---
+
+## Need Help?
+
+- Type `/?` or `/help` inside the agent
+- Run `/doctor` for system diagnostics
+- Visit the GitHub repository for issues