Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 19 additions & 55 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,20 @@ CodexBridge is a Codex-centered gateway for connecting multiple chat platforms t
## Current Direction

- First delivery target: `WeChat + Codex`
- Future platforms: `Telegram`, additional chat transports
- Future Codex provider profiles: configuration-only OpenAI-compatible backends such as `MiniMax`, `DeepSeek`, `Qwen`, `OpenRouter`, `Kimi`, `Gemini`, and `iFlow`
- Package-side experiments are paused for now
- `packages/codex-gateway` is not under active development
- `packages/mission-control` is not under active development
- `packages/codex-native-api` is retained as the only package planned for possible future work, but it is also paused for now
- Core rule: platforms are adapters, Codex stays the execution engine, and Codex thread state stays the source of truth

## Documents

- [Core architecture](./docs/architecture/codexbridge-core-architecture.md)
- [Mission Control architecture](./docs/architecture/mission-control.md)
- [Roadmap TODO](./docs/todo/roadmap.md)
- [Codex Gateway TODO](./docs/todo/codex-gateway.md)
- [Mission Control TODO](./docs/todo/mission-control.md)
- [Codex Native API TODO](./docs/todo/codex-native-api.md)
- [Codex Gateway TODO - paused](./docs/todo/codex-gateway.md)
- [Mission Control TODO - paused](./docs/todo/mission-control.md)
- [Mission Control architecture - historical reference](./docs/architecture/mission-control.md)
- [WeChat slash command reference](./docs/usage/weixin-slash-commands.md)

## Repository Layout
Expand All @@ -36,20 +39,27 @@ docs/

Project bootstrap is now focused on:

1. Landing the core session and binding model
2. Keeping platform and provider plugins independent
3. Making `WeChat + Codex` the first real implementation path
1. Keeping `WeChat + Codex` as the product center
2. Avoiding more backend/package expansion until the bridge direction is clearer
3. Treating `codex-gateway` and `mission-control` as paused workstreams
4. Keeping `codex-native-api` only as a retained future option, not as active work

Current implemented bridge pieces:

- Core session routing with WeChat-friendly slash commands, including `/helps`, `/status`, `/usage`, `/login`, `/stop`, `/review`, `/agent`, `/plan`, `/skills`, `/plugins`, `/automation`, `/weibo`, `/new`, `/uploads`, `/as`, `/log`, `/todo`, `/remind`, `/note`, `/provider`, `/models`, `/model`, `/personality`, `/instructions`, `/fast`, `/threads`, `/search`, `/next`, `/prev`, `/open`, `/peek`, `/rename`, `/permissions`, `/allow`, `/deny`, `/reconnect`, `/retry`, `/restart`, and `/lang`
- Core session routing with WeChat-friendly slash commands, including `/helps`, `/status`, `/usage`, `/login`, `/stop`, `/review`, `/plan`, `/skills`, `/plugins`, `/automation`, `/weibo`, `/new`, `/uploads`, `/as`, `/log`, `/todo`, `/remind`, `/note`, `/provider`, `/models`, `/model`, `/personality`, `/instructions`, `/fast`, `/threads`, `/search`, `/next`, `/prev`, `/open`, `/peek`, `/rename`, `/permissions`, `/allow`, `/deny`, `/reconnect`, `/retry`, `/restart`, and `/lang`
- `/open` now rebinds the current scope and immediately returns a short recent-turn preview, so users can resume an old thread with one command instead of calling `/peek` first
- File-backed JSON repositories for persistent bridge state
- WeChat platform skeleton for Hermes-compatible iLink config loading, QR account state reuse, inbound DM normalization, long-poll client/poller wiring, context-token persistence, text chunking, and outbound text/typing delivery
- Codex profile loader and initial Codex app-server client/plugin path for shared thread execution
- WeChat runtime wiring that feeds poll events into the shared bridge coordinator and sends responses back through the WeChat transport
- OpenAI-compatible Responses adapter for non-OpenAI Chat Completions providers, including compact fallback, SSE stream translation, tool-call repair, provider/model capability rules, and gated live-provider smoke tests

Package workstream status:

- `packages/codex-gateway`: paused
- `packages/mission-control`: paused
- `packages/codex-native-api`: retained for later only; currently paused

## OpenAI-Compatible Provider Validation

Live provider validation is opt-in so normal tests do not spend API quota.
Expand Down Expand Up @@ -87,13 +97,6 @@ Recommended entrypoints:
/review
/rv
/review base main
/agent 帮我检查当前项目测试并修复失败项
/agent confirm
/agent show 1
/agent result 1
/agent result 1 file
/agent send 1
/agent retry 1
/plan
/pl
/plan on
Expand Down Expand Up @@ -250,44 +253,6 @@ Examples:

`/plan on` enables native `plan` mode for later turns in the current bridge session. `/plan off` restores the native `default` collaboration mode. This is a mode toggle, not an approval flow.

### `/agent` and `/ag`

Create a confirmed background Agent job for deeper multi-step work.

Examples:

```text
/agent 帮我研究并实现一个小功能,然后测试
/agent confirm
/agent edit 改成只做方案,不修改代码
/agent list
/agent show 1
/agent result 1
/agent result 1 file
/agent send 1
/agent stop 1
/agent retry 1
/agent del 1
```

The experimental workflow is hybrid but Codex-first: Codex app-server is preferred for planning, execution, and verification so an existing Codex subscription is used by default. OpenAI Agents SDK is only a fallback when an Agent API key is configured and the Codex normalization/verifier path is unavailable. Long text results can be paged with `/agent result <index>` or exported as a phone-friendly TXT attachment with `/agent result <index> file`. Jobs with generated attachments keep artifact records, so `/agent send <index>` can resend the file if WeChat rate-limits the first delivery. If both Codex normalization and Agents SDK are unavailable, local fallback still creates a usable draft and verifier path.

Agent planner/verifier configuration:

```bash
# OpenAI default
OPENAI_API_KEY=...
CODEXBRIDGE_AGENT_MODEL=gpt-5.5

# OpenAI-compatible provider, for example MiniMax
CODEXBRIDGE_AGENT_API_KEY=...
CODEXBRIDGE_AGENT_BASE_URL=https://api.minimaxi.com/v1
CODEXBRIDGE_AGENT_MODEL=MiniMax-M2.7
CODEXBRIDGE_AGENT_API=chat_completions
```

`CODEXBRIDGE_AGENT_API_KEY` takes precedence over `OPENAI_API_KEY` for the fallback Agents SDK path. The default path still uses Codex app-server first. When `CODEXBRIDGE_AGENT_BASE_URL` or `OPENAI_BASE_URL` is set, the bridge defaults Agents SDK calls to Chat Completions compatibility mode unless `CODEXBRIDGE_AGENT_API=responses` is explicitly set.

OpenAI-compatible runtime adapter:

- CodexBridge can expose non-OpenAI providers through a local Responses adapter while Codex app-server still talks to a Responses-shaped endpoint.
Expand Down Expand Up @@ -359,7 +324,6 @@ Best-practice rule:
- use `/helps` for command discovery
- use `/login` and `/login list` to manage the host Codex account pool before switching accounts with `/login <index>`
- use `/review`, `/review base <branch>`, or `/review commit <sha>` when you want a native Codex code review without changing the current thread binding
- use `/agent <task>` when the task needs planning, background execution, verifier checks, and one automatic retry before delivery
- use `/plan on` when you want later turns in the current session to prioritize planning first, and `/plan off` when you want to restore the default collaboration mode
- use `/skills` to inspect what Codex can currently see in the active project, `/skills search <keyword>` for related matches, and `/skills show <index>` to understand what a skill is for before enabling or disabling it
- use `/auto add ...` in natural language first; the bridge will draft a schedule, then `/auto confirm` creates the job
Expand Down
10 changes: 9 additions & 1 deletion docs/todo/codex-gateway.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,14 @@
This document tracks the implementation backlog for
`@codexbridge/codex-gateway`.

## Status

This workstream is currently paused.

Keep this document as a historical backlog and reference. It should not be
treated as an active implementation queue unless the product direction changes
again.

It is the execution-oriented companion to:

- `docs/architecture/codexbridge-core-architecture.md`
Expand Down Expand Up @@ -60,7 +68,7 @@ Avoid frequent edits here unless the change is truly cross-cutting:
- `README.md`
- `package.json`

## Current Active Focus
## Last Active Focus

- [x] Stop treating OpenRouter live smoke as an active Phase 4 blocker; defer it until credentials are available again
- [x] Keep new provider onboarding config-first and capability-driven instead of adding one-off provider classes
Expand Down
10 changes: 9 additions & 1 deletion docs/todo/codex-native-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,14 @@
This document tracks the implementation backlog for the `track/codex-native-api`
workstream.

## Status

This workstream is retained as the only package-level backend candidate still
kept for possible future development, but it is currently paused.

Keep this document as a preserved backlog and reference point. It should not be
treated as an active implementation queue right now.

It is the execution-oriented companion to:

- `docs/architecture/codexbridge-core-architecture.md`
Expand Down Expand Up @@ -44,7 +52,7 @@ It should **not** own:
- user-facing slash-command policy unless a command is explicitly added later
- commercial billing, top-up, or payment workflows

## Track Branch
## Historical Track Branch

Primary long-lived branch for this workstream:

Expand Down
8 changes: 8 additions & 0 deletions docs/todo/mission-control.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,14 @@
This document tracks the implementation backlog for
`@codexbridge/mission-control`.

## Status

This workstream is currently paused.

Keep this document as a historical backlog and reference. It should not be
treated as an active implementation queue unless the product direction changes
again.

It is the execution-oriented companion to:

- `docs/architecture/mission-control.md`
Expand Down
41 changes: 26 additions & 15 deletions docs/todo/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,25 @@ This document is the top-level roadmap for CodexBridge.
It should stay short and stable. Detailed implementation checklists belong in
feature-specific TODO files instead of being expanded here.

## Current Status

- `packages/codex-gateway`: paused
- `packages/mission-control`: paused
- `packages/codex-native-api`: retained for possible future work, but currently paused
- active package-level development is intentionally on hold until the bridge direction is narrowed again

## Immutable Target

CodexBridge 的目标是通过微信稳定暴露 Codex 原生能力,并在桥接层扩展微信命令和个人助理工作流;`@codexbridge/codex-gateway` 的目标是让 Codex 稳定接入多模型来源
CodexBridge 的目标是通过微信稳定暴露 Codex 原生能力,并在桥接层扩展微信命令和个人助理工作流。

This target is stable. The route, package layout, and branch strategy may
change, but every new task should be judged against whether it advances this
target.

## Working Branch Model
## Historical Package Branch Model

The repository should be developed through long-lived workstream branches, not
one short-lived branch per tiny feature:
These long-lived workstream branches remain as historical references for the
paused package work:

```text
main
Expand All @@ -35,10 +42,9 @@ track/codex-native-api
Rules:

- `main` should stay mergeable and reasonably stable
- `track/codex-gateway` should primarily own Codex Gateway protocol/package work
- `track/mission-control` should primarily own Mission Control runtime/package work
- `track/codex-native-api` should primarily own Codex-native API exposure, localhost facade design, and isolated side-task routing policy
- `track/codex-native-api` should also preserve a clean extraction path toward a reusable package if the native-api boundary stabilizes
- `track/codex-gateway` is paused
- `track/mission-control` is paused
- `track/codex-native-api` is retained for possible future resumption, but it is also paused right now
- low-level checklist churn should stay out of this file
- avoid frequent concurrent edits to shared files such as:
- `docs/todo/roadmap.md`
Expand All @@ -49,17 +55,17 @@ Rules:

Use these files for detailed implementation work:

- [Codex Gateway TODO](./codex-gateway.md)
- [Mission Control TODO](./mission-control.md)
- [Codex Native API TODO](./codex-native-api.md)
- [Codex Native API TODO](./codex-native-api.md) - retained for later
- [Codex Gateway TODO](./codex-gateway.md) - paused
- [Mission Control TODO](./mission-control.md) - paused

Architecture references:

- [Core architecture](../architecture/codexbridge-core-architecture.md)
- [Mission Control architecture](../architecture/mission-control.md)
- [Codex Native API architecture](../architecture/codex-native-api.md)
- [Mission Control architecture](../architecture/mission-control.md) - historical reference

Reference sources currently tracked:
Reference sources currently tracked for later reuse:

- `reference/codex-gateway` for LiteLLM, codex-proxy, open-responses, and llm-rosetta
- `reference/symphony` as the orchestration reference mirror when available
Expand All @@ -72,7 +78,6 @@ Reference sources currently tracked:
Already landed and no longer part of the active detailed backlog:

- `/review` for uncommitted changes and base-branch review
- `/agent` experimental Codex-first hybrid background jobs with draft-confirm, full-access Codex execution, verifier checks, and retry
- `/plan` session-level native planning mode toggle
- `/skills`, `/apps`, `/plugins`, and `/mcp` visibility and control surfaces
- `/automation` draft-confirm flow and WeChat delivery-oriented scheduling
Expand Down Expand Up @@ -118,6 +123,8 @@ affect the product as a whole, not just one package.

### P2: Codex Gateway summary

Current status: paused.

- [x] Prove end-to-end profile switching across OpenAI-native, DeepSeek, MiniMax, Qwen, and OpenRouter without changing WeChat UX
- [ ] Revisit standalone launcher publication only if product direction changes; it is intentionally internal-only for now
- [ ] Keep deferred OpenRouter live validation clearly separated from completed package-local protocol work
Expand All @@ -128,6 +135,8 @@ Detailed checklist:

### P2: Codex Native API summary

Current status: retained for possible future work, but currently paused.

- [ ] Expose the logged-in local Codex runtime as a localhost Responses-first API without changing the main WeChat chat flow
- [ ] Route isolated side tasks to Codex Native API while keeping full conversation tasks on the current Codex app-server path
- [ ] Keep external provider APIs as fallback/optional paths rather than the primary route for isolated subtasks
Expand All @@ -139,6 +148,8 @@ Detailed checklist:

### P2: Mission Control summary

Current status: paused.

- [x] Preserve Symphony's real core ideas: workflow-owned policy, single orchestrator authority, stable workspace identity, continuation retries after normal exit, and handoff/wait-user states
- [x] Add workflow loading, workpad persistence, workspace isolation, and bounded run/verify/repair loop
- [x] Keep WeChat as the control and notification entrypoint while Mission Control owns orchestration
Expand All @@ -151,7 +162,7 @@ Detailed checklist:

- [ ] Do not prioritize new bridge-only slash commands ahead of high-value native Codex parity work unless the native layer is unavailable
- [ ] Do not add bridge-only aliases when existing commands already cover the user need well enough, such as `/open` for resume-style continuation or `/status` for cwd/session inspection
- [ ] Do not let this file become a second detailed implementation log for Codex Gateway or Mission Control
- [ ] Do not let this file become a second detailed implementation log for paused package workstreams

## Later Direction: Telegram Runtime

Expand Down
45 changes: 1 addition & 44 deletions docs/usage/weixin-slash-commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ It borrows the most useful CLI help conventions while staying chat-friendly:
- `/helps` shows the full command catalog
- `/helps <command>` shows one command in detail
- every slash command supports `-h`, `--help`, `-help`, and `-helps`
- every slash command also supports a short alias such as `/h`, `/st`, `/us`, `/lg`, `/sp`, `/rv`, `/ag`, `/sk`, `/n`, `/up`, `/as`, `/td`, `/rmd`, `/nt`, `/pd`, `/ms`, `/m`, `/psn`, `/ins`, `/th`, `/se`, `/nx`, `/pv`, `/o`, `/pk`, `/rn`, `/perm`, `/al`, `/dn`, `/rc`, `/rt`, and `/rs`
- every slash command also supports a short alias such as `/h`, `/st`, `/us`, `/lg`, `/sp`, `/rv`, `/sk`, `/n`, `/up`, `/as`, `/td`, `/rmd`, `/nt`, `/pd`, `/ms`, `/m`, `/psn`, `/ins`, `/th`, `/se`, `/nx`, `/pv`, `/o`, `/pk`, `/rn`, `/perm`, `/al`, `/dn`, `/rc`, `/rt`, and `/rs`
- `/lang` and `/lang <zh|en>` to switch reply language for this scope (higher priority than env).
- thread browsing is index-first on WeChat, so `/open 2` is preferred over copying raw thread ids
- before the bot reaches roughly 10 consecutive replies, the user can proactively send a single `/` to break the WeChat-side frequency limit; it is swallowed by the bridge, not forwarded to Codex, and does not create a reply
Expand All @@ -48,12 +48,6 @@ It borrows the most useful CLI help conventions while staying chat-friendly:
/rv
/review base main
/review commit HEAD~1
/agent 帮我检查当前项目测试并修复失败项
/agent confirm
/agent show 1
/agent result 1
/agent result 1 file
/agent send 1
/skills
/sk
/skills search 新闻
Expand Down Expand Up @@ -222,43 +216,6 @@ Examples:
/review 重点看 Agent 状态流转相关改动的回归风险
```

### `/agent` and `/ag`

Create a confirmed background Agent job for deeper multi-step work.

- `/agent <task>` creates a draft instead of executing immediately
- `/agent confirm` confirms the draft and queues the background job
- `/agent edit <change instruction>` refines the current draft by merging the new instruction back into the existing draft
- `/agent list` lists jobs for the current WeChat chat
- `/agent show <index>` shows the plan, status, attempts, and verifier result
- `/agent result <index>` shows the full text result in pages
- `/agent result <index> file` exports the full text result as a phone-friendly TXT attachment
- `/agent send <index>` resends saved attachments for a completed job
- `/agent stop <index>` requests stop for the job
- `/agent retry <index>` queues a failed/stopped/completed job again
- `/agent rename <index> <title>` updates the local job title
- `/agent del <index>` deletes the job record

Examples:

```text
/agent 检查当前项目测试并修复失败项
/ag 写一份 CodexBridge Agent 接入方案
/agent confirm
/agent edit 只做方案,不改代码
/agent list
/agent show 1
/agent result 1
/agent result 1 2
/agent result 1 file
/agent send 1
/agent stop 1
/agent retry 1
/agent del 1
```

Implementation note: planning, draft editing, and verification reuse the Provider currently bound to the WeChat chat first. Background execution continues on the detached task session created from that same Provider profile. Long text results are kept separately from the preview, so `/agent result <index>` can page through the full answer and `/agent result <index> file` can export it as phone-friendly TXT. Jobs with generated attachments keep artifact records, so `/agent send <index>` can resend the file if WeChat rate-limits the first delivery.

### `/as`, `/log`, `/todo`, `/remind`, and `/note`

Save personal assistant records from WeChat.
Expand Down
7 changes: 7 additions & 0 deletions packages/codex-gateway/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,13 @@

Internal package for the Codex Gateway protocol layer.

## Status

Development for this package is currently paused.

It remains in the repository as historical/internal reference material, but it
is not part of the active roadmap at this time.

Current release policy:

- keep this package `private: true`
Expand Down
Loading
Loading