# open-cli-agent

**Repository Path**: beau0303/open-cli-agent

## Basic Information

- **Project Name**: open-cli-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-07
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# open-cli-agent

> **Transform any AI CLI into a powerful server agent.**
>
> Need another server-side CLI interface? Add support in about 10 lines.
>
> English | [中文](./README.zh-CN.md)

---

## Overview

**open-cli-agent** turns any AI command-line interface into a powerful server agent.

Install any supported AI CLI alongside open-cli-agent on your server, then use that CLI directly from the built-in web chat UI. Instead of rebuilding similar agents, skills, MCP wiring, and tool orchestration again and again, you can reuse mature CLI tools as your server-side agent runtime and inherit their capabilities directly.

### Supported AI CLI Tools

| CLI Tool | Command | Streaming | Permission Flag |
|---------|---------|-----------|-----------------|
| **GitHub Copilot CLI** | `copilot` | ✅ JSON Lines | `--allow-all` |
| **Qwen CLI** | `qwen` | ✅ stream-json | `--yolo` |
| **Claude Code** | `claude` | ✅ stream-json | `--dangerously-skip-permissions` |
| **Gemini CLI** | `gemini` | ✅ stream-json | `--all-tools` |
| **OpenAI Codex CLI** | `codex` | ✅ JSON Lines | `--dangerously-bypass-approvals-and-sandbox` |
| **Aider** | `aider` | ⚠️ Plain text | `--yes` |
| **OpenCode** | `opencode` | ✅ JSON | `--yolo` |
| **Amazon Q Developer** | `q` | ⚠️ Plain text | `--accept-all` |
| **Ollama** | `ollama` | ⚠️ Plain text | No flag needed |

> See the [CLI Support Guide](./CLI_SUPPORT.md) for detailed CLI-specific setup.

### Key Features

- **Instant server upgrade**: Turn existing AI CLI tools such as Copilot, Claude, Qwen, Gemini, Codex, and others into server-grade agents.
- **No repeated agent rewrites**: Reuse mature AI CLI tools directly instead of rebuilding similar agent logic from scratch.
- **Higher capability ceiling**: Let your agents inherit the strengths of top CLI tools instead of being limited by a custom wrapper.
- **Beyond coding assistance**: Use the same foundation for automation and business workflows, not just development chat.
- **Flexible access**: Built-in chat UI works in desktop and mobile browsers.
- **Controlled permissions**: Configure different permission levels for different CLI tools and deployment environments.

---

## Quick Start

### Prerequisites

- **Node.js** `20.19+` or `22.12+`
- **One supported AI CLI**, for example:
  - **GitHub Copilot CLI** (`copilot`)
  - **Qwen CLI** (`qwen`)
  - **Claude Code** (`claude`)
  - **Gemini CLI** (`gemini`)
  - **OpenAI Codex CLI** (`codex`)
  - **Aider** (`aider`)
  - **OpenCode** (`opencode`)
  - **Amazon Q Developer** (`q`)
  - **Ollama** (`ollama`)

### Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/zyh-future/open-cli-agent.git
   cd open-cli-agent
   ```

2. **Use a compatible Node.js version**
   ```bash
   nvm install 20
   nvm use 20
   ```

3. **Install dependencies**
   ```bash
   cd server && npm install && cd ..
   cd web && npm install && cd ..
   ```

4. **Configure the server**

   Edit `server/config.json`:
   ```json
   {
     "password": "your_password",
     "ai_cli_path": "copilot",
     "permissions": {
       "preset": "full"
     }
   }
   ```

   Supported values for `ai_cli_path`:
   - `"copilot"` for GitHub Copilot CLI
   - `"qwen"` for Qwen CLI
   - `"claude"` for Claude Code
   - `"gemini"` for Gemini CLI
   - `"codex"` for OpenAI Codex CLI
   - `"aider"` for Aider
   - `"opencode"` for OpenCode
   - `"q"` for Amazon Q Developer
   - `"ollama"` for Ollama

   > See the [CLI Support Guide](./CLI_SUPPORT.md) for detailed configuration.

5. **Build the frontend**
   ```bash
   cd web && npm run build && cd ..
   ```

6. **Start the service**
   ```bash
   ./start.sh
   ```

7. **Open the web UI**

   Visit `http://localhost:3000`

> If `npm run build` shows `Vite requires Node.js version 20.19+ or 22.12+`, switch to Node 20 first, then reinstall dependencies and build again.

---

## Project Structure

```text
open-cli-agent/
├── server/              # Backend service
│   ├── index.js         # Express + WebSocket server
│   ├── cli-manager.js   # CLI execution manager
│   ├── session-manager.js  # Session management
│   ├── config.json      # Runtime config
│   └── package.json
├── web/                 # Frontend app
│   ├── src/
│   │   ├── components/
│   │   │   ├── Chat.vue
│   │   │   ├── Sidebar.vue
│   │   │   ├── Login.vue
│   │   │   └── LanguageSwitcher.vue
│   │   ├── i18n/
│   │   ├── locales/
│   │   ├── App.vue
│   │   └── main.js
│   ├── dist/            # Build output
│   └── package.json
├── session/             # Session data
│   ├── sessions-index.json
│   └── session-*.jsonl
├── start.sh             # Startup script
├── CLI_SUPPORT.md       # CLI support guide
├── PERMISSIONS.md       # Permission guide
└── README.md
```

---

## Configuration

### Basic Config

Edit `server/config.json`:

```json
{
  "password": "aaa",
  "ai_cli_path": "copilot",
  "permissions": {
    "preset": "full"
  }
}
```

### Permissions

**Problem**: Seeing `Permission denied` while using open-cli-agent?

**Solution**: Configure the `permissions` field.

> Different CLIs use different permission flags. open-cli-agent automatically chooses the correct flag based on `ai_cli_path`.
>
> For detailed permission behavior, see [CLI_SUPPORT.md](./CLI_SUPPORT.md) and [PERMISSIONS.md](./PERMISSIONS.md).

#### Presets

1. **`full`**: Full access, recommended for personal use
   ```json
   { "permissions": { "preset": "full" } }
   ```
   Allows browser access, file access, shell commands, URLs, and other supported capabilities.

2. **`tools-only`**: Allow tools but restrict URL and path access
   ```json
   { "permissions": { "preset": "tools-only" } }
   ```

3. **`safe`**: Minimal permissions for stricter environments
   ```json
   { "permissions": { "preset": "safe" } }
   ```

4. **`custom`**: Advanced custom configuration
   ```json
   {
     "permissions": {
       "preset": "custom",
       "custom": {
         "allowed_dirs": ["/path/to/project"],
         "allowed_urls": ["github.com"],
         "allowed_tools": ["chrome-devtools", "write"]
       }
     }
   }
   ```

---

## Usage

1. Log in with the password configured in `server/config.json`.
2. Create a new conversation from the sidebar.
3. Type a message and press `Enter` to send it.
4. Switch sessions from the conversation list.
5. Delete a session with the delete button on the right.
6. Toggle language with the `中文 / EN` button at the top of the sidebar.

---

## Tech Stack

### Backend

- **Node.js** + **Express** for the HTTP server
- **ws** for WebSocket communication
- **child_process** for AI CLI process management

### Frontend

- **Vue 3** for the reactive UI
- **Vite** for build tooling
- **WebSocket** for real-time updates
- **i18n** for bilingual UI text

---

## API Endpoints

### REST API

- `GET /api/sessions` to list all sessions
- `POST /api/sessions` to create a session
- `DELETE /api/sessions/:id` to delete a session
- `GET /api/sessions/:id/history` to get session history
- `PATCH /api/sessions/:id` to rename a session

### WebSocket

- `ws://localhost:3000/ws` for the realtime chat connection

Message examples:

```json
{ "type": "auth", "password": "..." }
{ "type": "select_session", "sessionId": "..." }
{ "type": "message", "text": "..." }
```

---

## Development

### Frontend Dev Mode

```bash
cd web
npm run dev
```

Then open `http://localhost:5173`.

### Backend Dev Mode

```bash
cd server
node index.js
```

---

## Troubleshooting

### 1. `Permission denied`

Cause: The CLI is running without the required non-interactive permission flag.

Fix: Set `permissions.preset` to `full` in `config.json`, or configure a more specific preset that matches your environment.

### 2. Connection failed

Cause: The server is not running, restarting, or the port is already in use.

Fix:
- Check whether the backend is listening on port `3000`
- Inspect server logs
- Verify the browser is opening the correct host and port

### 3. CLI not found

Cause: The AI CLI is not installed or not available in `PATH`.

Fix:
- Install the target CLI
- Or set `ai_cli_path` to the full executable path
- Review [CLI_SUPPORT.md](./CLI_SUPPORT.md) for supported CLIs

---

## Contributing

Issues and pull requests are welcome.

### Adding Support for a New CLI

To add a new CLI, update `server/cli-manager.js`:

1. Add CLI detection in `detectCliType()`
2. Add permission flag mapping in `buildPermissionArgs()`
3. Confirm the output format behavior, such as JSON Lines, JSON arrays, or plain text

In many cases, support can be added in around **10 lines of code**.

---

## License

[MIT](./LICENSE)

---

## Related Docs

- [CLI Support Guide](./CLI_SUPPORT.md)
- [Permissions Guide](./PERMISSIONS.md)

## Show
- <img width="1788" height="961" alt="Pc " src="https://github.com/user-attachments/assets/2440d472-6b0c-4478-b623-243023fb0a03" />

- <img width="420" height="895" alt="Phone" src="https://github.com/user-attachments/assets/bbdd8909-f367-427e-91dd-dd9da5131270" />