codexmate 0.0.14 → 0.0.16

package/README.en.md

@@ -1,429 +1,224 @@
-# Codex Mate
+<div align="center">
 
-<div align="center">
+# Codex Mate
 
-<img src="res/logo.png" alt="Codex Mate logo" width="110">
+**Local configuration and session manager for Codex / Claude Code / OpenClaw**
 
-[![Build](https://img.shields.io/github/actions/workflow/status/ymkiux/codexmate/release.yml?label=build)](https://github.com/ymkiux/codexmate/actions/workflows/release.yml)
+> Current version: `v0.0.16`
+
+[![Build](https://img.shields.io/github/actions/workflow/status/SakuraByteCore/codexmate/release.yml?label=build)](https://github.com/SakuraByteCore/codexmate/actions/workflows/release.yml)
 [![Version](https://img.shields.io/npm/v/codexmate?label=version&registry_uri=https%3A%2F%2Fregistry.npmjs.org)](https://www.npmjs.com/package/codexmate)
 [![Downloads](https://img.shields.io/npm/dt/codexmate?label=downloads)](https://www.npmjs.com/package/codexmate)
-[![Status](https://img.shields.io/badge/status-alpha-orange)](https://github.com/ymkiux/codexmate)
-[![Maintain](https://img.shields.io/github/commit-activity/m/ymkiux/codexmate?label=maintain%2Fmonth)](https://github.com/ymkiux/codexmate/commits)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D14.0.0-green.svg)](https://nodejs.org)
 
-**A lightweight AI configuration assistant: quickly switch Codex providers/models and Claude Code configs, with a unified session browser**
+[Quick Start](#quick-start) · [Commands](#command-reference) · [Web UI](#web-ui) · [MCP](#mcp) · [中文](README.md)
 
 </div>
 
 ---
 
-<p align="center">English · <a href="README.md">中文版</a></p>
-
-![Codex Mate Web UI](res/screenshot.png)
-
-## Overview
-
-Codex Mate helps you switch Codex/Claude Code providers and models in seconds, and manage local sessions in one place.
-
-## 60-Second Quick Start (One-Line Source Install)
-
-Requirements: `Node.js >= 14`, `Git`
-
-```bash
-git clone https://github.com/ymkiux/codexmate.git && cd codexmate && npm install && npm link && codexmate run
-```
-
-Open `http://localhost:3737` in your browser.
+## What Is This?
 
-If this is your first time, run:
+Codex Mate is a local-first CLI + Web UI for unified management of:
 
-```bash
-codexmate setup
-codexmate status
-```
-
-If you only want a temporary trial, run:
-
-```bash
-npx codexmate@latest run
-```
+- Codex provider/model switching and config writes
+- Claude Code profiles (writes to `~/.claude/settings.json`)
+- OpenClaw JSON5 profiles and workspace `AGENTS.md`
+- Local Codex/Claude sessions (list/filter/export/delete)
+- `codexmate qwen` passthrough command
 
-## Choose a Common Workflow
+It works on local files directly and does not require cloud hosting.
 
-1. Switch Codex provider/model quickly
+## Why Codex Mate?
 
-```bash
-codexmate switch <provider>
-codexmate use <model>
-```
-
-2. Apply Claude Code config in one line
-
-```bash
-codexmate claude <BaseURL> <API_KEY> <model>
-```
-
-3. Export a local session to Markdown
-
-```bash
-codexmate export-session --source codex --session-id <ID>
-```
-
-## Core Commands (Most Used)
-
-| Goal | Command |
-| --- | --- |
-| Check current status | `codexmate status` |
-| Start Web UI | `codexmate run` |
-| Interactive setup | `codexmate setup` |
-| List providers/models | `codexmate list` / `codexmate models` |
-| Switch provider/model | `codexmate switch <provider>` / `codexmate use <model>` |
-| Write Claude config | `codexmate claude <BaseURL> <API_KEY> [model]` |
-| Export session | `codexmate export-session --source <codex|claude> ...` |
-
-## What You Get
-
-- One-command provider/model switching
-- Local config control with backups
-- Lightweight Web UI instead of heavy clients
-- Unified session browser (view/export/resume when available)
-- Session management: list/filter/export/delete local sessions; keyword search supports Codex and Claude
-- New in 0.0.10: Claude sessions are searchable by keywords (e.g., `claude code`, `claude-code`, numeric tokens)
-- New in 0.0.14: Skills Manager modal adds overview counters, refined filters, and slimmer list scrollbars
-
-## Feature Overview
-
-| Module | Problem | Key Capabilities |
+| Dimension | Codex Mate | Manual File Editing |
 | --- | --- | --- |
-| Codex Config | Switching providers/models is painful | Provider/model switching, model management, CLI + Web entry points, template-confirmed writes |
-| Skills Manager | Local custom skills are hard to inspect and clean up | Skills modal with overview counters, keyword/status filters, bulk delete, and cross-app import scan |
-| Claude Code Config | Multiple profiles and inconsistent write paths | Profile management, default write to `~/.claude/settings.json` |
-| OpenClaw Config | OpenClaw configs are scattered | JSON5 profiles, apply to `~/.openclaw/openclaw.json`, AGENTS workspace management |
-| Session Browser | Local sessions are hard to track | List/filter sessions, keyword search (Codex + Claude), export to Markdown, copy resume command (when available), delete and batch cleanup |
-| Utilities | Compression/extraction requires extra tools | 7-Zip preferred, JS fallback |
-
-## Why Codex Mate
-
-- Focused on three jobs: Codex provider/model switching + Claude Code config apply + OpenClaw config apply
-- Local-first: configs and API keys are written to local files, not the cloud
-- Lightweight: CLI + Web, no desktop app required
-- Reversible: auto-backup before first takeover
-
-## Scope and Boundaries
-
-- Only configuration management for Codex, Claude Code, and OpenClaw, not a full all-in-one tool suite
-- No built-in proxy/relay/billing dashboard/cloud sync (kept lightweight)
-- Web UI runs only when you start it (`codexmate run`)
-
-## Alternatives
-
-- cc-switch: https://github.com/farion1231/cc-switch
-
-## Install
-
-### From Source (Recommended, One Line)
-
-```bash
-git clone https://github.com/ymkiux/codexmate.git && cd codexmate && npm install && npm link
-```
-
-Then verify:
+| Multi-tool management | Codex + Claude Code + OpenClaw in one entry | Different files and folders per tool |
+| Operation mode | CLI + local Web UI | Manual TOML/JSON/JSON5 edits |
+| Session handling | Browse/export/batch cleanup | Manual file location and processing |
+| Rollback readiness | Backup before first takeover | Easy to overwrite by mistake |
+| Automation integration | MCP stdio (read-only by default) | Requires custom scripting |
+
+## Core Features
+
+**Configuration**
+- Provider/model switching (`switch`, `use`)
+- Codex `config.toml` template confirmation before write
+- Claude Code profile management and apply
+- OpenClaw JSON5 profile management
+
+**Session Management**
+- Unified Codex + Claude session list
+- Keyword/source/cwd filters
+- Markdown export
+- Session-level and message-level delete (supports batch)
+
+**Engineering Utilities**
+- MCP stdio domains (`tools`, `resources`, `prompts`)
+- Built-in proxy controls (`proxy`)
+- Auth profile management (`auth`)
+- `codexmate qwen` compatibility entrypoint (passthrough with `--yolo`)
+- Zip/unzip utilities
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A[CLI: codexmate] --> B[Local config files]
+    A --> C[Local Web UI]
+    C --> D[Built-in HTTP API]
+    D --> B
+    D --> E[Session indexing/export]
+    A --> F[MCP stdio server]
+
+    subgraph Local Files
+      B1[~/.codex/config.toml]
+      B2[~/.claude/settings.json]
+      B3[~/.openclaw/openclaw.json]
+      B4[sessions/*.jsonl]
+    end
+
+    B --> B1
+    B --> B2
+    B --> B3
+    E --> B4
+```
+
+## Quick Start
+
+### Install from npm
 
 ```bash
+npm install -g codexmate
+codexmate setup
 codexmate status
 codexmate run
 ```
 
-### Run with npx (No Install)
+Default listen address is `127.0.0.1:3737`, and browser auto-open is enabled by default.
 
-```bash
-npx codexmate@latest status
-npx codexmate@latest run
-```
-
-### Global (npm)
+### Run from source
 
 ```bash
-npm install -g codexmate
+git clone https://github.com/SakuraByteCore/codexmate.git
+cd codexmate
+npm install
+npm link
+codexmate run
 ```
 
-Package name on npm: `codexmate`. If you want the latest repo version each time, install from GitHub:
+### Tests / CI (service only)
 
 ```bash
-npm install -g ymkiux/codexmate
+codexmate run --no-browser
 ```
 
-### Requirements
-
-- Node.js >= 14
-- Windows / macOS / Linux
+> Convention: automated tests validate service and API behavior only, without opening browser pages.
 
-## CLI Cheat Sheet
+## Command Reference
 
 | Command | Description |
 | --- | --- |
-| `codexmate` | Show help and available commands |
-| `codexmate setup` | Interactive configuration wizard |
-| `codexmate status` | Show current status |
-| `codexmate list` | List all providers |
-| `codexmate switch <provider>` | Switch provider |
-| `codexmate use <model>` | Switch model |
-| `codexmate add <name> <URL> [API key]` | Add a provider |
-| `codexmate delete <provider>` | Delete a provider |
-| `codexmate claude <BaseURL> <API key> [model]` | Write Claude Code config to `~/.claude/settings.json` |
-| `codexmate models` | List all models |
-| `codexmate add-model <model>` | Add a model |
-| `codexmate delete-model <model>` | Delete a model |
-| `codexmate run` | Start the Web UI |
-| `codexmate mcp [serve] [--transport stdio] [--allow-write\|--read-only]` | Start MCP server over stdio (default read-only) |
-| `codexmate export-session --source <codex|claude> (--session-id <ID>|--file <PATH>) [--output <PATH>] [--max-messages <N|all|Infinity>]` | Export a session to Markdown |
-
-## MCP (stdio)
-
-- Transport: `stdio` only
-- Default mode: read-only tool set
-- Write tools: enable by `--allow-write` or `CODEXMATE_MCP_ALLOW_WRITE=1`
-- Sensitive fields in `codexmate.claude.settings.get` are returned as masked values
+| `codexmate status` | Show current config status |
+| `codexmate setup` | Interactive setup |
+| `codexmate list` / `codexmate models` | List providers / models |
+| `codexmate switch <provider>` / `codexmate use <model>` | Switch provider / model |
+| `codexmate add <name> <URL> [API_KEY]` | Add provider |
+| `codexmate delete <name>` | Delete provider |
+| `codexmate claude <BaseURL> <API_KEY> [model]` | Write Claude Code config |
+| `codexmate auth <list\|import\|switch\|delete\|status>` | Auth profile management |
+| `codexmate proxy <status\|set\|apply\|enable\|start\|stop>` | Built-in proxy management |
+| `codexmate workflow <list\|get\|validate\|run\|runs>` | MCP workflow management |
+| `codexmate codex [args...] [--follow-up <text> repeatable]` | Codex CLI passthrough entrypoint (auto-adds `--yolo`, supports queued follow-up appends) |
+| `codexmate qwen [args...]` | Qwen CLI passthrough entrypoint |
+| `codexmate run [--host <HOST>] [--no-browser]` | Start Web UI |
+| `codexmate mcp serve [--read-only\|--allow-write]` | Start MCP stdio server |
+| `codexmate export-session --source <codex\|claude> ...` | Export session to Markdown |
+| `codexmate zip <path> [--max:0-9]` / `codexmate unzip <zip> [out]` | Zip / unzip |
+| `codexmate unzip-ext <zip-dir> [out] [--ext:suffix[,suffix...]] [--no-recursive]` | Extract files with target suffixes from ZIP files in a directory (default `.json`, recursive by default) |
 
-```bash
-# Read-only (recommended for external agents)
-codexmate mcp serve --read-only
-
-# Enable write tools explicitly
-codexmate mcp serve --allow-write
-```
-
-Provided MCP domains:
-
-- `tools`: status/provider/model/session/auth/proxy and config operations
-- `resources`: status/providers/sessions snapshots
-- `prompts`: built-in diagnose/switch/export templates
-
-## Web UI
-
-Start the Web UI (auto opens browser):
+### Codex Follow-up Append (Optional)
 
 ```bash
-codexmate run
+codexmate codex --follow-up "scan repository first" --follow-up "then fix failing tests"
+codexmate codex --model gpt-5.3-codex --follow-up "step1" --follow-up "step2"
 ```
 
-### Codex Config Mode
+> Note: both `--follow-up` and `--queued-follow-up` are accepted and repeatable.
 
-- View current provider and model status
-- Quickly switch provider and model
-- Manage available model list
-- Edit `~/.codex/AGENTS.md` instruction file (same level as `config.toml`)
-- Open the Skills Manager modal for `~/.codex/skills` (overview counters, keyword/status filters, multi-select delete, cross-app import scan)
-- Add/delete custom providers
-- Supports Codex config management on Linux/Windows
-
-### Skills Manager Modal
-
-- Shows overview counters (`total`, `with SKILL.md`, `missing SKILL.md`, `importable`) for quick audit
-- Supports keyword search by folder name/display name/description and status filter by `SKILL.md` presence
-- Supports multi-select and bulk deletion for local skills
-- Supports scanning unmanaged skills from other apps and importing selected items in batch
-
-### Claude Code Config Mode (Windows / macOS / Linux)
-
-- Manage multiple Claude Code profiles
-- Configure API key, Base URL, and model
-- Default write to `env` in `~/.claude/settings.json`: `env.ANTHROPIC_API_KEY` / `env.ANTHROPIC_BASE_URL` / `env.ANTHROPIC_MODEL`
-- One-liner apply via CLI:
+## Web UI
 
-```bash
-codexmate claude https://api.example.com/v1 sk-ant-xxx claude-3-7-sonnet
-```
+### Codex Mode
+- Provider/model switching
+- Model list management
+- `~/.codex/AGENTS.md` editing
+- `~/.codex/skills` management (filter, batch delete, cross-app import)
 
-- In the Web UI, each Claude configuration card now has a "Share Import Command" button that copies a one-click import command (for example: `codexmate claude <BaseURL> <API Key> <Model>`).
 
-### OpenClaw Config Mode
+### Claude Code Mode
+- Multi-profile management
+- Default write to `~/.claude/settings.json`
+- Shareable import command copy
 
-- Manage multiple OpenClaw JSON5 profiles
+### OpenClaw Mode
+- JSON5 multi-profile management
 - Apply to `~/.openclaw/openclaw.json`
-- Manage `AGENTS.md` under the OpenClaw Workspace (default: `~/.openclaw/workspace/AGENTS.md`)
-
-### Session Browser
+- Manage `~/.openclaw/workspace/AGENTS.md`
 
-- View local Codex and Claude Code sessions in one page
-- Filter by source (Codex / Claude / All)
-- Filter by session path (cwd), auto refresh on selection
-- Export selected sessions to Markdown
-- Copy resume command when available
-- Delete single sessions (local jsonl records)
-- Batch delete multiple sessions with partial failure summary
-- Delete individual records or multi-select within session details (writes back to original jsonl)
+### Sessions Mode
+- Unified Codex + Claude sessions
+- Search, filter, export, delete, batch cleanup
 
-### Codex Template Confirmation Mode
+## MCP
 
-- Codex config changes in Web UI go to a `config.toml` template editor first
-- Only writes to `config.toml` after you click "Confirm Apply Template"
-- Prevents direct one-click overwrites from the UI
+> Transport: `stdio`
 
-## Configuration Files
-
-Config directory: `~/.codex/`
-
-- `config.toml` - Codex main config
-- `auth.json` - API auth info
-- `models.json` - Available model list
-- `provider-current-models.json` - Per-provider current model config
-- `codexmate-init.json` - First-run marker
-- `config.toml.codexmate-backup-*.bak` - Backup created on first takeover
-
-Claude Code config files:
-
-- `~/.claude/settings.json` - Runtime config (default write target)
-- `~/.claude/settings.json.codexmate-backup-*.bak` - Backup before first overwrite
-
-OpenClaw config files:
-
-- `~/.openclaw/openclaw.json` - OpenClaw config (JSON5)
-- `~/.openclaw/workspace/AGENTS.md` - OpenClaw workspace instructions
-
-## First Run Initialization
-
-When you run `codexmate` for the first time and an existing `~/.codex/config.toml` is detected that is not managed by Codex Mate:
-
-- The original file is backed up as `config.toml.codexmate-backup-<timestamp>.bak`
-- The original `config.toml` is preserved, and a first-run marker is written
-- Only when `CODEXMATE_FORCE_RESET_EXISTING_CONFIG=1` is set will the default config be rebuilt
-- Subsequent runs will not repeat this process
-
-## Examples
-
-### Add a Custom API Provider
-
-```bash
-codexmate add myapi https://api.example.com/v1 sk-your-api-key
-codexmate switch myapi
-```
-
-### Switch to a Different Model
-
-```bash
-codexmate use gpt-4-turbo
-```
-
-### Export a Session (CLI)
-
-```bash
-codexmate export-session --source codex --session-id 123456
-codexmate export-session --source claude --file "~/.claude/projects/demo/session.jsonl" --max-messages=all
-```
-
-By default, exports are capped at 1000 messages. Use `--max-messages=all` (or `Infinity`) to export everything.
-
-### Configure Claude Code (Cross-Platform)
-
-1. Start the Web UI: `codexmate run`
-2. Switch to "Claude Code Config" mode in the browser
-3. Add a profile (example Zhipu GLM): Name=ZhipuGLM, API Key=your API key, Base URL=`https://open.bigmodel.cn/api/anthropic`, Model=`glm-4.7`
-4. Click the card to apply, or use "Save & Apply to Claude Config" in the editor
-5. Default write to `~/.claude/settings.json`
-6. Restart Claude Code to apply
-
-### Start the Web UI
-
-```bash
-codexmate run
-```
-
-By default it binds to `127.0.0.1`. To expose on LAN, use `--host` or `CODEXMATE_HOST`:
-
-```bash
-codexmate run --host 0.0.0.0
-```
-
-Then open `http://localhost:3737` (or your chosen host). Note: binding to `0.0.0.0` is unsafe on untrusted networks.
-
-## FAQ
-
-### Q: Which operating systems are supported?
-
-A: Codex features support Windows and Linux (CLI and Web). Claude Code config applies to Windows / macOS / Linux (writes to `~/.claude/settings.json`).
-
-### Q: Where are API keys stored?
-
-A: API keys are stored locally in `~/.codex/config.toml` and are not uploaded.
-
-### Q: Is the Web UI safe?
-
-A: The Web UI runs locally; all operations happen on your machine. API keys are masked in the UI.
-
-### Q: How do Claude Code configs take effect?
-
-A: After clicking "Apply to Claude Config", it writes to `~/.claude/settings.json`. Restart Claude Code to apply.
-
-### Q: How to uninstall?
-
-A: Run `npm uninstall -g codexmate`.
-
-## Extras: Compression/Extraction
-
-Prefer 7-Zip for multithreaded zip/unzip. Fallback to the built-in JS library when unavailable.
-
-```bash
-# Compress file or folder (default compression level 5)
-codexmate zip <path>
-
-# Set compression level (0-9, 0=store only, 9=max)
-codexmate zip <path> --max:9
-
-# Unzip a zip file (default to same-level folder)
-codexmate unzip <zip path>
-
-# Unzip to a specific output directory
-codexmate unzip <zip path> <output dir>
-```
+- Default: read-only tools
+- Enable writes: `--allow-write` or `CODEXMATE_MCP_ALLOW_WRITE=1`
+- Domains: `tools`, `resources`, `prompts`
 
 Examples:
 
 ```bash
-# Compress a project folder
-codexmate zip ./my-project
-
-# Max compression
-codexmate zip ./my-project --max:9
-
-# Store only (fast)
-codexmate zip ./large-folder --max:0
-
-# Unzip
-codexmate unzip ./my-project.zip
-
-# Unzip to a target location
-codexmate unzip ./backup.zip D:/restored
+codexmate mcp serve --read-only
+codexmate mcp serve --allow-write
 ```
 
-Note: 7-Zip is optional. If missing, the built-in JS library is used. `--max` only applies to 7-Zip.
+## Config Files
 
-## Tech Stack
+- `~/.codex/config.toml`
+- `~/.codex/auth.json`
+- `~/.codex/models.json`
+- `~/.codex/provider-current-models.json`
+- `~/.claude/settings.json`
+- `~/.openclaw/openclaw.json`
+- `~/.openclaw/workspace/AGENTS.md`
 
-- **Node.js** - Runtime
-- **@iarna/toml** - TOML parser
-- **Vue.js 3** - Web UI framework
-- **Native HTTP** - Built-in Web server
+## Environment Variables
 
-## Release (GitHub Actions)
-
-Create a tag that matches `package.json` (for example `v0.0.14`). Then run the `release` workflow in GitHub Actions and input that tag. It will create a GitHub Release and attach the `npm pack` `.tgz` artifact.
+| Variable | Default | Description |
+| --- | --- | --- |
+| `CODEXMATE_PORT` | `3737` | Web server port |
+| `CODEXMATE_HOST` | `127.0.0.1` | Web listen host |
+| `CODEXMATE_NO_BROWSER` | unset | Set `1` to disable browser auto-open |
+| `CODEXMATE_MCP_ALLOW_WRITE` | unset | Set `1` to allow MCP write tools by default |
+| `CODEXMATE_FORCE_RESET_EXISTING_CONFIG` | `0` | Set `1` to force bootstrap reset of existing config |
 
-## License
+## Tech Stack
 
-Apache-2.0 © [ymkiux](https://github.com/ymkiux)
+- Node.js
+- Vue.js 3 (Web UI)
+- Native HTTP server
+- `@iarna/toml`, `json5`
 
 ## Contributing
 
 Issues and pull requests are welcome.
 
-## Changelog
+- English changelog: `doc/CHANGELOG.md`
+- Chinese changelog: `doc/CHANGELOG.zh-CN.md`
 
-See [doc/CHANGELOG.md](doc/CHANGELOG.md) for the English version.
-See [doc/CHANGELOG.zh-CN.md](doc/CHANGELOG.zh-CN.md) for the Chinese version.
-
----
-
-Made with [ymkiux](https://github.com/ymkiux)
+## License
 
+Apache-2.0