@agiflowai/agent-cli 0.0.6 → 0.0.8

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.0.8
+Update:
+- Add `claude --standalone` command to support launching claude without backend connection.
+
+## 0.0.7
+Add:
+- Add `router` command to enable switching provider to openai chatgpt sub.
+Update:
+- Launch `claude` command independently which can be dynamically switch model between gpt and claude.
+
 ## 0.0.6
 - Launch Claude code npm package instead of native binary.
 

package/README.md

@@ -1,7 +1,17 @@
 # Agiflow Agent CLI
 
+[![GitHub](https://img.shields.io/badge/GitHub-AgiFlow%2Faicode--toolkit-blue?logo=github)](https://github.com/AgiFlow/aicode-toolkit)
+[![npm version](https://img.shields.io/npm/v/@agiflowai/agent-cli.svg)](https://www.npmjs.com/package/@agiflowai/agent-cli)
+[![License](https://img.shields.io/badge/License-Elastic--2.0-yellow.svg)](./LICENSE)
+
 @agiflowai/agent-cli - Command-line interface for connecting and managing AI agents (Claude Code, Gemini) with Agiflow remotely.
 
+**Note**:
+- For `agent-cli claude` and `agent-cli router` you don't need to authenticate with Agiflow server.
+- Use `agent-cli claude --standalone` to run Claude Code locally without any backend connection.
+
+**🔗 Related Project**: Check out the [AgiFlow AI Code Toolkit](https://github.com/AgiFlow/aicode-toolkit) - an open-source collection of AI development tools and utilities.  
+
 ## Quick Start
 
 ### Installation
@@ -18,18 +28,18 @@ npm install @agiflowai/agent-cli
 
 The CLI provides three main commands:
 
-#### 1. `agiflow connect` - Connect Daemon
+#### 1. `agent-cli connect` - Connect Daemon
 Connect your local machine to the Agiflow platform to receive remote commands.
 
 ```bash
 # Basic connection
-agiflow connect
+agent-cli connect
 
 # With custom server URL
-agiflow connect --server-url wss://your-server.com
+agent-cli connect --server-url wss://your-server.com
 
 # With verbose logging
-agiflow connect --verbose
+agent-cli connect --verbose
 ```
 
 **Options:**
@@ -39,19 +49,36 @@ agiflow connect --verbose
 - `--reconnect-interval <ms>` - Reconnection interval in milliseconds (default: 5000)
 - `--unique-instance` - Create unique daemon instance
 
-#### 2. `agiflow claude` - Launch Claude Agent
+#### 2. `agent-cli claude` - Launch Claude Agent
 Launch a Claude Code agent with full functionality.
 
 ```bash
-# Basic Claude agent launch (requires session ID)
-agiflow claude --agent-session-id your-session-id
+# Basic Claude agent launch in standalone mode (no backend)
+agent-cli claude --standalone
+
+# With backend connection (requires session ID)
+agent-cli claude --agent-session-id your-session-id
+
+# With custom alias for easy identification
+agent-cli claude \
+  --agent-session-id your-session-id \
+  --alias "my-dev-session"
 
 # With custom configuration
-agiflow claude \
+agent-cli claude \
   --agent-session-id your-session-id \
   --server-url wss://your-server.com \
   --working-directory /path/to/project \
   --verbose
+
+# With LLM routing to GPT-5
+agent-cli claude \
+  --llm-provider chatgpt \
+  --llm-model gpt-5 \
+  --alias "gpt5-experiment"
+
+# Standalone mode (no backend connection)
+agent-cli claude --standalone --verbose
 ```
 
 **Options:**
@@ -65,41 +92,232 @@ agiflow claude \
 - `-c, --agent-config <json>` - Agent configuration as JSON string
 - `--args <args...>` - Additional arguments to pass to Claude
 - `-v, --verbose` - Enable verbose logging
+- `--alias <alias>` - Custom session alias for easy identification
+- `--standalone` - Run in standalone mode without backend connection
 
-#### 3. `agiflow logout` - Clean Up Credentials
-Log out and clean up stored credentials.
+**LLM Routing Options:**
+- `--llm-provider <provider>` - LLM provider to route requests to (e.g., `chatgpt`, `openai`)
+- `--llm-model <model>` - LLM model to use (e.g., `gpt-5`, `gpt-5-codex`)
+
+**Note:** LLM routing configuration is saved to `~/.agiflow/sessions.json` and can be changed later using the `agent-cli router` command without restarting the agent.
+
+##### Standalone Mode
+
+Run Claude Code agent locally without connecting to the Agiflow backend server. This is useful for:
+- Development and testing
+- Running in environments without backend access
+- Privacy-focused local-only usage
+
+**Usage:**
 
 ```bash
-# Remove credential files only
-agiflow logout
+# Explicit standalone mode
+agent-cli claude --standalone
 
-# Remove entire .agiflow directory
-agiflow logout --remove-all
+# Standalone mode with verbose logging
+agent-cli claude --standalone --verbose
 
-# With verbose output
-agiflow logout --verbose
+# Standalone mode with custom working directory
+agent-cli claude --standalone --working-directory /path/to/project
+```
+
+**How It Works:**
+
+When `--standalone` is enabled:
+- ✅ Claude Code launches normally with full functionality
+- ✅ All local features work (file operations, code analysis, etc.)
+- ❌ No WebSocket connection to Agiflow backend
+- ❌ No remote session management
+- ❌ No backend authentication required
+
+**Automatic Standalone Detection:**
+
+If no server URL is configured (via `--server-url` or environment variables), the agent automatically runs in standalone mode even without the `--standalone` flag.
+
+##### Running Claude with ChatGPT/OpenAI
+
+You can route Claude Code requests to ChatGPT/OpenAI using the LLM routing feature. This allows you to use GPT models while keeping the Claude Code interface.
+
+**Prerequisites:**
+
+1. **Authenticate with Codex CLI** (required for ChatGPT access):
+   ```bash
+   # Install Codex CLI
+   npm install -g @openai/codex
+
+   # Authenticate (opens browser for OAuth login)
+   codex auth login
+   ```
+
+   This stores your ChatGPT credentials in `~/.codex/auth.json`
+
+**Usage Examples:**
+
+```bash
+# Start with default Claude (no routing)
+agent-cli claude --alias "claude-session"
+
+# Start with GPT-5 routing
+agent-cli claude \
+  --alias "gpt5-session" \
+  --llm-provider chatgpt \
+  --llm-model gpt-5
+
+# Start with GPT-5 Codex
+agent-cli claude \
+  --alias "codex-session" \
+  --llm-provider chatgpt \
+  --llm-model gpt-5-codex
+```
+
+**How It Works:**
+
+When routing is enabled:
+1. Claude Code requests are intercepted before reaching Anthropic's API
+2. Requests are transformed from Claude Messages API format → ChatGPT Responses API format
+3. The request is sent to ChatGPT with proper authentication (via Codex CLI)
+4. ChatGPT's streaming response is transformed back to Claude's format
+5. Claude Code receives responses as if they came from Anthropic
+
+**Supported Models:**
+
+- `gpt-5` - GPT-5 with reasoning (supports reasoning effort levels)
+- `gpt-5-codex` - GPT-5 optimized for coding tasks
+- More models may be added in the future
+
+**Dynamic Model Switching:**
+
+You can change the LLM routing configuration for an active session without restarting using the `agent-cli router` command (see below).
+
+#### 3. `agent-cli router` - Manage LLM Routing
+
+Manage LLM routing configuration for active Claude sessions. This allows you to switch between different LLM models without restarting your agent.
+
+```bash
+# Configure routing for a session (interactive)
+agent-cli router
+
+# Clear all session routing configurations
+agent-cli router --clear
+
+# With verbose logging
+agent-cli router --verbose
 ```
 
 **Options:**
 - `-v, --verbose` - Enable verbose logging
-- `--remove-all` - Remove entire .agiflow directory (default: remove only credential files)
+- `--clear` - Clear all session routing configurations
 
-### Environment Variables
+**Interactive Workflow:**
 
-The CLI uses these environment variables (can be overridden with command options):
+1. **Select a session** - The command shows all active sessions with their current routing:
+   ```
+   ? Select a session to configure routing:
+   ❯ my-dev-session [chatgpt/gpt-5 (high)]
+     gpt5-experiment [chatgpt/gpt-5-codex (medium)]
+     claude-session [default]
+   ```
+
+2. **Select routing configuration** - Choose from available options:
+   ```
+   ? Select LLM routing configuration:
+   ❯ Default (Claude)
+     GPT-5 (Reasoning: High)
+     GPT-5 (Reasoning: Medium)
+     GPT-5 (Reasoning: Low)
+     GPT-5 (Reasoning: Minimal)
+     GPT-5 Codex (Reasoning: High)
+     GPT-5 Codex (Reasoning: Medium)
+     GPT-5 Codex (Reasoning: Low)
+   ```
+
+3. **Configuration saved** - The routing configuration is updated in `~/.agiflow/sessions.json`
+
+**Available Routing Options:**
+
+- **Default (Claude)** - Remove routing, use native Claude
+- **GPT-5 (Reasoning: High)** - GPT-5 with maximum reasoning effort (best for complex problems)
+- **GPT-5 (Reasoning: Medium)** - GPT-5 with balanced reasoning (default)
+- **GPT-5 (Reasoning: Low)** - GPT-5 with minimal reasoning (faster responses)
+- **GPT-5 (Reasoning: Minimal)** - GPT-5 with no reasoning (fastest)
+- **GPT-5 Codex** - GPT-5 optimized for coding with reasoning levels
+
+**Reasoning Effort Levels:**
+
+The reasoning effort parameter controls how much computational reasoning the model uses:
+- **High** - Maximum reasoning, best for complex problems, slowest
+- **Medium** - Balanced reasoning, good for most tasks
+- **Low** - Light reasoning, faster responses
+- **Minimal** - No extra reasoning, fastest responses
+
+**Session Settings Location:**
+
+All session routing configurations are stored in `~/.agiflow/sessions.json`:
+
+```json
+{
+  "session-id-1": {
+    "provider": "chatgpt",
+    "model": "gpt-5",
+    "reasoningEffort": "high",
+    "alias": "my-dev-session"
+  },
+  "session-id-2": {
+    "provider": "chatgpt",
+    "model": "gpt-5-codex",
+    "reasoningEffort": "medium",
+    "alias": "gpt5-experiment"
+  }
+}
+```
+
+**Example Workflow:**
 
 ```bash
-# Required for Claude agent
-CLAUDE_AGENT_SESSION_ID=your-session-id
+# 1. Start Claude with default routing
+agent-cli claude --alias "dev-session"
+
+# 2. Switch to GPT-5 with high reasoning (while agent is running)
+agent-cli router
+# Select "dev-session" → "GPT-5 (Reasoning: High)"
 
-# Optional authentication
-AGENT_API_KEY=your-api-key
-AGENT_ORGANIZATION_ID=your-org-id
+# 3. Switch to GPT-5 Codex with medium reasoning
+agent-cli router
+# Select "dev-session" → "GPT-5 Codex (Reasoning: Medium)"
 
-# Server endpoints (from config)
-VITE_INJECT_AGIFLOW_APP_ENDPOINT=wss://your-server.com
+# 4. Switch back to default Claude
+agent-cli router
+# Select "dev-session" → "Default (Claude)"
+
+# 5. Clear all routing configurations
+agent-cli router --clear
 ```
 
+**Tips:**
+
+- Use `--alias` when launching Claude to give your sessions meaningful names
+- Session routing is dynamic - changes take effect immediately without restart
+- Clear routing with `agent-cli router --clear` to reset all sessions to default Claude
+- Reasoning effort only applies to GPT models (not Claude)
+
+#### 4. `agent-cli logout` - Clean Up Credentials
+Log out and clean up stored credentials.
+
+```bash
+# Remove credential files only
+agent-cli logout
+
+# Remove entire .agiflow directory
+agent-cli logout --remove-all
+
+# With verbose output
+agent-cli logout --verbose
+```
+
+**Options:**
+- `-v, --verbose` - Enable verbose logging
+- `--remove-all` - Remove entire .agiflow directory (default: remove only credential files)
+
 ### Authentication Flow
 
 1. **Connect Command**: Uses device code authentication flow
@@ -131,12 +349,51 @@ VITE_INJECT_AGIFLOW_APP_ENDPOINT=wss://your-server.com
    ```
    Error: Authentication failed
    ```
-   Solution: Run `agiflow connect` first or provide valid API credentials
+   Solution: Run `agent-cli connect` first or provide valid API credentials
 
 4. **Connection Issues**
    - Check network connectivity
    - Verify server URL is accessible
    - Use `--verbose` flag for detailed logging
+   - Use `--standalone` flag to run without backend connection
+
+5. **WebSocket 401 Unauthorized (Production)**
+   ```
+   Error: Unexpected server response: 401
+   ```
+   Solution: Use `--standalone` flag to run without backend authentication:
+   ```bash
+   agent-cli claude --standalone --verbose
+   ```
+
+**LLM Routing Issues:**
+
+1. **Codex Auth Not Found**
+   ```
+   Warning: Failed to read Codex auth
+   ```
+   Solutions:
+   - Install Codex CLI: `npm install -g @openai/codex`
+   - Authenticate: `codex auth login`
+   - Verify `~/.codex/auth.json` exists
+
+2. **ChatGPT Token Expired**
+   ```
+   Error: 401 Unauthorized
+   ```
+   Solution: Re-authenticate with Codex: `codex auth login`
+
+3. **Routing Not Working**
+   - Verify routing is configured via `agent-cli router` command
+   - Use `--verbose` to see routing status
+   - Check that Codex credentials are valid (`codex auth login`)
+   - Ensure network can reach ChatGPT API
+
+4. **Session Not Found in Router**
+   If your session doesn't appear in `agent-cli router`:
+   - Restart Claude agent with `--alias` to give it a meaningful name
+   - Check `~/.agiflow/sessions.json` to see saved sessions
+   - Use `agent-cli router --clear` to reset all configurations
 
 ### Global Options
 
@@ -144,7 +401,11 @@ All commands support these global options:
 - `-v, --verbose` - Enable verbose logging
 - `--debug` - Enable debug mode
 
-Use `agiflow --help` or `agiflow <command> --help` for detailed command information.
+Use `agent-cli --help` or `agent-cli <command> --help` for detailed command information.
+
+## Related Projects
+
+🔗 **[AgiFlow AI Code Toolkit](https://github.com/AgiFlow/aicode-toolkit)** - An open-source collection of AI development tools and utilities for building with AI coding assistants.
 
 ## License