agentcue 0.0.0-stage → 0.0.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.
- package/LICENSE +21 -0
- package/README.md +122 -2
- package/dist/cli.js +770 -0
- package/dist/client.js +489 -0
- package/dist/demo.html +110 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +661 -0
- package/dist/server/dispatcher.d.ts +40 -0
- package/dist/server/handler.d.ts +20 -0
- package/dist/server/server.d.ts +20 -0
- package/dist/shared/prompt.d.ts +2 -0
- package/dist/shared/types.d.ts +69 -0
- package/dist/vite.d.ts +60 -0
- package/dist/vite.js +636 -0
- package/logo.svg +18 -0
- package/package.json +48 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 yuler
|
|
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/README.md
CHANGED
|
@@ -1,3 +1,123 @@
|
|
|
1
|
-
#
|
|
1
|
+
# <img src="./logo.svg" alt="" width="28" height="28" align="absmiddle" /> agentcue
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Cue the Agent.** Pick one or more DOM elements in the browser, jot down quick UI edits, and push the batch straight to your local Agent CLI (`agy`, `claude`, `cursor-agent`, `codex`, `pi`) so it edits your code immediately.
|
|
4
|
+
|
|
5
|
+
**[Live Website & Interactive Sandbox (agentcue.yuler.dev)](https://agentcue.yuler.dev)** · **[中文文档](https://agentcue.yuler.dev/zh/)** · **[GitHub Repository](https://github.com/yuler/agentcue)**
|
|
6
|
+
|
|
7
|
+
## Why
|
|
8
|
+
|
|
9
|
+
Terminal coding agents cannot see your rendered page. Explaining visual tweaks in prose ("move the second button on the left 8px right and match the header font size") is slow and imprecise.
|
|
10
|
+
|
|
11
|
+
Most visual feedback tools either lock into React or drop annotations into a passive MCP server where you still have to switch back to the terminal and ask the agent to pull tasks.
|
|
12
|
+
|
|
13
|
+
**agentcue** turns Pull into **Push** with an Agentation-inspired floating overlay: pick multiple spots (**Pin**s), press `S` (or `Cmd/Ctrl + Enter`), and `agentcue` dispatches a compact structured **Cue** directly into your chosen **Agent Target**.
|
|
14
|
+
|
|
15
|
+
## How It Works
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
Browser (activate + pick Pins) ──► local agentcue bridge ──► Agent CLI (agy / claude / cursor-agent / codex / pi) ──► HMR reload
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
1. **Activate & pick in browser** — Press `Cmd/Ctrl + Shift + F` (or click the collapsed `✦` launcher) to enter **Pick Mode**, then click one or more elements on your local dev page to drop numbered **Pin**s with brief change notes.
|
|
22
|
+
2. **Capture sharp DOM & source context** — Each **Pin** extracts a stable CSS selector, DOM breadcrumb, trimmed `outerHTML`, visible text, key computed styles, bounding box, and opportunistic framework source/component hints (React Fiber, Vue, Svelte, Astro, `data-*` attributes).
|
|
23
|
+
3. **Push Cue straight to Agent CLI** — Press `S` (or `Cmd/Ctrl + Enter`) to send the batch to the local `agentcue` bridge, which queues and runs your selected **Agent Target** in workspace auto-edit mode while streaming live status over SSE back to the browser.
|
|
24
|
+
|
|
25
|
+
## Usage
|
|
26
|
+
|
|
27
|
+
### Vite Plugin (`agentcue/vite`)
|
|
28
|
+
|
|
29
|
+
Install `agentcue` and register the plugin to mount `/__agentcue/*` onto Vite's dev server — automatic `<script>` injection in `vite` dev mode and zero impact on `vite build`:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npm add -D agentcue
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
// vite.config.ts
|
|
37
|
+
import { defineConfig } from "vite";
|
|
38
|
+
import agentcue from "agentcue/vite";
|
|
39
|
+
|
|
40
|
+
export default defineConfig({
|
|
41
|
+
plugins: [agentcue()],
|
|
42
|
+
});
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Standalone CLI (Any Framework or Plain HTML)
|
|
46
|
+
|
|
47
|
+
Start the local bridge in any frontend project (Next.js, React, Vue, Svelte, Astro, Rails, or plain HTML) with zero build setup. It automatically detects all installed Agent CLIs (`agy`, `claude`, `cursor-agent`, `codex`, `pi`) so you can switch targets freely in the browser:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
# Start local bridge in current workspace (default port: 4318)
|
|
51
|
+
npx agentcue
|
|
52
|
+
|
|
53
|
+
# Or customize port and target workspace directory
|
|
54
|
+
npx agentcue --port 4318 --cwd /path/to/your-frontend
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Then attach the overlay in the browser using any output printed in your terminal:
|
|
58
|
+
|
|
59
|
+
- **Script tag**: add `<script src="http://localhost:4318/client.js"></script>` to your dev HTML
|
|
60
|
+
- **Bookmarklet**: run the zero-config Bookmarklet URL on any local page
|
|
61
|
+
- **Built-in playground**: open `http://localhost:4318/demo` to test live edits immediately
|
|
62
|
+
|
|
63
|
+
## Browser Shortcuts
|
|
64
|
+
|
|
65
|
+
| Shortcut | Action |
|
|
66
|
+
| -------------------------- | ----------------------------------------------------------------- |
|
|
67
|
+
| `Cmd / Ctrl + Shift + F` | Activate / collapse toolbar and toggle **Pick Mode** |
|
|
68
|
+
| `Enter` (in popover) | Save current **Pin** and stay in **Pick Mode** to pick the next |
|
|
69
|
+
| `Shift + Enter` | Insert newline inside a **Pin** note |
|
|
70
|
+
| `S` / `Cmd / Ctrl + Enter` | Save active note and push all pending **Pin**s as a **Cue** |
|
|
71
|
+
| `P` (when active) | Pause / resume **Pick Mode** |
|
|
72
|
+
| `A` / `1-5` (when active) | Switch **Agent Target** |
|
|
73
|
+
| `R` (when active) | Reset current **Agent Target** session (start fresh on next Cue) |
|
|
74
|
+
| `C` (when active) | Copy pending **Cue** as structured Markdown |
|
|
75
|
+
| `X` (when active) | Clear all pending **Pin**s |
|
|
76
|
+
| `H` (when active) | Hide / show **Pin**s on the page |
|
|
77
|
+
| `Esc` | Close active popover (discarding empty draft) or collapse toolbar |
|
|
78
|
+
|
|
79
|
+
## Supported Agent Targets
|
|
80
|
+
|
|
81
|
+
| Agent Target | CLI | Auto-approve invocation (`Continue` adds `--continue` / `resume --last`) |
|
|
82
|
+
| ------------ | -------------- | ------------------------------------------------------------------------ |
|
|
83
|
+
| Antigravity | `agy` | `agy --dangerously-skip-permissions -p <prompt>` |
|
|
84
|
+
| Claude Code | `claude` | `claude --dangerously-skip-permissions -p <prompt>` |
|
|
85
|
+
| Cursor Agent | `cursor-agent` | `cursor-agent --yolo -p <prompt>` |
|
|
86
|
+
| OpenAI Codex | `codex` | `codex exec --dangerously-bypass-approvals-and-sandbox <prompt>` |
|
|
87
|
+
| Pi | `pi` | `pi --approve -p -- <prompt>` |
|
|
88
|
+
|
|
89
|
+
## Design Principles
|
|
90
|
+
|
|
91
|
+
- **Push, not Pull** — Submitting a **Cue** triggers the selected CLI immediately in a serial FIFO queue with live SSE status in the browser capsule.
|
|
92
|
+
- **Framework-agnostic** — Zero-dependency Shadow DOM Web Component (`client.js`) with opportunistic source/component hints (React Fiber, Vue, Svelte, Astro, Vite inspector `data-*` attributes).
|
|
93
|
+
- **Safe Rollback** — Pending **Pin**s clear on send for clean HMR reloads, and automatically restore onto the page if a CLI run fails.
|
|
94
|
+
|
|
95
|
+
## Development
|
|
96
|
+
|
|
97
|
+
Requires Node.js `>= 22` and [`mise`](https://mise.jdx.dev/) (provisions `bun` via [`mise.toml`](./mise.toml)).
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
# Install workspace dependencies and build all targets
|
|
101
|
+
mise run setup
|
|
102
|
+
|
|
103
|
+
# Start all watchers and dev servers concurrently
|
|
104
|
+
mise run dev
|
|
105
|
+
|
|
106
|
+
# Build all packages/apps/examples and run the test suite
|
|
107
|
+
mise run check
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Workspace Targets
|
|
111
|
+
|
|
112
|
+
| Workspace | Description | Dev / Start Command | Port |
|
|
113
|
+
| --------------------- | ---------------------------------------------------- | --------------------------------- | ------- |
|
|
114
|
+
| `packages/agentcue` | CLI, local HTTP/SSE bridge, Vite plugin, and overlay | `mise run agentcue:start` | `:4318` |
|
|
115
|
+
| `apps/web` | Official showcase and interactive documentation | `mise run web:dev` | `:4319` |
|
|
116
|
+
| `examples/html` | Plain HTML playground with live reload | `mise run example:html:dev` | `:4320` |
|
|
117
|
+
| `examples/vite-react` | Vite + React + TypeScript HMR playground | `mise run example:vite-react:dev` | `:5173` |
|
|
118
|
+
|
|
119
|
+
Other workspace tasks: `mise run build`, `mise run test`, and `mise run clean`.
|
|
120
|
+
|
|
121
|
+
## License
|
|
122
|
+
|
|
123
|
+
MIT
|