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
15 changes: 13 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,15 @@ You shouldn't have to notice, switch chats, and explain the change again.
You don't need two different products: two sessions of the same agent can collaborate.

**You choose which sessions join. The models choose when a message is useful.**
ThreadMesh supplies discovery, advisory messages, a persistent inbox and portable
checkpoints—not a new model, shared chat history or a fixed sequence of handoffs.
The workspace supplies discovery, advisory messages, a persistent inbox and portable
checkpoints—not a new model or shared chat history. The optional Codex desktop
skill instead uses **Codex's native task tools**; it does not add that transport.

**Doesn't Codex already do this? Yes, on the tested host.** If its native task
tools meet your needs, use them directly. The skill adds reusable collaboration
guidance; the workspace adds coordination for supported integrations. We have
not proved the skill outperforms native Codex alone.
[What is native, what we add, and when not to install →](docs/00-overview/native-capabilities-and-value.md)

<p align="center">
<img src="docs/assets/threadmesh-session-initiative.jpg" width="100%" alt="Concept: Agent A sends advice from another task to Agent B while unrelated work stays quiet">
Expand All @@ -34,6 +41,10 @@ checkpoints—not a new model, shared chat history or a fixed sequence of handof

## A real handoff without the copy-paste

[Read the actual desktop exchange and B's own diff →](docs/evidence/codex-native-2026-09-07/README.md)
Retained native records, with busy/stop checks; not a screenshot or reenactment.
The separate installed-package example below is also retained.

**Two Codex sessions. One remembers your earlier decision; the other changes the
product facts. You don't relay the change.**

Expand Down
12 changes: 10 additions & 2 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,13 @@
不必换两种产品:同一个 Agent 的两个 session 就能协作。

**你决定哪些 session 加入,模型判断什么时候值得联系。**
ThreadMesh 提供目标发现、建议消息、持久收件箱和可携带的 checkpoint。
它不是新模型、共享聊天记录,也不是把每次交接都写死的工作流。
Workspace 提供目标发现、建议消息、持久收件箱和可携带的 checkpoint,
不是新模型或共享聊天记录。可选的桌面 Skill 则使用 **Codex 已有的原生任务工具**,
并没有新增这套通信能力。

**Codex 自己不是就能做吗?在实测宿主上,是的。** 原生功能够用,就直接用原生。
Skill 提供可复用协作规则,workspace 为已支持的集成提供协调能力;目前没有证明
Skill 比原生 Codex 更有效。[哪些是原生、我们增加什么、何时不需要安装 →](docs/zh-CN/native-capabilities-and-value.md)

<p align="center">
<img src="docs/assets/threadmesh-session-initiative.jpg" width="100%" alt="概念示意:Agent A 向 Agent B 发送来自另一任务的建议,无关工作保持安静">
Expand All @@ -34,6 +39,9 @@ ThreadMesh 提供目标发现、建议消息、持久收件箱和可携带的 ch

## 一次不用你转述的真实协作

[查看实际桌面消息与 B 自己的修改 →](docs/zh-CN/native-evidence.md)
保留的原生记录,含忙碌/停止检查;不是截图或重演。下面另保留安装包案例。

**两个 Codex session:一个记着你之前的约定,另一个修改产品事实。你不用转述变化。**

在安装包真实运行中,网站 session 先自主说明了依赖,品牌 session 随后自行决定发送相关变化。
Expand Down
18 changes: 18 additions & 0 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,24 @@ policy layer; A2A, Cotal, ACP, or harness-native APIs may supply transport.

## Active priority — existing desktop clients (2026-09-07)

**Native-value checkpoint:** Codex already supplies the tested native messaging
and continuation. The skill is optional guidance, not new transport. Read the
[responsibility map and when not to install](docs/00-overview/native-capabilities-and-value.md).
The [retained desktop evidence](docs/evidence/codex-native-2026-09-07/README.md)
shows feasibility, not improvement over native Codex alone.

The next product slice must reduce a real user's setup/relay burden: simple
explicit pair selection, retained decisions, and clear pending/applied outcomes.
Then compare a small matched native-only workflow with the added guidance;
record setup actions, manual relays, correct receiver edits and unwanted contact.
Do not build a benchmark platform or add harnesses for this comparison. If no
gain is observed, retain a lightweight optional recipe rather than a new platform.

For community growth, first make one independent Codex user's own pair succeed;
fix their first blocker, then prepare a consented real recording and a concise
case study. Existing issue replies remain deferred as requested. No fabricated
video, unsolicited promotion or guaranteed star count.

Primary audience: **Codex users**, especially separate existing conversations
inside Codex desktop. Pi is a supported option, not a prerequisite or replacement.
A Codex-only first-use entry must reuse the user's own Codex login/model, never
Expand Down
72 changes: 72 additions & 0 deletions docs/00-overview/native-capabilities-and-value.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# If Codex already does this, why ThreadMesh?

**You may not need ThreadMesh.** On the tested Codex desktop host, native tools
already read task status, send messages to another task, attribute their source
and continue the receiver. The model can choose those tools without ThreadMesh
inventing the communication capability. The original “sent from another task”
moment belongs to Codex, not to this project.

The official [App Server lifecycle](https://learn.chatgpt.com/docs/app-server#lifecycle-overview)
also documents threads, continuation, active-turn steering and events. It does
not establish that every desktop distribution exposes the same cross-task tools.
Our [native task record](../evidence/codex-native-2026-09-07/README.md) establishes
the narrower observed host behavior. App Server primitives are not an API for
silently attaching an external service to arbitrary existing desktop tasks.

## Two routes, different responsibilities

| Capability | Native Codex + ThreadMesh skill | ThreadMesh workspace / adapters |
|---|---|---|
| Model reasoning and deciding relevance | Codex model, guided by the skill | Host model, guided by tools/context |
| Cross-task transport, source badge, native continuation | **Codex supplies these** | ThreadMesh protocol/coordinator and supported adapter supply routing; wake is host-specific |
| Selected goals, advisory scope, busy/stop behavior | Model-followed skill instructions; not enforced isolation | Explicit room membership, mute, bounded sends and receiver dispositions; same-owner local boundary |
| Durable mailbox and message disposition | Codex native history; no ThreadMesh mailbox in this route | SQLite mailbox and separate delivery/decision/outcome fields |
| Portable work checkpoint | Not supplied by the native skill | Explicit saved checkpoint, not full transcript or permission migration |
| Evidence so far | One controlled prior-context pair, own receiver edit and busy/stop checks | Versioned maintainer runs and one independent first-use report; gaps vary by adapter |

Implementation: [native skill](../../plugins/threadmesh-codex/skills/threadmesh-codex/SKILL.md),
[workspace](../../src/workspace/local-workspace.mjs),
[compatibility and failures](harness-support.md).

Do not transfer workspace persistence, admission or mute enforcement into a claim
about the skill-only desktop path. Conversely, a native desktop success does not
prove an external cross-harness adapter can do the same thing.

## What is valuable today—and what is still a hypothesis

The native skill is a reusable, reviewed opt-in workflow: selected peers/topics,
narrow advisory messages, fresh status checks, retained constraints, stop behavior
and an explicit distinction between delivery and useful completion. Its incremental
value is **modest today**. A user can express similar rules directly to Codex.
The successful demonstration proves that this workflow can work, not that it is
necessary, unique, more reliable or faster than native Codex alone. There is no
matched native-only versus skill comparison yet.

The workspace route additionally implements shared coordination primitives for
supported integrations and explicit portable checkpoints. That is real code,
but generic desktop plug-and-play, meaningful quota-blocked recovery and broad
cross-product correctness remain unproven. Architecture alone is not user value.

**Use native Codex directly** if its existing task tools already solve your
same-client need with acceptable setup and control. Try the skill for repeatable
scoped collaboration guidance. Consider the workspace when you actually need a
persistent cross-session inbox or supported cross-harness integration and accept
its current setup cost. For one conversation, add neither layer.

## The product must earn its place

The immediate promise to work toward is: **tell related tasks once, stop being
their messenger, and see whether the receiving task actually acted correctly.**

1. Make pairing usable in Codex without copying IDs, editing JSON or installing
a developer runtime. Preserve explicit selection and user control.
2. Retain user decisions across useful handoffs and expose pending versus applied
state. A delivery badge alone is not sufficient.
3. Save reviewed proof from actual user work. Then compare native-only use with
the smallest ThreadMesh addition: setup burden, manual relays, useful edits,
unwanted contacts and failure recovery—not messages sent or internal test counts.

If that comparison shows no useful gain, keep the Codex integration a small
optional recipe instead of inflating it into a platform. Portable coordination
must independently earn its own use case. Community growth follows repeatable
first-user success and honest evidence, not a promised star count.
15 changes: 10 additions & 5 deletions docs/00-overview/product-guide.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,12 @@
# What ThreadMesh is

ThreadMesh connects independent agent sessions to an explicitly shared local
workspace. The aim is simple: **you should not have to relay every useful change
between agents yourself**.
ThreadMesh offers an explicit local workspace for supported integrations and an
optional skill workflow over Codex's native task tools. The aim is simple:
**you should not have to relay every useful change between agents yourself**.

Codex already supplies native cross-task communication on the tested host. The
skill did not invent it, and may be unnecessary if native use meets your needs.
[Native capabilities versus ThreadMesh's current value](native-capabilities-and-value.md).

A session is one agent conversation with its own task and context. A harness
is the application running it, such as Codex or Pi. ThreadMesh connects opted-in
Expand Down Expand Up @@ -43,8 +47,9 @@ it is not a production service or an npm-published release.
## What the “intelligence” means

Models choose relevance and message content under configured collaboration
guidance. ThreadMesh supplies discovery, persistence, provenance and lifecycle
integration. It does not hard-code every handoff or guarantee useful choices.
guidance. In the workspace route, ThreadMesh supplies discovery, persistence and
adapter integration. In the native skill route, Codex supplies the transport,
source attribution and continuation. Neither route guarantees useful choices.

A real unrelated-change control stayed quiet despite available peer/inbox tools.
A second copy case delivered and resumed correctly but lost a free-plan qualifier.
Expand Down
9 changes: 7 additions & 2 deletions docs/06-guides/real-world-cases.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,13 @@ reproduction and audit.

## Start with the everyday-work test

The latest [ordinary Codex → Pi evidence](../09-reviews/2026-09-05-workspace-awareness.md)
is the best starting point for the current alpha:
For the current Codex audience, start with the [actual native desktop exchange](../evidence/codex-native-2026-09-07/README.md):
one explicitly opted-in prior-context pair, original B's own correct edit, and
busy/stop controls. Codex provided native transport. See the [evidence library](../evidence/README.md)
for preserved recent CLI passes and failures; none is a native-only benefit comparison.

The earlier [ordinary Codex → Pi evidence](../09-reviews/2026-09-05-workspace-awareness.md)
retains the cross-harness baseline:

| Ordinary task | Result | What it establishes |
|---|---|---|
Expand Down
5 changes: 5 additions & 0 deletions docs/09-reviews/2026-09-07-native-desktop-acceptance.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,11 @@ No monitor, global configuration or installation requires cleanup.

## Evidence and remaining limits

Public inspection: [reviewed native excerpts and actual diff](../evidence/codex-native-2026-09-07/README.md)
and [structural audit](../evidence/codex-native-2026-09-07/audit.json). The audit tool
emits no raw IDs, paths or prose; it checks supplied export structure, not business
correctness or host authenticity. No screenshot or recording is implied.

Complete native histories were read through the exposed task tool: six turns in A
and five in B, with no further history page. A has exactly one outgoing native
send, to B; B has none. No task-list call or unrelated target appears in either
Expand Down
7 changes: 7 additions & 0 deletions docs/10-planning/community-followup-2026-09-07.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,13 @@ goal because the smaller new-session example is easier to validate.

## Deferred reply and execution discipline

Subsequent native desktop evidence is now retained as [actual excerpts and diff](../evidence/codex-native-2026-09-07/README.md).
That controlled prior-context pair passed; it is not this contributor's independent
live result. The [native-value correction](../00-overview/native-capabilities-and-value.md)
credits Codex's existing transport and discloses that the skill has no measured
advantage over native-only use. These are material clarifications to include when
a reply is authorized, not reasons to post another immediate acknowledgement.

The user explicitly asked us to make several real improvements before replying
again. Therefore do not post another acknowledgement, roadmap promise, test
request or issue closure now. Continue implementation, review and verification
Expand Down
9 changes: 9 additions & 0 deletions docs/10-planning/project-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@

## Current product update — 2026-09-07

**Value and evidence correction:** the native demo uses Codex's own communication
and continuation; the skill adds guidance, not transport. [English responsibility
map](../00-overview/native-capabilities-and-value.md) / [中文](../zh-CN/native-capabilities-and-value.md)
now state when native Codex is enough and that incremental benefit is unmeasured.
The [public proof pack](../evidence/codex-native-2026-09-07/README.md) preserves
reviewed excerpts, actual receiver diff and a content-free structural audit.
No screenshot or video of that run exists. Next focus on pairing, meaningful
receiver outcomes and one independent user's success, not another adapter matrix.

**Latest Codex-first delivery:** Codex is primary; Pi is optional, not a required
second product. The [installed-package case](../09-reviews/2026-09-07-codex-first-use-release.md)
now passes in 272.604 seconds with the default command and unchanged five-minute
Expand Down
2 changes: 2 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ Start with the user guides; the protocol and historical benchmarks are optional.
| I want to… | Start here |
|---|---|
| Understand the idea | [What ThreadMesh is](00-overview/product-guide.md) |
| Know whether native Codex is enough | [Native capabilities and added value](00-overview/native-capabilities-and-value.md) |
| Inspect the actual desktop exchange | [Retained messages, diff and audit](evidence/codex-native-2026-09-07/README.md) |
| Connect Codex, Pi, Kimi or DeepSeek | [Your first workspace](06-guides/first-workspace.md) |
| Explore existing Codex desktop tasks | [Experimental native-task workflow](06-guides/codex-native-tasks.md) |
| See actual model behavior | [Everyday cases and evidence](06-guides/real-world-cases.md) |
Expand Down
28 changes: 28 additions & 0 deletions docs/evidence/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Evidence library

Use records to support a specific claim, not as substitutes for independent
adoption or proof of incremental value over the host's native capability.

| Recent case | Public record | Retained private originals |
|---|---|---|
| Codex desktop prior-context pair | [Actual exchange, B's diff and reduced audit](codex-native-2026-09-07/README.md) | Complete A/B native exports, original tasks and files |
| Codex default installed-package pass, 272.604 s | [Acceptance](../09-reviews/2026-09-07-codex-first-use-release.md) | Events, report, transcripts and sample artifacts copied to a dated non-temporary archive |
| Codex diagnostic pass, 184.050 s | [Same record, separate budget](../09-reviews/2026-09-07-codex-first-use-release.md) | Same archive categories; not counted as the default gate |
| Codex old-runtime failure | [Failure retained alongside passes](../09-reviews/2026-09-07-codex-first-use-release.md#failures-that-changed-the-implementation) | Events and failed-run report copied to the dated archive |
| Pi copy and installed-package API passes | [Acceptance and event commitments](../09-reviews/2026-09-07-packaged-first-use.md) | Both sample directories copied to the dated non-temporary archive |

All five copied CLI event files match the SHA-256 commitments in the original
acceptance records. The original temporary directories were not removed. Private
archives are outside the public repository, in owner-only parent directories;
they are local retention, not off-device backup. No raw model logs, account data
or unrelated task histories were uploaded.

No screenshot or video was captured for these listed recent runs. Earlier
concept images and staged animations are not retroactive proof. The desktop
[capture policy](codex-native-2026-09-07/README.md#screenshots-and-recordings)
describes consent, cropping, originals and truthful retrospective labels.

For older adapter experiments and failures, use the
[case portfolio](../06-guides/real-world-cases.md) and
[dated review index](../09-reviews/README.md). Their documentation is retained;
this index does not claim every historical raw recording has been recovered.
Loading
Loading