agent-things 0.0.0-stage → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/LICENSE +21 -0
  2. package/NOTICE +5 -0
  3. package/README.md +221 -2
  4. package/README.zh-CN.md +222 -0
  5. package/bin/agent-things.cjs +8 -0
  6. package/bin/antigravity-session-status.cjs +96 -0
  7. package/bin/claude-session-status.cjs +55 -0
  8. package/bin/codex-session-status.cjs +287 -0
  9. package/mods/agent-things-ui/.claude-plugin/plugin.json +12 -0
  10. package/mods/agent-things-ui/SKILL.md +10 -0
  11. package/mods/agent-things-ui/hooks/controls.js +112 -0
  12. package/mods/agent-things-ui/hooks/foundation.js +431 -0
  13. package/mods/agent-things-ui/hooks/hooks.json +1 -0
  14. package/mods/agent-things-ui/hooks/presentation.js +223 -0
  15. package/mods/agent-things-ui/hooks/progress.js +1 -0
  16. package/mods/agent-things-ui/hooks/register.js +382 -0
  17. package/native/bin/bridge +0 -0
  18. package/native/bin/bridge.json +20 -0
  19. package/native/session-status-bridge.swift +280 -0
  20. package/outputs/antigravity-session-status.js +2476 -0
  21. package/outputs/codex-session-status.js +1761 -0
  22. package/package.json +75 -4
  23. package/scripts/build-antigravity-bundle.cjs +35 -0
  24. package/scripts/build-codex-bundle.cjs +31 -0
  25. package/scripts/build-native-bridge.cjs +55 -0
  26. package/scripts/build-shared-ui.cjs +16 -0
  27. package/scripts/setup-antigravity-service.cjs +71 -0
  28. package/scripts/setup-claude-service.cjs +21 -0
  29. package/skills/agent-things/SKILL.en.md +95 -0
  30. package/skills/agent-things/SKILL.md +99 -0
  31. package/skills/codex/things/SKILL.en.md +10 -0
  32. package/skills/codex/things/SKILL.md +10 -0
  33. package/skills/things/SKILL.en.md +10 -0
  34. package/skills/things/SKILL.md +10 -0
  35. package/skills/things/checklist.en.md +91 -0
  36. package/skills/things/checklist.md +95 -0
  37. package/src/analysis-app-server.cjs +74 -0
  38. package/src/analysis-assets/output.en.schema.json +93 -0
  39. package/src/analysis-assets/output.schema.json +93 -0
  40. package/src/analysis-assets/prompt.en.txt +17 -0
  41. package/src/analysis-assets/prompt.zh-CN.txt +18 -0
  42. package/src/analysis-budget.cjs +105 -0
  43. package/src/analysis-git.cjs +38 -0
  44. package/src/analysis-history.cjs +150 -0
  45. package/src/analysis-ledger.cjs +82 -0
  46. package/src/analysis-log.cjs +62 -0
  47. package/src/analysis-runner.cjs +203 -0
  48. package/src/analysis-service.cjs +197 -0
  49. package/src/analysis-source.cjs +72 -0
  50. package/src/antigravity-card.cjs +2063 -0
  51. package/src/antigravity-hook.cjs +138 -0
  52. package/src/antigravity-mcp-config.cjs +36 -0
  53. package/src/app-server.cjs +96 -0
  54. package/src/cdp.cjs +115 -0
  55. package/src/claude-inline-install.cjs +38 -0
  56. package/src/claude-mcp-config.cjs +29 -0
  57. package/src/cli/arguments.cjs +30 -0
  58. package/src/cli/environment-probe.cjs +130 -0
  59. package/src/cli/integration-state.cjs +15 -0
  60. package/src/cli/interactive-cli.cjs +236 -0
  61. package/src/cli/prompt-tui.cjs +420 -0
  62. package/src/cli/setup-orchestrator.cjs +449 -0
  63. package/src/codex-mcp-config.cjs +67 -0
  64. package/src/harnesses/antigravity/analysis-profile.cjs +41 -0
  65. package/src/harnesses/antigravity/antigravity-git.cjs +89 -0
  66. package/src/harnesses/antigravity/antigravity-harness.js +1477 -0
  67. package/src/harnesses/antigravity/antigravity-injector.cjs +104 -0
  68. package/src/harnesses/antigravity/antigravity-migration.cjs +235 -0
  69. package/src/harnesses/antigravity/antigravity-service.cjs +357 -0
  70. package/src/harnesses/antigravity/antigravity-title.cjs +155 -0
  71. package/src/harnesses/antigravity/gemini-runner.cjs +304 -0
  72. package/src/harnesses/antigravity/transcript-cleaner.cjs +129 -0
  73. package/src/harnesses/antigravity/transcript-source.cjs +100 -0
  74. package/src/harnesses/claude/claude-harness.js +93 -0
  75. package/src/harnesses/claude/claude-host-helper.cjs +176 -0
  76. package/src/harnesses/claude/claude-injector.cjs +95 -0
  77. package/src/harnesses/claude/claude-local-source.cjs +106 -0
  78. package/src/harnesses/claude/claude-navigation.cjs +99 -0
  79. package/src/harnesses/claude/claude-runner.cjs +74 -0
  80. package/src/harnesses/claude/claude-service.cjs +313 -0
  81. package/src/harnesses/claude/claude-source.cjs +70 -0
  82. package/src/harnesses/codex/codex-analysis.cjs +10 -0
  83. package/src/harnesses/codex/codex-card-bridge.js +123 -0
  84. package/src/harnesses/codex/codex-card-events.cjs +76 -0
  85. package/src/harnesses/codex/codex-card.cjs +169 -0
  86. package/src/harnesses/codex/codex-git.cjs +24 -0
  87. package/src/harnesses/codex/codex-harness.js +229 -0
  88. package/src/harnesses/codex/codex-local-card.js +97 -0
  89. package/src/harnesses/codex/codex-progress-context.cjs +84 -0
  90. package/src/harnesses/codex/codex-service.cjs +502 -0
  91. package/src/i18n.cjs +174 -0
  92. package/src/launchd.cjs +105 -0
  93. package/src/lifecycle-lock.cjs +13 -0
  94. package/src/local-progress-http.cjs +267 -0
  95. package/src/manual-status-agent.cjs +12 -0
  96. package/src/manual-status-startup.cjs +66 -0
  97. package/src/manual-status-store.cjs +466 -0
  98. package/src/mcp-stdio.cjs +67 -0
  99. package/src/model-router.cjs +63 -0
  100. package/src/native-bridge.cjs +17 -0
  101. package/src/npm-updates.cjs +228 -0
  102. package/src/plugins/things/assets/logo.svg +13 -0
  103. package/src/plugins/things/plugin.json +6 -0
  104. package/src/plugins/things/sidecars/things_board/app.js +447 -0
  105. package/src/plugins/things/sidecars/things_board/index.html +2141 -0
  106. package/src/plugins/things/sidecars/things_board/main.mjs +652 -0
  107. package/src/plugins/things/sidecars/things_board/package.json +6 -0
  108. package/src/plugins/things/sidecars/things_board/sidecar.json +21 -0
  109. package/src/plugins/things/sidecars/things_board/styles.css +560 -0
  110. package/src/plugins/things/sidecars/things_board/ui-i18n.mjs +434 -0
  111. package/src/progress-error.cjs +54 -0
  112. package/src/progress-tools.cjs +145 -0
  113. package/src/project-path.cjs +15 -0
  114. package/src/renderer-resource.cjs +17 -0
  115. package/src/request-budget.cjs +24 -0
  116. package/src/resolve.cjs +51 -0
  117. package/src/runtime-install.cjs +635 -0
  118. package/src/session-status-filter.cjs +136 -0
  119. package/src/session-status.js +992 -0
  120. package/src/session-view.cjs +34 -0
  121. package/src/startup/controller.cjs +354 -0
  122. package/src/startup/watch.cjs +126 -0
  123. package/src/state-file-lock.cjs +31 -0
  124. package/src/task-provenance.cjs +42 -0
  125. package/src/ui-foundation.cjs +435 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 snuffpic
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/NOTICE ADDED
@@ -0,0 +1,5 @@
1
+ Agent Things
2
+ Copyright (c) 2026 snuffpic
3
+
4
+ 本项目以 MIT 许可发布,许可全文见 LICENSE。
5
+ 本项目不包含第三方源代码,npm 包也没有运行时依赖。
package/README.md CHANGED
@@ -1,3 +1,222 @@
1
- # Temporary Holding Version
1
+ # Agent Things
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ English | [简体中文](README.zh-CN.md)
4
+
5
+ When you juggle several sessions at once, or come back to one you haven't touched in a while, Agent Things shows you at a glance how far each session has got and what is still open, so you can decide whether to archive it or keep following up. You can also jump from any task back to the message it came from.
6
+
7
+ Agent Things is a session progress plugin for AI coding sessions on macOS. It supports local sessions in **ChatGPT**, **Antigravity** and **Claude Desktop**. Inspired by [Things 3](https://culturedcode.com/things/): one progress ring sums up where a piece of work stands, and opening it gives you a clear to-do list.
8
+
9
+ > This is a beta release; see Known limitations below. This project is not affiliated with Cultured Code, OpenAI, Google or Anthropic.
10
+
11
+ <table>
12
+ <tr>
13
+ <td width="50%"><img src="assets/readme/sidebar-panel.png" alt="Progress rings in the session list and the status panel"></td>
14
+ <td width="50%"><img src="assets/readme/manual-adjust.png" alt="Manually recording a session's status, progress and notes"></td>
15
+ </tr>
16
+ <tr>
17
+ <td align="center">Progress rings in the session list and the status panel</td>
18
+ <td align="center">Adjust status, progress and notes by hand</td>
19
+ </tr>
20
+ <tr>
21
+ <td width="50%"><img src="assets/readme/claude-inline-card.png" alt="The /things progress card in a Claude session"></td>
22
+ <td width="50%"><img src="assets/readme/antigravity-panel.png" alt="The Things side panel in Antigravity"></td>
23
+ </tr>
24
+ <tr>
25
+ <td align="center">Type <code>/things</code> in a session to see its progress (Claude)</td>
26
+ <td align="center">The Things side panel in Antigravity</td>
27
+ </tr>
28
+ </table>
29
+
30
+ ## Features
31
+
32
+ **See progress at a glance**
33
+
34
+ - Each item in the session list gets a progress ring; the number is the completion percentage. The color shows the session's state: gray for not started, gold for remaining items, blue for completed, and purple for completed and pushed to the remote (for example origin/main).
35
+ - Click the ring to open the status panel, with the session's state, completion rate, a one-line summary, remaining tasks and completed tasks.
36
+
37
+ **Tasks organized for you**
38
+
39
+ - Click **Update progress** and the plugin reads the conversation, asks the model you are already signed in to for a task list, separates completed from remaining items and flags blocked tasks.
40
+ (By default it picks the most cost-effective model in each client: ChatGPT: Luna, Claude Code: Haiku, Antigravity: Gemini 3.8.)
41
+ - Later updates only process new messages; existing tasks and completion records stay as they are.
42
+ - Every task links back to the message it came from, so you can check it.
43
+
44
+ **Record things yourself**
45
+
46
+ - **Adjust** lets you set the state (Not started / Remaining items / Completed), drag the progress and write notes.
47
+ - **Clear** removes the session's progress, tasks, notes and history.
48
+
49
+ **Ask from inside the session**
50
+
51
+ - Type `/things` in any session and the model reads the checklist, shows a progress card in the conversation, and reads or updates progress (works together with the bundled skill).
52
+ - The plugin also registers MCP tools (read / update progress, update tasks, list all sessions, clear progress), so the assistant can record progress on its own while it works.
53
+
54
+ **English and Chinese**
55
+
56
+ - The interface, the `/things` card, the skills and the tasks the model writes all use one language: English or Simplified Chinese.
57
+ - The first install suggests your system language; you can switch it later from the management menu. After switching, the next **Update progress** rewrites existing tasks in the new language.
58
+
59
+ ## Supported clients
60
+
61
+ | Client | Where it shows | First-time setup |
62
+ | --- | --- | --- |
63
+ | ChatGPT | Progress rings in the session list, status panel, `/things` | None. Open it from the Dock as usual; see "Why does ChatGPT close and reopen once?" below |
64
+ | Antigravity | Progress rings in the session list, Things side panel, `/things` | None |
65
+ | Claude Desktop (local Code sessions) | `/things` card in the conversation; session-list rings must be turned on | Run `/reload-plugins` after installing; for session-list rings, turn on **Developer → Enable Main Process Debugger** |
66
+
67
+ ## Installation
68
+
69
+ Requires macOS (Apple Silicon or Intel), Node.js 22 or later, and at least one of the clients above, installed and signed in.
70
+
71
+ ```sh
72
+ npx agent-things
73
+ ```
74
+
75
+ The wizard asks for your language and the clients to enable. It installs the plugin runtime, a background service, the MCP configuration and the `/things` skills into your user folder; you don't need to close any open client. When it finishes, reconnect the MCP server in your client.
76
+
77
+ To skip the questions and set up every installed client:
78
+
79
+ ```sh
80
+ npx agent-things setup --yes
81
+ ```
82
+
83
+ To force the latest version, run `npx agent-things@latest`.
84
+
85
+ ## Data and privacy
86
+
87
+ - Progress, tasks and notes are stored only on your Mac:
88
+ - ChatGPT: `~/Library/Application Support/CodexSessionStatus/manual-state.json`
89
+ - Antigravity: `~/.gemini/antigravity/session-status/manual-state.json`
90
+ - Claude: `~/Library/Application Support/AgentThings/claude/manual-state.json`
91
+ - The plugin has no telemetry and uploads nothing.
92
+ - **Update progress** calls a model through the Codex CLI built into ChatGPT, the Antigravity command line, or Claude Code (Haiku), whichever you are signed in to locally, and sends the user and assistant text of the session to that model. Raw tool output, reasoning and images are not sent.
93
+ - The plugin draws its interface through each client's local debugging interface and only accepts loopback addresses. See [SECURITY.md](SECURITY.md) for details.
94
+
95
+ ## Updating and uninstalling
96
+
97
+ - The plugin checks the official npm registry for a new version once a day; both the panel (below the notes) and the management menu show when an update is available.
98
+ - Updates run as a separate background job, so you can close the terminal and the panel. They wait for any running analysis to finish and keep your ledger and client selection.
99
+ - To uninstall, run `npx agent-things` again and choose Uninstall from the menu. This stops the background service and removes the MCP entries and program files, keeping your ledger and backups.
100
+
101
+ ## Commands
102
+
103
+ Every command runs as `npx agent-things <command>`. Day-to-day you only need the first two; the rest are for troubleshooting or manual management.
104
+
105
+ | Command | What it does |
106
+ | --- | --- |
107
+ | `npx agent-things` | Opens the interactive wizard: installs on first run, then opens the management menu (Health check, Update enabled apps, Switch language, Check for updates / upgrade, Sync components and skills, Uninstall) |
108
+ | `npx agent-things setup` | Same as above. Add `--yes` (or `--all`) to skip the questions and set up every installed client; add `--lang en` or `--lang zh` to choose the interface and analysis language (without it, the existing setting is kept, or the system language is used on first install) |
109
+ | `npx agent-things doctor` | Shows diagnostics for clients, the background service and interface mounting |
110
+ | `npx agent-things --help` | Shows command help |
111
+
112
+ These commands apply to ChatGPT only:
113
+
114
+ | Command | What it does |
115
+ | --- | --- |
116
+ | `npx agent-things status` | Prints, as JSON, the ledger location, the number of recorded sessions, and the state of the background service and interface mounting |
117
+ | `npx agent-things run` | Runs the progress service and mounts the interface in the foreground, for debugging; press Ctrl+C to exit. Add `--watch-startup` to also handle ChatGPT's startup handoff |
118
+ | `npx agent-things mcp` | Runs the MCP server over stdio; normally started by the client |
119
+ | `npx agent-things install-mcp` | Adds the MCP server to `~/.codex/config.toml` |
120
+ | `npx agent-things disable-mcp` | Removes the MCP server from `~/.codex/config.toml` |
121
+ | `npx agent-things install-autostart` | Installs the background service, which starts at login and mounts the interface |
122
+ | `npx agent-things disable-autostart` | Turns off the background service, keeping existing records |
123
+ | `npx agent-things update-renderer` | Replaces the installed interface resources with the ones from this version |
124
+
125
+ `run`, `status` and `mcp` accept `--port <port>` (default 39222); `run`, `status`, `mcp`, `install-autostart` and `update-renderer` accept `--data-dir <folder>` to use a different data folder.
126
+
127
+ ## FAQ
128
+
129
+ **How do I switch between English and Chinese?**
130
+
131
+ Run `npx agent-things` and choose **Switch language** in the management menu. This reinstalls the skills for all three clients and the interface switches with it; reconnect the MCP server in your client so the assistant also sees the tool descriptions in the new language. Existing tasks are rewritten in the new language at the next **Update progress**; notes are left as they are.
132
+
133
+ **Why does ChatGPT close and reopen once?**
134
+
135
+ The release build of the ChatGPT desktop app doesn't let outside programs attach to its interface while it is running; the local debugging port can only be added at launch. Once the window is ready, the plugin asks ChatGPT to quit normally (the same as ⌘Q, so your work is saved) and reopens it with the debugging port. This usually takes 15 seconds or more, mostly spent in the client's own shutdown. Antigravity and Claude can be attached while running; without **Enable Main Process Debugger**, Claude only gets the in-conversation card.
136
+
137
+ **I don't see the progress rings in the session list. What should I do?**
138
+
139
+ Run `npx agent-things doctor` to see diagnostics for the clients, the background service and interface mounting. Right after ChatGPT opens, wait for it to reopen once; Claude's session-list rings need **Enable Main Process Debugger** turned on first.
140
+
141
+ **Does it modify the clients?**
142
+
143
+ No. The plugin doesn't change any client's app bundle, signature or security settings, and client updates are unaffected.
144
+
145
+ **Can I add to-do items by hand?**
146
+
147
+ Agent Things relies on the LLM to keep the task list up to date, which saves you from tedious bookkeeping. If there is something you want to write down, use the notes. Adding tasks through the conversation may come in a future release.
148
+
149
+ **Does progress update automatically?**
150
+
151
+ Not on a timer. Progress updates in three ways: clicking **Update progress** in the panel; typing `/things` in the session so the assistant reads or updates it; and the assistant recording progress through the MCP tools while it works. This way it never uses your model quota without you noticing.
152
+
153
+ **Does Update progress use my model quota?**
154
+
155
+ Yes. Analysis uses the account you are signed in to in that client, with the most cost-effective model available there by default. Later updates only process messages added since the last one, so they cost much less than the first analysis.
156
+
157
+ **What if the model's task list is wrong?**
158
+
159
+ Add a few messages explaining what actually happened, then click **Update progress** again; or use **Adjust** to change the state, progress and notes directly. If the whole list is far off, **Clear** it and analyze again.
160
+
161
+ **Can I undo Clear?**
162
+
163
+ No. Clearing immediately deletes the session's progress, all tasks, notes and history, with no backup.
164
+
165
+ **Why do some sessions have no progress ring?**
166
+
167
+ Sessions with no record don't show a ring until you hover over or select them; click it to start recording. Sessions being analyzed show a loading state.
168
+
169
+ **What does the purple ring mean?**
170
+
171
+ All tasks are complete and the conversation shows the changes were pushed to the remote repository. It only appears when the project has a Git remote configured. The plugin checks for a Git remote locally and never goes online to do so.
172
+
173
+ **Does analysis read my code?**
174
+
175
+ No. Analysis only uses the user and assistant text in the session; raw tool output, reasoning and images are never sent to the model. The plugin doesn't read your project files either.
176
+
177
+ **Can I turn off the automatic reopen when ChatGPT starts?**
178
+
179
+ There is no menu option yet. Set `allowClientRestart` to `false` in `~/Library/Application Support/CodexSessionStatus/autostart.json`, then run `npx agent-things` and reinstall to restart the background service. After that, ChatGPT only shows progress rings when it was launched with the debugging port; `/things` and the MCP tools are unaffected.
180
+
181
+ **The progress rings disappeared after a client update. What now?**
182
+
183
+ Run `npx agent-things doctor` first. If the client's interface changed significantly, you'll need to wait for a plugin release that supports the new version; meanwhile `/things` and the MCP tools usually keep working and your ledger is unaffected.
184
+
185
+ **Why doesn't `/things` respond?**
186
+
187
+ After installing or updating, reconnect the MCP server in your client; Claude also needs `/reload-plugins` once. If it still doesn't work, run `npx agent-things doctor` to check the background service.
188
+
189
+ **Can progress sync between Macs?**
190
+
191
+ Not yet. All data is stored in your user folder on this Mac; there is no cloud service.
192
+
193
+ **Does it support Windows or Linux?**
194
+
195
+ Not yet. The plugin relies on native macOS interfaces to manage client startup and interface mounting, so it currently supports macOS only (Apple Silicon and Intel).
196
+
197
+ **Is my data kept after uninstalling?**
198
+
199
+ Uninstalling keeps your ledger and backups, and progress comes back when you reinstall. To delete everything, remove the three data folders listed under "Data and privacy" after uninstalling.
200
+
201
+ ## Known limitations
202
+
203
+ - The plugin depends on each client's internal interface structure. After a major client update, the plugin may need an update too before the interface shows again.
204
+ - The model's task list can miss items or merge them poorly; use **Adjust** to correct it.
205
+
206
+ ## Development
207
+
208
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Common commands:
209
+
210
+ ```sh
211
+ npm ci --ignore-scripts
212
+ npm run verify
213
+ ```
214
+
215
+ ## License
216
+
217
+ [MIT](LICENSE) © 2026 snuffpic
218
+
219
+ ## Roadmap
220
+
221
+ - DeepSeek harness support
222
+ - OKtaMind support
@@ -0,0 +1,222 @@
1
+ # Agent Things
2
+
3
+ [English](README.md) | 简体中文
4
+
5
+ 当你在同时处理多个会话时或太久没使用某个会话,Agent Things 可以帮助你快速了解会话的进度和待办事项,从而判断是否需要归档和追踪,你还可以点击查看来源快速跳转、回顾历史信息。
6
+
7
+ Agent Things 是 macOS 上的 AI 编程会话进度插件,支持 **ChatGPT**、**Antigravity** 和 **Claude Desktop** 本地会话。灵感来自 [Things 3](https://culturedcode.com/things/):用一个进度圆环概括一件事做到了哪里,打开后就是一份清楚的待办清单。
8
+
9
+ > 当前为 Beta 版本,已知限制见文末。本项目与 Cultured Code、OpenAI、Google、Anthropic 均无关联。
10
+
11
+ <table>
12
+ <tr>
13
+ <td width="50%"><img src="assets/readme/sidebar-panel.png" alt="会话列表中的进度圆环与状态面板"></td>
14
+ <td width="50%"><img src="assets/readme/manual-adjust.png" alt="手动记录会话状态、进度与备注"></td>
15
+ </tr>
16
+ <tr>
17
+ <td align="center">会话列表的进度圆环与状态面板</td>
18
+ <td align="center">手动调整状态、进度与备注</td>
19
+ </tr>
20
+ <tr>
21
+ <td width="50%"><img src="assets/readme/claude-inline-card.png" alt="在 Claude 会话中用 /things 查看进度卡片"></td>
22
+ <td width="50%"><img src="assets/readme/antigravity-panel.png" alt="Antigravity 侧边的 Things 面板"></td>
23
+ </tr>
24
+ <tr>
25
+ <td align="center">在会话中输入 <code>/things</code> 查看进度(Claude)</td>
26
+ <td align="center">Antigravity 侧边的 Things 面板</td>
27
+ </tr>
28
+ </table>
29
+
30
+ ## 功能
31
+
32
+ **快速查看进度**
33
+
34
+ - 会话列表每一项左侧显示进度圆环,数字是完成百分比;颜色表示会话状态:灰色为尚未开始,金色为有遗留事项,蓝色为全部完成,紫色为全部完成并已推送到远端(如 origin/main)。
35
+ - 点击圆环打开状态面板,查看会话状态、完成比例、一句话概括、剩余任务和已完成任务。
36
+
37
+ **自动整理任务**
38
+
39
+ - 点击「更新进度」,插件读取会话中的对话,调用你已登录的模型整理出任务清单,区分已完成和剩余的事项,并标出受阻的任务。
40
+ (默认选用性价比最高的模型:ChatGPT:Luna,claude code:Haiku,Antigravity:Gemini 3.8)
41
+ - 再次更新时只增量处理新的对话,已有任务和完成记录保持不变。
42
+ - 每项任务都能跳回会话中对应的原文,方便核对。
43
+
44
+ **手动记录**
45
+
46
+ - 「手动调整」可以直接设置状态(尚未开始 / 有遗留事项 / 全部完成)、拖动进度,并填写备注。
47
+ - 「清除进度」会清空该会话的进度、任务、备注与进展记录。
48
+
49
+ **在会话里直接问**
50
+
51
+ - 在任意会话中输入 `/things`,模型会读取这份清单,在消息流中显示进度卡片,并读取或更新进度(搭配Skill使用)。
52
+ - 插件同时注册 MCP 工具(读取 / 更新进度、更新任务、列出所有会话、清除进度),助手在工作过程中也可以自己记录进度。
53
+
54
+ **中英双语**
55
+
56
+ - 界面、`/things` 卡片、技能说明和模型整理出的任务都使用同一种语言:简体中文或 English。
57
+ - 首次安装时按系统语言推荐,之后可在管理菜单中切换;切换后再次「更新进度」,已有任务会改写为新的语言。
58
+
59
+ ## 支持的客户端
60
+
61
+ | 客户端 | 显示位置 | 首次使用需要做的事 |
62
+ | -------------------------- | -------------------------------- | ----------------------------------------------------------------------- |
63
+ | ChatGPT | 会话列表进度圆环、状态面板、`/things` | 无。从 Dock 正常打开即可,见下方“为什么 ChatGPT 会重新打开一次” |
64
+ | Antigravity | 会话列表进度圆环、侧边 Things 面板、`/things` | 无 |
65
+ | Claude Desktop(本地 Code 会话) | 消息流中的 `/things` 卡片;会话列表进度圆环需手动开启 | 安装后执行 `/reload-plugins`;如需会话列表圆环,开启「开发者 → Enable Main Process Debugger」 |
66
+
67
+ ## 安装
68
+
69
+ 需要 macOS(Apple Silicon 或 Intel)、Node.js 22 及以上,以及已安装并登录的上述客户端之一。
70
+
71
+ ```sh
72
+ npx agent-things
73
+ ```
74
+
75
+ 按向导选择语言和要启用的客户端。安装会在用户目录中写入插件运行时、后台服务、MCP 配置和 `/things` 技能,过程中不需要关闭已打开的客户端。安装完成后,在客户端中重新连接 MCP 服务。
76
+
77
+ 如需跳过选择、自动配置已安装的全部客户端:
78
+
79
+ ```sh
80
+ npx agent-things setup --yes
81
+ ```
82
+
83
+ 需要强制使用最新版本时,可运行 `npx agent-things@latest`。
84
+
85
+ ## 数据与隐私
86
+
87
+ - 进度、任务和备注只保存在本机:
88
+ - ChatGPT:`~/Library/Application Support/CodexSessionStatus/manual-state.json`
89
+ - Antigravity:`~/.gemini/antigravity/session-status/manual-state.json`
90
+ - Claude:`~/Library/Application Support/AgentThings/claude/manual-state.json`
91
+ - 插件没有任何遥测或上传服务。
92
+ - 「更新进度」会通过本机已登录的 ChatGPT 内置 Codex CLI、Antigravity 命令行或 Claude Code(Haiku)调用模型,并把会话中的用户与助手文本发送给该模型;工具原始输出、思考过程和图片不会发送。
93
+ - 插件通过客户端的本机调试接口显示界面,只接受本机回环地址。详细说明见 [SECURITY.md](SECURITY.md)。
94
+
95
+ ## 升级与卸载
96
+
97
+ - 插件每天从 npm 官方仓库检查一次新版本,面板备注下方和管理菜单都会提示升级。
98
+ - 升级在独立的后台任务中执行,可以关闭终端和面板;会等待正在进行的分析结束,并保留账本和客户端选择。
99
+ - 再次运行 `npx agent-things`,在菜单中选择卸载:停止后台服务,移除 MCP 入口和程序文件,保留账本与备份。
100
+
101
+ ## 命令
102
+
103
+ 所有命令都通过 `npx agent-things <命令>` 运行。日常使用只需要前两条,其余用于排查或手动管理。
104
+
105
+ | 命令 | 说明 |
106
+ | --- | --- |
107
+ | `npx agent-things` | 打开交互式向导:首次运行时安装,之后进入管理菜单(查看运行状态、修改启用的客户端、切换界面与分析语言、检查更新 / 升级、同步组件与技能、卸载) |
108
+ | `npx agent-things setup` | 同上;加 `--yes`(或 `--all`)跳过选择并配置已安装的全部客户端,加 `--lang zh` 或 `--lang en` 指定界面与分析语言(不指定时沿用已有设置,首次安装按系统语言) |
109
+ | `npx agent-things doctor` | 查看客户端、后台服务和界面挂载的诊断信息 |
110
+ | `npx agent-things --help` | 显示命令帮助 |
111
+
112
+ 以下命令只作用于 ChatGPT:
113
+
114
+ | 命令 | 说明 |
115
+ | --- | --- |
116
+ | `npx agent-things status` | 以 JSON 输出账本位置、已记录的会话数、后台服务与界面挂载状态 |
117
+ | `npx agent-things run` | 在前台运行进度服务并挂载界面,用于调试;按 Ctrl+C 退出。加 `--watch-startup` 同时接管 ChatGPT 的启动交接 |
118
+ | `npx agent-things mcp` | 以 stdio 方式运行 MCP 服务,一般由客户端自动调用 |
119
+ | `npx agent-things install-mcp` | 把 MCP 服务写入 `~/.codex/config.toml` |
120
+ | `npx agent-things disable-mcp` | 从 `~/.codex/config.toml` 中移除 MCP 服务 |
121
+ | `npx agent-things install-autostart` | 安装后台服务,登录后自动运行并挂载界面 |
122
+ | `npx agent-things disable-autostart` | 关闭后台服务,保留已有记录 |
123
+ | `npx agent-things update-renderer` | 用当前版本的界面资源替换已安装的资源 |
124
+
125
+ `run`、`status`、`mcp` 支持 `--port <端口>`(默认 39222);`run`、`status`、`mcp`、`install-autostart`、`update-renderer` 支持 `--data-dir <目录>` 指定数据目录。
126
+
127
+ ## 常见问题
128
+
129
+ **怎么切换中文和英文?**
130
+
131
+ 运行 `npx agent-things`,在管理菜单中选择「切换界面与分析语言」。切换会重新安装三端的技能,界面随之切换;之后在客户端中重新连接 MCP 服务,助手看到的工具说明也会换成新语言。已有任务在下一次「更新进度」时改写为新语言,备注保持原样。
132
+
133
+ **为什么 ChatGPT 打开后窗口会关掉再重新打开一次?**
134
+
135
+ ChatGPT 桌面应用的正式版不允许外部程序在运行中接入界面,只能在启动时附加本机调试端口。插件会在窗口就绪后请求它正常退出(与 ⌘Q 相同,会完成保存),再带上调试端口重新打开。整个过程通常需要 15 秒或更久,主要取决于客户端自身的退出收尾。Antigravity 和 Claude 支持运行中接入,Claude 如未打开「Enable Main Process Debugger」,将仅可使用会话内卡片。
136
+
137
+ **会话列表里看不到进度圆环怎么办?**
138
+
139
+ 运行 `npx agent-things doctor`,查看客户端、后台服务和界面挂载的诊断信息。ChatGPT 刚打开时需要等它重新打开一次;Claude 的会话列表圆环需要先开启「Enable Main Process Debugger」。
140
+
141
+ **会修改客户端吗?**
142
+
143
+ 不会。插件不修改任何客户端的应用包、签名或安全设置,客户端更新也不会受影响。
144
+
145
+ **是否支持手动添加待办事项?**
146
+
147
+ Agent Things 依赖 LLM 更新具体待办事项,免去了繁琐的记录过程。如有需要记录的内容,可使用备注记录,但不排除在未来添加通过对话添加待办事项的功能。
148
+
149
+ **进度会自动更新吗?**
150
+
151
+ 不会定时自动更新。进度在以下三种情况下更新:点击面板中的「更新进度」;在会话中输入 `/things` 让助手读取或更新;助手在工作过程中通过 MCP 工具自行记录。这样不会在你没注意的时候消耗模型额度。
152
+
153
+ **「更新进度」会消耗我的模型额度吗?**
154
+
155
+ 会。分析使用你在对应客户端中已登录的账号,默认选用该客户端里性价比最高的模型。再次更新时只处理上次之后新增的对话,消耗会明显少于首次分析。
156
+
157
+ **模型整理的任务不准确怎么办?**
158
+
159
+ 可以先补充几句对话说明实际情况,再点「更新进度」重新整理;也可以用「手动调整」直接修改状态、进度和备注。如果整份清单偏差很大,可以「清除进度」后重新分析。
160
+
161
+ **「清除进度」可以撤销吗?**
162
+
163
+ 不可以。清除会立即删除该会话的进度、全部任务、备注和进展记录,且不保留备份。
164
+
165
+ **为什么有的会话没有显示进度圆环?**
166
+
167
+ 没有任何记录的会话默认不显示圆环,鼠标移到该会话上或选中它时才会出现,点击即可开始记录。分析进行中的会话会显示加载状态。
168
+
169
+ **紫色圆环代表什么?**
170
+
171
+ 表示任务全部完成,且对话显示改动已推送到远端仓库。只有项目配置了 Git 远端时才会出现这个状态。插件只在本机读取项目是否配置了 Git 远端,不访问网络。
172
+
173
+ **分析时会读取我的代码吗?**
174
+
175
+ 不会。分析只使用会话中的用户与助手文本;工具原始输出、思考过程和图片都不会发送给模型。插件也不会读取项目文件内容。
176
+
177
+ **可以关闭 ChatGPT 启动时的自动重开吗?**
178
+
179
+ 目前没有菜单开关。可以把 `~/Library/Application Support/CodexSessionStatus/autostart.json` 中的 `allowClientRestart` 改为 `false`,再运行 `npx agent-things` 重新安装以重启后台服务。关闭后,ChatGPT 只有在带调试端口启动时才会显示进度圆环,`/things` 和 MCP 工具不受影响。
180
+
181
+ **客户端更新后进度圆环不见了怎么办?**
182
+
183
+ 先运行 `npx agent-things doctor` 查看诊断。如果客户端界面结构有较大变化,需要等待插件发布适配新版本;在此期间,`/things` 和 MCP 工具通常仍可使用,账本数据不受影响。
184
+
185
+ **为什么 `/things` 没有反应?**
186
+
187
+ 安装或升级后,需要在客户端中重新连接 MCP 服务;Claude 需要执行一次 `/reload-plugins`。仍无效时,运行 `npx agent-things doctor` 检查后台服务状态。
188
+
189
+ **可以在多台电脑之间同步进度吗?**
190
+
191
+ 暂不支持。所有数据都保存在本机用户目录,没有云端服务。
192
+
193
+ **支持 Windows 或 Linux 吗?**
194
+
195
+ 暂不支持。插件依赖 macOS 原生接口来管理客户端的启动与界面挂载,目前仅支持 macOS(Apple Silicon 与 Intel)。
196
+
197
+ **卸载后数据还在吗?**
198
+
199
+ 卸载会保留账本与备份,重新安装后进度会自动恢复。如需彻底删除,可在卸载后手动删除“数据与隐私”中列出的三个数据目录。
200
+
201
+ ## 已知限制
202
+
203
+ - 插件依赖客户端的内部界面结构。客户端大版本更新后,界面显示可能需要插件随之更新。
204
+ - 模型整理的任务清单可能有遗漏或合并不当,可以用「手动调整」修正。
205
+
206
+ ## 开发
207
+
208
+ 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。常用命令:
209
+
210
+ ```sh
211
+ npm ci --ignore-scripts
212
+ npm run verify
213
+ ```
214
+
215
+ ## 许可
216
+
217
+ [MIT](LICENSE) © 2026 snuffpic
218
+
219
+ ## 更新计划
220
+
221
+ - DeepSeek harness 支持
222
+ - OKtaMind 支持
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+ const { main } = require('./codex-session-status.cjs');
4
+
5
+ main().catch(error => {
6
+ console.error(error.message);
7
+ process.exitCode = 1;
8
+ });
@@ -0,0 +1,96 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+ const { AntigravityService, DEFAULT_PORT, DEFAULT_STATE_FILE } = require('../src/harnesses/antigravity/antigravity-service.cjs');
4
+ const { AntigravityInjector } = require('../src/harnesses/antigravity/antigravity-injector.cjs');
5
+ const { requestProgressHttp } = require('../src/local-progress-http.cjs');
6
+ const { assertIntegrationEnabled } = require('../src/cli/integration-state.cjs');
7
+ const { serveMcp } = require('../src/mcp-stdio.cjs');
8
+ const { readConfiguredLang } = require('../src/i18n.cjs');
9
+
10
+ async function main() {
11
+ const args = process.argv.slice(2);
12
+ const en = readConfiguredLang() === 'en';
13
+ if (args.some(arg => !['--daemon', '--no-ui', '--help', '-h', 'help'].includes(arg))) throw new Error(en ? 'Unknown Antigravity service option' : '未知 Antigravity 服务选项');
14
+ if (args.some(arg => ['--help', '-h', 'help'].includes(arg))) {
15
+ console.log(en
16
+ ? 'Usage: antigravity-session-status [--daemon] [--no-ui]; Agent Things (Antigravity) daemon and MCP stdio service.'
17
+ : '用法:antigravity-session-status [--daemon] [--no-ui];Agent Things (Antigravity) 后台与 MCP stdio 服务。');
18
+ return;
19
+ }
20
+ const isDaemon = process.argv.includes('--daemon');
21
+ const port = Number(process.env.SESSION_STATUS_PORT ?? DEFAULT_PORT);
22
+ const stateFile = process.env.SESSION_STATUS_STATE_FILE || DEFAULT_STATE_FILE;
23
+ let service = null, injector = null, stopping = false, refreshing = false, remote = false;
24
+ const request = (route, body) => requestProgressHttp(stateFile, route, body, port);
25
+ const ensureService = async () => {
26
+ assertIntegrationEnabled('antigravity');
27
+ if (service || stopping) return;
28
+ if (remote) {
29
+ try { await request('/health'); return; }
30
+ catch { remote = false; }
31
+ }
32
+ const candidate = new AntigravityService({ port, stateFile });
33
+ try { await candidate.start(); }
34
+ catch (error) {
35
+ if (error.code !== 'EADDRINUSE') throw error;
36
+ // Binding is the ownership decision. Another starting owner may still be
37
+ // publishing its credential file, so verify its identity before reuse.
38
+ for (let attempt = 0; attempt < 20; attempt++) {
39
+ try { await request('/health'); remote = true; return; }
40
+ catch (failure) {
41
+ if (attempt === 19) throw failure;
42
+ await new Promise(resolve => setTimeout(resolve, 25));
43
+ }
44
+ }
45
+ }
46
+ service = candidate;
47
+ injector = process.argv.includes('--no-ui') ? null : new AntigravityInjector(service.http.credentials, { allowOrigin: origin => service.http.allowOrigin(origin) });
48
+ };
49
+ await ensureService();
50
+ const refresh = async () => {
51
+ if (refreshing || stopping) return;
52
+ refreshing = true;
53
+ try { await ensureService(); await injector?.scan(); }
54
+ catch (error) {
55
+ if (error.code === 'INTEGRATION_DISABLED') await shutdown();
56
+ else process.stderr.write(`[agent-things antigravity] ${error.message}\n`);
57
+ }
58
+ finally { refreshing = false; }
59
+ };
60
+ const timer = setInterval(refresh, 2500);
61
+ void refresh();
62
+ const shutdown = async () => {
63
+ if (stopping) return;
64
+ stopping = true; clearInterval(timer); await injector?.stop();
65
+ if (service) await service.stop();
66
+ };
67
+ const antigravityTools = toolLang => {
68
+ const isEn = toolLang === 'en';
69
+ return [
70
+ {
71
+ name: 'render_things_card',
72
+ description: isEn
73
+ ? 'Generate and return the inline Agent Things session progress card artifact and embed tag for the current Antigravity conversation in one step.'
74
+ : '在当前 Antigravity 会话生成并返回 Agent Things 任务进度信息流卡片工件与内嵌标签。一步完成读取、卡片工件生成与回复文本。',
75
+ inputSchema: {
76
+ type: 'object',
77
+ properties: {
78
+ conversation_id: { type: 'string', minLength: 1, description: isEn ? 'Conversation ID of the current session' : '当前会话的 Conversation ID' },
79
+ artifact_dir: { type: 'string', description: isEn ? 'Artifact directory path (optional)' : '工件目录路径(可选)' },
80
+ },
81
+ required: ['conversation_id'],
82
+ additionalProperties: false,
83
+ },
84
+ },
85
+ ];
86
+ };
87
+
88
+ if (!isDaemon) serveMcp({ name: 'antigravity-session-status', extraTools: antigravityTools, callTool: async (name, args) => {
89
+ await ensureService();
90
+ return (await request('/tools', { name, args })).result;
91
+ }, onClose: shutdown });
92
+ for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => shutdown().catch(error => { process.stderr.write(error.message + '\n'); process.exitCode = 1; }));
93
+ }
94
+
95
+ if (require.main === module) main().catch(error => { process.stderr.write(error.message + '\n'); process.exitCode = 1; });
96
+ module.exports = { main };
@@ -0,0 +1,55 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+ const { ClaudeService, DEFAULT_PORT, DEFAULT_STATE_FILE } = require('../src/harnesses/claude/claude-service.cjs');
4
+ const { ClaudeInjector } = require('../src/harnesses/claude/claude-injector.cjs');
5
+ const { requestProgressHttp } = require('../src/local-progress-http.cjs');
6
+ const { serveMcp } = require('../src/mcp-stdio.cjs');
7
+ const { assertIntegrationEnabled } = require('../src/cli/integration-state.cjs');
8
+ const { readConfig } = require('../src/cli/setup-orchestrator.cjs');
9
+ const { readConfiguredLang } = require('../src/i18n.cjs');
10
+
11
+ async function main(args = process.argv.slice(2)) {
12
+ const en = readConfiguredLang() === 'en';
13
+ if (args.some(arg => !['--daemon', '--no-ui', '--help', '-h'].includes(arg))) throw new Error(en ? 'Unknown Claude service option' : '未知 Claude 服务选项');
14
+ if (args.includes('--help') || args.includes('-h')) {
15
+ console.log(en
16
+ ? 'Usage: claude-session-status [--daemon] [--no-ui]; Agent Things (Claude) daemon and MCP stdio service.'
17
+ : '用法:claude-session-status [--daemon] [--no-ui];Agent Things (Claude) 后台与 MCP stdio 服务。');
18
+ return;
19
+ }
20
+ assertIntegrationEnabled('claude');
21
+ const stateFile = process.env.SESSION_STATUS_STATE_FILE || DEFAULT_STATE_FILE;
22
+ const port = Number(process.env.SESSION_STATUS_PORT ?? DEFAULT_PORT);
23
+ let service = null, injector = null, stopping = false, refreshing = false;
24
+ const request = (route, body) => requestProgressHttp(stateFile, route, body, port || undefined);
25
+ try { await request('/health'); }
26
+ catch {
27
+ service = new ClaudeService({ stateFile, port });
28
+ try { await service.start(); }
29
+ catch (error) { if (error.code !== 'EADDRINUSE') throw error; await request('/health'); service = null; }
30
+ if (service && !args.includes('--no-ui')) injector = new ClaudeInjector({ stateFile });
31
+ }
32
+ const refresh = async () => {
33
+ if (stopping || refreshing) return;
34
+ refreshing = true;
35
+ try { assertIntegrationEnabled('claude'); await injector?.scan(); }
36
+ catch (error) { if (error.code === 'INTEGRATION_DISABLED') await stop(); else process.stderr.write(`[agent-things claude] ${error.message}\n`); }
37
+ finally { refreshing = false; }
38
+ };
39
+ const timer = setInterval(refresh, 1000);
40
+ const stop = async () => {
41
+ if (stopping) return;
42
+ stopping = true; clearInterval(timer);
43
+ // A replacement daemon adopts the live host. Disabling the integration
44
+ // removes its UI before the service disappears.
45
+ if (service && injector?.attachedPid && !readConfig()?.enabledApps.includes('claude')) await Promise.race([service.requestHost('detach', '').catch(() => {}), new Promise(resolve => setTimeout(resolve, 2000))]);
46
+ await service?.stop();
47
+ };
48
+ void refresh();
49
+ if (!args.includes('--daemon')) serveMcp({ name: 'claude-session-status', callTool: async (name, toolArgs) => {
50
+ assertIntegrationEnabled('claude'); return (await request('/tools', { name, args: toolArgs })).result;
51
+ }, onClose: stop });
52
+ for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => { void stop().catch(error => { process.stderr.write(error.message + '\n'); process.exitCode = 1; }); });
53
+ }
54
+ if (require.main === module) main().catch(error => { process.stderr.write(error.message + '\n'); process.exitCode = 1; });
55
+ module.exports = { main };