@qduc/term2 0.1.0

package/dist/utils/streaming-updater.js

@@ -0,0 +1,41 @@
+import { createThrottledFunction } from './throttle.js';
+export const createStreamingUpdateCoordinator = (onUpdate, intervalMs) => {
+    let lastEmitted = null;
+    const throttled = createThrottledFunction((...args) => {
+        if (lastEmitted && args.length === lastEmitted.length) {
+            let isDuplicate = true;
+            for (let i = 0; i < args.length; i += 1) {
+                if (args[i] !== lastEmitted[i]) {
+                    isDuplicate = false;
+                    break;
+                }
+            }
+            if (isDuplicate) {
+                return;
+            }
+        }
+        lastEmitted = args;
+        onUpdate(...args);
+    }, intervalMs);
+    const push = (...args) => {
+        if (lastEmitted && args.length === lastEmitted.length) {
+            let isDuplicate = true;
+            for (let i = 0; i < args.length; i += 1) {
+                if (args[i] !== lastEmitted[i]) {
+                    isDuplicate = false;
+                    break;
+                }
+            }
+            if (isDuplicate) {
+                return;
+            }
+        }
+        throttled.throttled(...args);
+    };
+    return {
+        push,
+        flush: throttled.flush,
+        cancel: throttled.cancel,
+    };
+};
+//# sourceMappingURL=streaming-updater.js.map

package/dist/utils/streaming-updater.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-updater.js","sourceRoot":"","sources":["../../source/utils/streaming-updater.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,uBAAuB,EAAC,MAAM,eAAe,CAAC;AAQtD,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAC5C,QAAiC,EACjC,UAAkB,EACc,EAAE;IAClC,IAAI,WAAW,GAAgB,IAAI,CAAC;IAEpC,MAAM,SAAS,GAAG,uBAAuB,CAAC,CAAC,GAAG,IAAU,EAAE,EAAE;QACxD,IAAI,WAAW,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,CAAC,MAAM,EAAE,CAAC;YACpD,IAAI,WAAW,GAAG,IAAI,CAAC;YACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;gBACtC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC7B,WAAW,GAAG,KAAK,CAAC;oBACpB,MAAM;gBACV,CAAC;YACL,CAAC;YACD,IAAI,WAAW,EAAE,CAAC;gBACd,OAAO;YACX,CAAC;QACL,CAAC;QACD,WAAW,GAAG,IAAI,CAAC;QACnB,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;IACtB,CAAC,EAAE,UAAU,CAAC,CAAC;IAEf,MAAM,IAAI,GAAG,CAAC,GAAG,IAAU,EAAE,EAAE;QAC3B,IAAI,WAAW,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,CAAC,MAAM,EAAE,CAAC;YACpD,IAAI,WAAW,GAAG,IAAI,CAAC;YACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;gBACtC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC7B,WAAW,GAAG,KAAK,CAAC;oBACpB,MAAM;gBACV,CAAC;YACL,CAAC;YACD,IAAI,WAAW,EAAE,CAAC;gBACd,OAAO;YACX,CAAC;QACL,CAAC;QACD,SAAS,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC;IACjC,CAAC,CAAC;IAEF,OAAO;QACH,IAAI;QACJ,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,MAAM,EAAE,SAAS,CAAC,MAAM;KAC3B,CAAC;AACN,CAAC,CAAC"}

package/dist/utils/throttle.d.ts

@@ -0,0 +1,7 @@
+export type ThrottledFunction<Args extends unknown[]> = {
+    throttled: (...args: Args) => void;
+    flush: () => void;
+    cancel: () => void;
+};
+export declare const createThrottledFunction: <Args extends unknown[]>(fn: (...args: Args) => void, intervalMs: number) => ThrottledFunction<Args>;
+//# sourceMappingURL=throttle.d.ts.map

package/dist/utils/throttle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.d.ts","sourceRoot":"","sources":["../../source/utils/throttle.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,CAAC,IAAI,SAAS,OAAO,EAAE,IAAI;IACpD,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IACnC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,MAAM,EAAE,MAAM,IAAI,CAAC;CACtB,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,IAAI,SAAS,OAAO,EAAE,EAC1D,IAAI,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,EAC3B,YAAY,MAAM,KACnB,iBAAiB,CAAC,IAAI,CAkDxB,CAAC"}

package/dist/utils/throttle.js

@@ -0,0 +1,49 @@
+export const createThrottledFunction = (fn, intervalMs) => {
+    let lastCallTime = 0;
+    let timeout = null;
+    let pendingArgs = null;
+    const invoke = () => {
+        if (!pendingArgs)
+            return;
+        const args = pendingArgs;
+        pendingArgs = null;
+        lastCallTime = Date.now();
+        fn(...args);
+    };
+    const schedule = (delayMs) => {
+        if (timeout)
+            return;
+        timeout = setTimeout(() => {
+            timeout = null;
+            invoke();
+        }, delayMs);
+    };
+    const throttled = (...args) => {
+        pendingArgs = args;
+        if (timeout)
+            return;
+        const now = Date.now();
+        const elapsed = now - lastCallTime;
+        if (elapsed >= intervalMs) {
+            invoke();
+            return;
+        }
+        schedule(intervalMs - elapsed);
+    };
+    const flush = () => {
+        if (timeout) {
+            clearTimeout(timeout);
+            timeout = null;
+        }
+        invoke();
+    };
+    const cancel = () => {
+        if (timeout) {
+            clearTimeout(timeout);
+            timeout = null;
+        }
+        pendingArgs = null;
+    };
+    return { throttled, flush, cancel };
+};
+//# sourceMappingURL=throttle.js.map

package/dist/utils/throttle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.js","sourceRoot":"","sources":["../../source/utils/throttle.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACnC,EAA2B,EAC3B,UAAkB,EACK,EAAE;IACzB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,OAAO,GAAyC,IAAI,CAAC;IACzD,IAAI,WAAW,GAAgB,IAAI,CAAC;IAEpC,MAAM,MAAM,GAAG,GAAG,EAAE;QAChB,IAAI,CAAC,WAAW;YAAE,OAAO;QACzB,MAAM,IAAI,GAAG,WAAW,CAAC;QACzB,WAAW,GAAG,IAAI,CAAC;QACnB,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC1B,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAChB,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG,CAAC,OAAe,EAAE,EAAE;QACjC,IAAI,OAAO;YAAE,OAAO;QACpB,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE;YACtB,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,EAAE,CAAC;QACb,CAAC,EAAE,OAAO,CAAC,CAAC;IAChB,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,CAAC,GAAG,IAAU,EAAE,EAAE;QAChC,WAAW,GAAG,IAAI,CAAC;QACnB,IAAI,OAAO;YAAE,OAAO;QACpB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,GAAG,GAAG,YAAY,CAAC;QACnC,IAAI,OAAO,IAAI,UAAU,EAAE,CAAC;YACxB,MAAM,EAAE,CAAC;YACT,OAAO;QACX,CAAC;QACD,QAAQ,CAAC,UAAU,GAAG,OAAO,CAAC,CAAC;IACnC,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,GAAG,EAAE;QACf,IAAI,OAAO,EAAE,CAAC;YACV,YAAY,CAAC,OAAO,CAAC,CAAC;YACtB,OAAO,GAAG,IAAI,CAAC;QACnB,CAAC;QACD,MAAM,EAAE,CAAC;IACb,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,GAAG,EAAE;QAChB,IAAI,OAAO,EAAE,CAAC;YACV,YAAY,CAAC,OAAO,CAAC,CAAC;YACtB,OAAO,GAAG,IAAI,CAAC;QACnB,CAAC;QACD,WAAW,GAAG,IAAI,CAAC;IACvB,CAAC,CAAC;IAEF,OAAO,EAAC,SAAS,EAAE,KAAK,EAAE,MAAM,EAAC,CAAC;AACtC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,108 @@
+{
+    "name": "@qduc/term2",
+    "version": "0.1.0",
+    "description": "A terminal-based AI assistant that can help you get things done on your computer",
+    "license": "MIT",
+    "author": "qduc",
+    "keywords": [
+        "ai",
+        "assistant",
+        "cli",
+        "terminal",
+        "openai",
+        "agent",
+        "chat",
+        "gpt"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/qduc/term2.git"
+    },
+    "homepage": "https://github.com/qduc/term2",
+    "bugs": {
+        "url": "https://github.com/qduc/term2/issues"
+    },
+    "bin": {
+        "term2": "dist/cli.js"
+    },
+    "type": "module",
+    "engines": {
+        "node": ">=16"
+    },
+    "scripts": {
+        "start": "node dist/cli.js",
+        "build": "tsc && npm run post-build",
+        "dev": "tsc --watch",
+        "test": "DISABLE_LOGGING=1 ava --reporter=min | grep -v '✔'",
+        "test:verbose": "tsc && ava",
+        "lint": "prettier --check .",
+        "lint-fix": "prettier --write .",
+        "post-build": "cp -r source/prompts dist/",
+        "prepublishOnly": "npm run build && npm test",
+        "logs": "node tools/log_viewer/src/server.js"
+    },
+    "files": [
+        "dist"
+    ],
+    "dependencies": {
+        "@openai/agents": "^0.3.3",
+        "@types/ssh2": "^1.15.5",
+        "bash-parser": "^0.5.0",
+        "env-paths": "^3.0.0",
+        "fast-glob": "^3.3.2",
+        "fuse.js": "^7.0.0",
+        "ignore": "^5.3.2",
+        "ink": "^6.5.1",
+        "ink-prompt": "^0.1.7",
+        "marked": "^17.0.1",
+        "meow": "^11.0.0",
+        "openai": "^6.9.1",
+        "react": "^19.0.0",
+        "ssh2": "^1.17.0",
+        "winston": "^3.18.3",
+        "winston-daily-rotate-file": "^5.0.0",
+        "zod": "^4.1.13"
+    },
+    "devDependencies": {
+        "@ava/typescript": "^6.0.0",
+        "@babel/cli": "^7.21.0",
+        "@babel/preset-react": "^7.18.6",
+        "@types/env-paths": "^1.0.2",
+        "@types/marked": "^5.0.2",
+        "@types/node": "^24.10.1",
+        "@types/react": "^19.0.0",
+        "ava": "^6.4.1",
+        "chalk": "^5.2.0",
+        "eslint-config-xo-react": "^0.27.0",
+        "eslint-plugin-react": "^7.32.2",
+        "eslint-plugin-react-hooks": "^4.6.0",
+        "import-jsx": "^5.0.0",
+        "ink-testing-library": "^4.0.0",
+        "prettier": "^2.8.7",
+        "tsx": "^4.20.6",
+        "typescript": "^5.9.3"
+    },
+    "ava": {
+        "environmentVariables": {
+            "NODE_NO_WARNINGS": "1",
+            "DISABLE_LOGGING": "1"
+        },
+        "typescript": {
+            "rewritePaths": {
+                "source/": "dist/"
+            },
+            "compile": "tsc"
+        }
+    },
+    "xo": {
+        "extends": "xo-react",
+        "prettier": true,
+        "ignores": [
+            "**/*.test.js"
+        ],
+        "rules": {
+            "react/prop-types": "off",
+            "unicorn/expiring-todo-comments": "off"
+        }
+    }
+}

package/readme.md

@@ -0,0 +1,428 @@
+# term2
+
+[![npm version](https://img.shields.io/npm/v/term2.svg)](https://www.npmjs.com/package/term2)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/term2.svg)](https://nodejs.org)
+
+A powerful terminal-based AI assistant that helps you get things done on your computer through natural conversation.
+
+## Features
+
+-   🤖 **Multi-Provider Support** - Works with OpenAI, OpenRouter, and OpenAI-compatible APIs
+-   🔒 **Safe Execution** - Every command requires your explicit approval with diff preview
+-   🛠️ **Advanced Tools** - Shell execution, file patching, search/replace, grep, find files, file reading, web search, and mentor consultation
+-   💬 **Slash Commands** - Quick actions like `/clear`, `/quit`, `/model`, `/setting` for easy control
+-   📝 **Smart Context** - The assistant understands your environment and provides relevant help
+-   🎯 **Streaming Responses** - See the AI's thoughts and reasoning in real-time
+-   🧠 **Reasoning Effort Control** - Configurable reasoning levels (minimal to high) for O1/O3 models
+-   ⚡ **Command History** - Navigate previous inputs with arrow keys
+-   🎨 **Markdown Rendering** - Formatted code blocks and text in the terminal
+-   🔄 **Retry Logic** - Automatic recovery from tool hallucinations and upstream errors
+-   🌐 **SSH Mode** - Execute commands and edit files on remote servers over SSH
+
+## Demo
+
+<!-- Add a demo GIF or screenshot here -->
+
+```
+$ term2
+You: What files are in my current directory?
+Assistant: I'll list the files for you.
+
+📋 Command to execute:
+ls -la
+
+Approve? (y/n): y
+...
+```
+
+## Installation
+
+**Requirements:**
+
+-   Node.js 16 or higher
+-   An API key from OpenAI, OpenRouter, or any OpenAI-compatible provider
+
+Install globally via npm:
+
+```bash
+npm install --global term2
+```
+
+Set your API key as an environment variable:
+
+```bash
+# For OpenAI (default)
+export OPENAI_API_KEY="your-api-key-here"
+
+# For OpenRouter
+export TERM2_AGENT_PROVIDER="openrouter"
+export TERM2_AGENT_OPENROUTER_API_KEY="your-openrouter-key"
+```
+
+To make it permanent, add the export to your shell configuration file (`~/.bashrc`, `~/.zshrc`, or `~/.profile`).
+
+## Usage
+
+Start the assistant:
+
+```bash
+term2
+```
+
+Then simply chat with the AI! Type your question or request, press Enter, and the assistant will help you.
+
+### Basic Examples
+
+```
+"What files are in my current directory?"
+"Show me my git status"
+"Create a backup of my documents folder"
+"What's using port 3000?"
+```
+
+### Advanced Examples
+
+```
+"Find all TODO comments in my JavaScript files"
+"Help me debug why my server won't start on port 8080"
+"Create a new React component called UserProfile"
+"Show me the disk usage of my home directory"
+"What processes are consuming the most memory?"
+"Search for the word 'config' in all .json files"
+```
+
+### Command Line Options
+
+```bash
+term2                           # Start with default model (gpt-5.1)
+term2 -m gpt-4o                # Use a specific model
+term2 --model gpt-4o-mini      # Use GPT-4o mini for faster/cheaper responses
+term2 -r high                  # Set reasoning effort to high (for O1/O3 models)
+term2 --reasoning medium       # Set reasoning effort to medium
+term2 --lite                   # Start in lite mode (session-only, minimal context)
+
+# SSH Mode - execute on remote servers
+term2 --ssh user@host --remote-dir /path/to/project
+term2 --ssh deploy@server.com --remote-dir /var/www/app --ssh-port 2222
+
+# Combine SSH with lite mode for remote terminal assistance
+term2 --ssh user@host --remote-dir /path --lite
+```
+
+### Slash Commands
+
+While in the chat, you can use these commands:
+
+-   `/clear` - Clear the conversation history
+-   `/quit` - Exit the application
+-   `/model [model-name]` - Switch to a different model
+-   `/mentor` - Toggle mentor mode (collaborative mode with mentor model)
+-   `/lite` - Toggle lite mode (minimal context, session-only)
+-   `/settings [key] [value]` - Modify runtime settings (e.g., `/settings agent.temperature 0.7`)
+
+## Configuration
+
+term2 stores its configuration in:
+
+-   **macOS**: `~/Library/Logs/term2-nodejs/settings.json`
+-   **Linux**: `~/.local/state/term2-nodejs/settings.json`
+
+You can also configure settings via environment variables (prefix with `TERM2_`):
+
+```bash
+# Agent settings
+export TERM2_AGENT_MODEL="gpt-4o"
+export TERM2_AGENT_PROVIDER="openai"  # or "openrouter"
+export TERM2_AGENT_REASONING_EFFORT="medium"  # none, minimal, low, medium, high, default
+export TERM2_AGENT_TEMPERATURE="0.7"  # 0.0 to 2.0
+export TERM2_AGENT_MAX_TURNS="100"
+export TERM2_AGENT_RETRY_ATTEMPTS="2"
+
+# Provider-specific settings
+export TERM2_AGENT_OPENROUTER_API_KEY="your-key"
+
+# Tool settings
+export TERM2_SHELL_TIMEOUT="180000"
+export TERM2_SHELL_MAX_OUTPUT_LINES="1000"
+
+# Web Search settings
+export TAVILY_API_KEY="tvly-..."      # Your Tavily API key
+export TERM2_WEBSEARCH_PROVIDER="tavily"  # Web search provider (default: tavily)
+
+# App settings
+export TERM2_APP_MODE="default"  # or "edit" for automatic patch approval
+
+# SSH settings (alternative to CLI flags)
+export TERM2_SSH_HOST="user@server.com"
+export TERM2_SSH_PORT="22"
+export TERM2_SSH_REMOTE_DIR="/path/to/project"
+```
+
+## How It Works
+
+1. You type a message and press Enter
+2. The AI analyzes your request and determines if it needs to execute commands
+3. If a command is needed, you'll see a preview and approval prompt
+4. After approval, the command runs and results are shown
+5. The AI uses the results to provide a helpful response
+6. You stay in full control - reject any command with 'n'
+
+## SSH Mode
+
+SSH mode enables term2 to execute commands and modify files on remote servers over SSH. This is useful for managing remote deployments, debugging server issues, or working on remote development environments.
+
+### Requirements
+
+- SSH agent running with your keys loaded (`ssh-add`)
+- SSH access to the target server
+- `--remote-dir` is required to specify the working directory (optional in lite mode - will auto-detect)
+
+### Usage
+
+```bash
+# Basic usage
+term2 --ssh user@hostname --remote-dir /path/to/project
+
+# With custom SSH port
+term2 --ssh user@hostname --remote-dir /path/to/project --ssh-port 2222
+
+# With lite mode (auto-detects remote directory)
+term2 --ssh user@hostname --lite
+```
+
+### How It Works
+
+When SSH mode is enabled:
+1. term2 establishes an SSH connection using your SSH agent for authentication
+2. All shell commands are executed on the remote server via SSH
+3. File operations (read, write, patch) are performed remotely using shell commands (`cat`, heredocs)
+4. The working directory is set to `--remote-dir` on the remote server
+5. The connection is automatically closed when you exit term2
+
+### Combining with Lite Mode
+
+SSH mode works seamlessly with lite mode for lightweight remote terminal assistance:
+
+```bash
+term2 --ssh user@host --remote-dir /path/to/project --lite
+```
+
+This combination provides:
+- Remote command execution over SSH
+- Read-only tools (grep, find_files, read_file) for exploration
+- Minimal context and faster responses
+- No file editing tools (safer for production servers)
+
+### Limitations
+
+- Authentication is via SSH agent only (no password prompts)
+- Binary file operations are not supported (text files only)
+- Large file transfers may be slower than local operations
+
+## Safety Features
+
+-   **Command Approval** - Every destructive operation requires your explicit confirmation
+-   **Diff Preview** - See exact file changes before approving patches or edits
+-   **Risk Analysis** - Dangerous operations (like `rm -rf`, `git push --force`) are flagged
+-   **Path Safety** - Operations on sensitive directories require extra caution
+-   **Dry-Run Validation** - Patches are validated before approval to prevent errors
+-   **No Hidden Actions** - All tool usage is transparent and visible
+-   **Retry Limits** - Automatic abort after consecutive tool failures (default: 3)
+
+## Available Tools
+
+The AI assistant has access to these tools to help you:
+
+### Shell Tool
+Execute shell commands with safety validation:
+- Detects dangerous patterns (`rm -rf`, force operations)
+- Validates paths to prevent operations on sensitive directories
+- Configurable timeout and output limits
+- Requires explicit approval before execution
+
+### Apply Patch Tool
+Apply file changes using unified diff format:
+- Create new files or update existing ones
+- Dry-run validation before approval
+- Clear diff preview showing exact changes
+- Supports "edit mode" for automatic approval
+
+### Search & Replace Tool
+Find and replace text in files:
+- Exact match with fallback to line-by-line matching
+- Diff generation for user preview
+- Single or multiple replacements
+- Requires approval before making changes
+
+### Grep Tool
+Search codebase for patterns:
+- Uses ripgrep when available (fast!)
+- Supports regex patterns
+- Respects .gitignore
+- Read-only operation (no approval needed)
+
+### Ask Mentor Tool
+Consult a smarter model for advice:
+- Query a different/better model for complex questions
+- Configurable mentor model via settings
+- Useful for getting second opinions
+
+### Find Files Tool
+Search for files in the workspace:
+- High-performance file search using `fd`
+- Supports glob patterns and exclusions
+- Respects `.gitignore` by default
+
+### Read File Tool
+Read file contents with precision:
+- Read entire files or specific line ranges
+- Optimizes context usage for large files
+- Support for reading multiple files
+
+### Web Search Tool
+Search the web for information:
+- Uses Tavily API by default for web search
+- Converts results to markdown for readability
+- Pluggable architecture ready to swap in other providers (Serper, Brave, etc.)
+- Read-only operation (no approval needed)
+- Requires `TAVILY_API_KEY` environment variable or settings configuration
+
+
+## Supported Models
+
+term2 works with multiple AI providers:
+
+### OpenAI (default)
+-   `gpt-5.2` (latest)
+-   `gpt-5.1` (default)
+-   `gpt-5`
+-   `gpt-5-mini`
+-   `gpt-4.1`
+-   `gpt-4.1-mini`
+-   `gpt-4o`
+-   `gpt-4o-mini`
+-   `o3` (supports reasoning effort)
+-   `o3-mini` (supports reasoning effort)
+-   `o1` (supports reasoning effort)
+
+### OpenRouter
+Access hundreds of models through OpenRouter including:
+-   Claude models (Anthropic)
+-   Gemini models (Google)
+-   Open-source models (Deepseek, GLM, Minimax, Devstral, etc.)
+
+Set `TERM2_AGENT_PROVIDER="openrouter"` to use OpenRouter.
+
+### OpenAI-Compatible
+Any OpenAI-compatible API endpoint can be configured through runtime settings.
+
+## Development
+
+Want to contribute or run from source?
+
+```bash
+# Clone the repository
+git clone https://github.com/qduc/term2.git
+cd term2
+
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Run tests
+npm test
+
+# Build
+npm run build
+```
+
+## Troubleshooting
+
+### "OPENAI_API_KEY not set"
+
+Make sure you've exported your OpenAI API key:
+
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+### Command not found: term2
+
+After installation, you may need to restart your terminal or run:
+
+```bash
+source ~/.bashrc  # or ~/.zshrc
+```
+
+### Permission denied
+
+If you get permission errors during global installation, use:
+
+```bash
+sudo npm install --global term2
+```
+
+Or configure npm to install globally without sudo: https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally
+
+### SSH connection failed
+
+Make sure your SSH agent is running and has your keys loaded:
+
+```bash
+# Start SSH agent if not running
+eval "$(ssh-agent -s)"
+
+# Add your SSH key
+ssh-add ~/.ssh/id_rsa
+
+# Verify the key is loaded
+ssh-add -l
+```
+
+Also verify you can connect manually: `ssh user@hostname`
+
+### SSH mode: "remote-dir is required"
+
+When using `--ssh` without `--lite`, you must also specify `--remote-dir`:
+
+```bash
+term2 --ssh user@host --remote-dir /home/user/project
+```
+
+With `--lite` mode, `--remote-dir` is optional and will auto-detect:
+
+```bash
+term2 --ssh user@host --lite
+```
+
+## Tips
+
+-   The assistant won't run dangerous commands without your approval
+-   You can reject any command by pressing 'n' when prompted
+-   Press Ctrl+C to exit the chat at any time
+-   Use arrow keys to navigate through your command history
+-   Be specific in your requests for better results
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request or open an Issue on [GitHub](https://github.com/qduc/term2).
+
+## Acknowledgments
+
+Built with:
+
+-   [OpenAI Agents SDK](https://github.com/openai/openai-agents-js)
+-   [Ink](https://github.com/vadimdemedes/ink) - React for CLI
+-   [TypeScript](https://www.typescriptlang.org/)
+-   [ssh2](https://github.com/mscdex/ssh2) - SSH client for Node.js
+
+---
+
+Made with ❤️ by [qduc](https://github.com/qduc)