Skip to content

Commit 0cebd49

Browse files
ymkiuxymkiux
committed
docs(readme): clarify value proposition and first-use flow
1 parent 18d6759 commit 0cebd49

9 files changed

Lines changed: 280 additions & 225 deletions

File tree

‎README.md‎

Lines changed: 52 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@
44

55
# Codex Mate
66

7-
**One dashboard for all your local AI coding agents. Switch providers, manage sessions, and orchestrate tasks across Codex, Claude Code, Gemini CLI, CodeBuddy Code, Pi, OpenCode, KiloCode, and OpenClaw. Zero cloud, local-first control plane.**
7+
**Find the conversations scattered across your AI coding tools.**
8+
9+
Codex Mate is a locally running CLI + Web tool for browsing, filtering, and exporting existing sessions in one place, with Provider, Skills, and task management when you need them.
810

911
<p>
1012
<a href="https://sakurabytecore.github.io/codexmate/">[Documentation]</a>
@@ -31,57 +33,21 @@
3133
---
3234

3335
> [!TIP]
34-
> **Local First**: All configurations and sessions are stored in your home directory. No telemetry, no cloud accounts required.
35-
36-
> [!IMPORTANT]
37-
> This project is currently in early stage. We are seeking developers to help build the local agent ecosystem!
36+
> **Local First**: Read existing sessions and manage configuration on your machine. No telemetry or Codex Mate cloud account required. Model requests still go to your configured provider; running locally does not mean models run offline.
3837
3938
## What is Codex Mate?
4039

41-
Have you ever felt overwhelmed by managing multiple local AI agents? Each has its own config format, session storage, and skills directory.
40+
Was last week's solution discussed in Codex or Claude Code? Narrow down your local sessions by source, project, or time, open the conversation, and export it as Markdown for reference.
4241

43-
**Codex Mate** offers a unified control plane to bring order to the chaos. It's a local-first CLI + Web UI designed to manage [Codex](https://github.com/openai/codex), [Claude Code](https://github.com/anthropic-ai/claude-code), [OpenCode](https://opencode.ai/), KiloCode, [OpenClaw](https://github.com/moeru-ai/openclaw), and Pi seamlessly.
42+
Codex Mate manages existing tools and local records. It is not a new AI model or a replacement for your coding assistant. Start by finding one useful conversation, without configuring every tool first.
4443

45-
### What's So Special?
44+
[Get started](#quick-start) · [Session guide (Chinese)](https://sakurabytecore.github.io/codexmate/guide/sessions)
4645

47-
Unlike simple wrappers, Codex Mate acts as a **Local Agent Bridge**:
48-
- **Unified Session Browser**: Search, inspect, filter, and export local sessions across Codex, Claude Code, Gemini CLI, CodeBuddy Code, WorkBuddy, Pi, OpenCode, and Zed from one place.
49-
- **OpenAI-Compatible Bridge**: Use Codex with any OpenAI-compatible UI by normalizing the Responses API; the built-in Codex conversion also fills and normalizes Codex fingerprint headers such as `User-Agent`, `Version`, `OpenAI-Beta`, and `Originator` so upstream providers see an official Codex CLI-shaped request.
50-
- **Claude Provider Bridge**: Connect Claude Code to OpenAI Chat Completions-compatible providers and Ollama through the built-in local Claude-compatible proxy.
51-
- **OpenCode Provider Control**: Manage OpenCode provider/model selection with a CodexMate-owned provider store under `~/.codexmate`, projecting only the active provider into native OpenCode config to avoid polluting or deleting user-owned settings.
52-
- **KiloCode Config Bridge**: Configure KiloCode providers from the CLI or Web UI, writing to `~/.config/kilo/kilo.jsonc` while preserving stored API keys.
53-
- **Pi Provider Config**: Manage Pi providers from the Web UI with lossless round-trip writes to `~/.pi/agent/models.json`, auto-fetched remote model lists, and one-click default provider/model switching via `~/.pi/agent/settings.json`.
54-
- **Provider Health Cleanup**: Probe local Codex and Claude provider routes, surface failed configs in one modal, and bulk-clean selected broken providers without touching healthy or protected entries.
55-
- **Skills Marketplace**: A local-first market to share and import skills between different agent apps.
56-
- **Prompt File Editor**: Unified editor for global and project-level `CLAUDE.md` and `AGENTS.md` (including OpenCode's `~/.config/opencode/AGENTS.md`) with auto-detection of project paths, plus a shared preset pool for reusable prompts.
57-
- **Task Orchestrator**: Plan and execute complex tasks with dependency tracking.
58-
59-
---
60-
61-
## Current Progress
62-
63-
| Feature | Status | Description |
64-
| --- | --- | --- |
65-
| **Provider Management** | ✅ | Switch providers/models for Codex, Claude, OpenCode, KiloCode, OpenClaw, and Pi |
66-
| **Live Agent Sync** | ✅ | Real-time monitoring of Codex/Claude config & status |
67-
| **Session Browser** | ✅ | Search, preview, filter, and export sessions across Codex, Claude Code, Gemini CLI, CodeBuddy Code, WorkBuddy, Pi, OpenCode, and Zed |
68-
| **Usage Analytics** | ✅ | Visualize message trends and top projects |
69-
| **Local Skills Market** | ✅ | Cross-app import/export of agent skills |
70-
| **Task Queue** | ✅ | DAG-based task execution and logs |
71-
| **OpenAI Bridge** | ✅ | Convert Codex Responses API to standard OpenAI format and attach/normalize Codex fingerprints in the built-in conversion |
72-
| **Claude Provider Bridge** | ✅ | Connect Claude Code to OpenAI Chat Completions-compatible providers and Ollama via the built-in Claude-compatible proxy |
73-
| **OpenCode Provider Store** | ✅ | Keep multiple OpenCode providers in `~/.codexmate` while projecting only the selected provider to native OpenCode config |
74-
| **KiloCode Config Bridge** | ✅ | Configure KiloCode through `codexmate kilo config` or the Web UI, writing provider URL/model/API key data to `~/.config/kilo/kilo.jsonc` |
75-
| **Pi Provider Config** | ✅ | Manage Pi providers in the Web UI writing to `~/.pi/agent/models.json` (unknown fields preserved) and switch the default provider/model in `~/.pi/agent/settings.json` |
76-
| **Provider Health Check** | ✅ | Probe local Codex/Claude provider routes, highlight failed configs, and bulk-remove selected broken providers safely |
77-
| **Prompt Templates** | ✅ | Reusable prompt plugins with variables |
78-
| **Prompt File Editor** | ✅ | Edit global and project-level CLAUDE.md / AGENTS.md with auto-detect, path switching, and a shared preset pool. Applying a preset only updates the editor; save manually to write the file. |
79-
| **MCP Integration** | ✅ | Expose local tools and resources via MCP stdio |
80-
| **Auto Update** | ✅ | Quick update CLI via `codexmate update` |
46+
## Quick Start
8147

82-
---
48+
Install using one option below, then run `codexmate run`. Open the address printed in your terminal, select a source with existing records in the session browser, open a conversation, and use its export action. If there are no local records, create a conversation in the original tool first.
8349

84-
## Quick Start
50+
Exports are for reading and archiving, not restoring complete agent state in another tool. Use `codexmate setup` when you need to configure a provider. See the [quick-start guide (Chinese)](https://sakurabytecore.github.io/codexmate/guide/quick-start) for details.
8551

8652
### Install via Homebrew (macOS / Linux)
8753

@@ -131,6 +97,45 @@ curl -fsSL https://raw.githubusercontent.com/SakuraByteCore/codexmate/main/scrip
13197

13298
---
13399

100+
## What's So Special?
101+
102+
After finding your conversations, manage the configuration, skills, and tasks used in your daily work:
103+
- **Unified Session Browser**: Browse local sessions from Codex, Claude Code, Gemini CLI, CodeBuddy Code, WorkBuddy, Pi, OpenCode, and Zed in one place. Search, export, and deletion availability varies by source; see the [session guide (Chinese)](https://sakurabytecore.github.io/codexmate/guide/sessions).
104+
- **OpenAI-Compatible Bridge**: Use Codex with any OpenAI-compatible UI by normalizing the Responses API; the built-in Codex conversion also fills and normalizes Codex fingerprint headers such as `User-Agent`, `Version`, `OpenAI-Beta`, and `Originator` so upstream providers see an official Codex CLI-shaped request.
105+
- **Claude Provider Bridge**: Connect Claude Code to OpenAI Chat Completions-compatible providers and Ollama through the built-in local Claude-compatible proxy.
106+
- **OpenCode Provider Control**: Manage OpenCode provider/model selection with a CodexMate-owned provider store under `~/.codexmate`, projecting only the active provider into native OpenCode config to avoid polluting or deleting user-owned settings.
107+
- **KiloCode Config Bridge**: Configure KiloCode providers from the CLI or Web UI, writing to `~/.config/kilo/kilo.jsonc` while preserving stored API keys.
108+
- **Pi Provider Config**: Manage Pi providers from the Web UI with lossless round-trip writes to `~/.pi/agent/models.json`, auto-fetched remote model lists, and one-click default provider/model switching via `~/.pi/agent/settings.json`.
109+
- **Provider Health Cleanup**: Probe local Codex and Claude provider routes, surface failed configs in one modal, and bulk-clean selected broken providers without touching healthy or protected entries.
110+
- **Skills Marketplace**: A local-first market to share and import skills between different agent apps.
111+
- **Prompt File Editor**: Unified editor for global and project-level `CLAUDE.md` and `AGENTS.md` (including OpenCode's `~/.config/opencode/AGENTS.md`) with auto-detection of project paths, plus a shared preset pool for reusable prompts.
112+
- **Task Orchestrator**: Plan and execute complex tasks with dependency tracking.
113+
114+
---
115+
116+
## Current Progress
117+
118+
| Feature | Status | Description |
119+
| --- | --- | --- |
120+
| **Provider Management** | ✅ | Switch providers/models for Codex, Claude, OpenCode, KiloCode, OpenClaw, and Pi |
121+
| **Live Agent Sync** | ✅ | Real-time monitoring of Codex/Claude config & status |
122+
| **Session Browser** | ✅ | Browse and filter local sessions; search and Markdown export depend on the source. See the session guide |
123+
| **Usage Analytics** | ✅ | Visualize message trends and top projects |
124+
| **Local Skills Market** | ✅ | Cross-app import/export of agent skills |
125+
| **Task Queue** | ✅ | DAG-based task execution and logs |
126+
| **OpenAI Bridge** | ✅ | Convert Codex Responses API to standard OpenAI format and attach/normalize Codex fingerprints in the built-in conversion |
127+
| **Claude Provider Bridge** | ✅ | Connect Claude Code to OpenAI Chat Completions-compatible providers and Ollama via the built-in Claude-compatible proxy |
128+
| **OpenCode Provider Store** | ✅ | Keep multiple OpenCode providers in `~/.codexmate` while projecting only the selected provider to native OpenCode config |
129+
| **KiloCode Config Bridge** | ✅ | Configure KiloCode through `codexmate kilo config` or the Web UI, writing provider URL/model/API key data to `~/.config/kilo/kilo.jsonc` |
130+
| **Pi Provider Config** | ✅ | Manage Pi providers in the Web UI writing to `~/.pi/agent/models.json` (unknown fields preserved) and switch the default provider/model in `~/.pi/agent/settings.json` |
131+
| **Provider Health Check** | ✅ | Probe local Codex/Claude provider routes, highlight failed configs, and bulk-remove selected broken providers safely |
132+
| **Prompt Templates** | ✅ | Reusable prompt plugins with variables |
133+
| **Prompt File Editor** | ✅ | Edit global and project-level CLAUDE.md / AGENTS.md with auto-detect, path switching, and a shared preset pool. Applying a preset only updates the editor; save manually to write the file. |
134+
| **MCP Integration** | ✅ | Expose local tools and resources via MCP stdio |
135+
| **Auto Update** | ✅ | Quick update CLI via `codexmate update` |
136+
137+
---
138+
134139
## Architecture
135140

136141
```mermaid
@@ -172,6 +177,9 @@ flowchart TD
172177

173178
## Special Thanks
174179

180+
> [!IMPORTANT]
181+
> This project is currently in early stage. We are seeking developers to help build the local agent ecosystem!
182+
175183
Special thanks to all contributors for their contributions to Codex Mate ❤️
176184

177185
<a href="https://github.com/SakuraByteCore/codexmate/graphs/contributors">

0 commit comments

Comments
 (0)