Skip to content

Commit 9520f69

Browse files
Add Cursor and OpenCode adapters (#25)
* Add a Cursor agent-hook adapter Cursor's agent hooks are a flat `hooks.json` of per-event command entries with a `matcher` field on the entry itself, and its permission-bearing hooks answer with a top-level `permission` of allow/deny/ask. That is close enough to the Codex adapter's config-file shape to reuse its installer idioms, but the event set and response schema are Cursor's own, so the parsing lives in a new module. The supported slice stays deliberately narrow: `beforeShellExecution` for commands Cursor does not sandbox, `preToolUse` matching `Write` and `Delete` for the mutating file tools, and `stop` for completion. Cursor runs the shell hook for every command rather than only when it would prompt, so this is a strict pre-tool gate with no native policy; sandboxed executions are skipped because Cursor never prompts for those. Cursor documents `preToolUse` `tool_input` as an open object, which for a write can hold the whole proposed file body, so the summary names the action from the tool type and speaks only a path it can resolve — never the argument object. `stop` carries no final assistant text, so completion is announced and no turn is ever continued. Every parse, transport, and broker failure emits no hook output, which is also Cursor's documented default for a failed hook. Wire format from https://cursor.com/docs/agent/hooks; fixtures in the tests are written from that reference rather than recorded from a pinned client release. Co-Authored-By: Claude Fable 5 <[email protected]> * Add `tapq integration cursor` install, status, and uninstall Matches the existing integration UX: TapQ-managed entries only, unrelated hook data preserved, a restrictive backup before an existing file changes, and repair on rerun. Cursor has no hook-trust step and no local command that reports hook activation, so status validates TapQ's file layout and then states the documented client coverage instead of executing a Cursor binary. That coverage matters: the desktop app fires every installed hook, while `cursor-agent` does not fire `preToolUse`, leaving writes and deletes native there. Co-Authored-By: Claude Fable 5 <[email protected]> * Document the Cursor adapter Adds the integration-guide and CLI-reference sections plus a manual test plan modeled on the Codex one. The plan carries extra weight here: this adapter ships no versioned Cursor fixture corpus, so it is the only place the real payload shape is confirmed against a live client, and several cases ask the tester to record observed field names. Co-Authored-By: Claude Fable 5 <[email protected]> * Add the OpenCode adapter module and relay executable OpenCode has no hook-registration file comparable to Claude Code's settings.json or Codex's hooks.json. Its documented extension surface is a JavaScript plugin loaded from the OpenCode configuration directory at startup, so the unit of installation is one file TapQ owns end to end. TapQOpenCodeAdapter therefore generates and installs that plugin, and tapq-opencode-hook is the executable edge it relays to. The plugin observes OpenCode's permission.asked and session-idle bus events, pipes a small TapQ relay envelope to the hook, and applies the returned decision through OpenCode's own permission API. All policy, broker authentication, and speech rendering stay in Swift, so the JavaScript layer carries no security-relevant logic and a bus-event rename is a one-line plugin edit. The plugin's permission.ask hook is deliberately unused: it is declared in @opencode-ai/plugin's types but no OpenCode code path triggers it (anomalyco/opencode#7006), so a plugin built on it would silently never run. Replies prefer POST /permission/{requestID}/reply and fall back to the deprecated session-scoped route on the injected SDK client. The plugin is embedded as source text rather than an SPM resource because package-runtime-app.sh assembles TapQRuntime.app from executables alone, so a resource bundle would be absent exactly where the installer normally runs. Embedding also makes install, repair detection, and idempotence a plain string comparison. The supported slice stays narrow. Allow becomes a one-time `once` reply and deny becomes `reject`; the remembered `always` reply is never sent, because a hands-free answer is scoped to the prompt it was spoken for. bash, edit, and webfetch get kind-specific speech from documented scalar metadata, with a URL contributing only its host, and every other kind is spoken from its name alone, so a permission's open-ended metadata object never reaches speech. There is no question interception or final-response continuation, because OpenCode exposes no equivalent surface. Every parse, transport, and broker failure applies no reply at all, leaving OpenCode's own prompt pending and answerable on screen. Co-Authored-By: Claude Fable 5 <[email protected]> * Add tapq integration opencode install/status/uninstall The command matches the existing integration UX: TapQ-managed content only, a restrictive timestamped backup before changing an existing file, atomic replacement, and repair-on-rerun for a plugin left stale by a moved checkout or a hand edit. A plugin whose contents already match is a byte-for-byte no-op that creates no backup. Because TapQ owns the whole file here rather than merging entries into a shared one, ownership is explicit: only a file carrying TapQ's marker is rewritten or removed. Install refuses to overwrite anything else at the managed path and reports it instead, and uninstall leaves such a file alone, so neighbouring plugins in the same directory are never touched. The default path resolves the OpenCode configuration directory the way OpenCode does — OPENCODE_CONFIG_DIR, then XDG_CONFIG_HOME/opencode, then ~/.config/opencode — and ignores a non-absolute value in either variable so the plugin cannot land somewhere OpenCode will not scan. Co-Authored-By: Claude Fable 5 <[email protected]> * Package and boundary-check the OpenCode hook executable package-runtime-app.sh now builds, copies, and signs tapq-opencode-hook alongside the other adapters, so the installer running from TapQRuntime.app can point at a hook that exists beside it. check-public-boundary.sh adds the new module to the portable target list. Co-Authored-By: Claude Fable 5 <[email protected]> * Document the OpenCode adapter Adds an OpenCode section to the integration guide and the CLI reference, a manual test plan modeled on the Codex one, and the roadmap, README, and changelog updates. The docs are explicit about what the automated coverage does and does not claim: the process contracts drive the real hook against a real broker, but they do not start OpenCode, load the plugin into its runtime, or prove that OpenCode accepted the reply the plugin issues. The manual plan owns those boundaries, along with the once-per-turn completion announcement, the speech boundary for permission metadata, and answering on screen while TapQ is still speaking. Co-Authored-By: Claude Fable 5 <[email protected]> --------- Co-authored-by: spaceamoeba_t <[email protected]> Co-authored-by: Claude Fable 5 <[email protected]>
1 parent 0529a36 commit 9520f69

37 files changed

Lines changed: 6493 additions & 25 deletions

‎CHANGELOG.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,50 @@ All notable changes to TapQ will be recorded in this file. The project uses
3636
decision logic only: every trace is shaped by construction, so the capture study remains
3737
the accuracy gate for every IMU default.
3838

39+
**Cursor adapter**
40+
41+
- `tapq integration cursor install|status|uninstall` manages TapQ-owned
42+
entries in `~/.cursor/hooks.json`, and the new `tapq-cursor-hook` executable answers
43+
Cursor's `beforeShellExecution` for non-sandboxed commands, `preToolUse` for the `Write`
44+
and `Delete` file tools, and `stop` for completion announcements. Unrelated hook data is
45+
preserved, an existing file is backed up before it changes, and every failure path emits
46+
no hook output so Cursor's own permission and turn flow stays in control. Cursor exposes
47+
no hookable question tool and no final assistant text on `stop`, so clarifying and
48+
final-response questions stay in Cursor's interface. See the
49+
[integration guide](docs/INTEGRATIONS.md) and
50+
[manual test plan](docs/CURSOR_ADAPTER_MANUAL_TEST_PLAN.md).
51+
52+
**OpenCode adapter**
53+
54+
- A new `TapQOpenCodeAdapter` module and `tapq-opencode-hook` executable connect OpenCode
55+
to the existing agent-neutral broker. OpenCode has no hook-registration file, so the
56+
adapter installs one plugin TapQ owns end to end at `<config>/plugins/tapq.js`,
57+
resolving `<config>` the way OpenCode does (`OPENCODE_CONFIG_DIR`, then
58+
`XDG_CONFIG_HOME/opencode`, then `~/.config/opencode`). The plugin relays OpenCode's
59+
own `permission.asked` prompts and its session-idle completion event to the hook
60+
executable and applies the hands-free answer through OpenCode's permission API; all
61+
policy, broker authentication, and speech rendering stay in Swift.
62+
- `tapq integration opencode install|status|uninstall`, with `--plugin PATH` and
63+
`--hook PATH` for isolated setups. Install refuses to overwrite a file at the managed
64+
path that TapQ did not write, uninstall removes only TapQ's own plugin, mutations
65+
snapshot the previous file to a restrictive timestamped backup, and rerunning install
66+
repairs a plugin left stale by a moved checkout or a hand edit while a matching plugin
67+
is a byte-for-byte no-op.
68+
- The supported slice is deliberately narrow: allow becomes a one-time `once` reply and
69+
deny becomes `reject`; the remembered `always` reply is never sent. `bash`, `edit`, and
70+
`webfetch` get kind-specific speech from documented scalar metadata — a web-fetch URL
71+
contributes only its host — and every other permission kind is spoken from its name
72+
alone, so a permission's `metadata` object is never serialized into speech. Broker
73+
absence, timeout, an incompatible wire version, or no hands-free answer applies no
74+
reply at all, leaving OpenCode's on-screen prompt pending and usable. There is no
75+
question interception and no final-response continuation, because OpenCode exposes no
76+
equivalent surface.
77+
- The adapter targets OpenCode `1.18.15` and deliberately does not use the
78+
`permission.ask` plugin hook, which is declared in `@opencode-ai/plugin` but never
79+
triggered by OpenCode ([opencode#7006](https://github.com/anomalyco/opencode/issues/7006)).
80+
Replies prefer `POST /permission/{requestID}/reply` and fall back to the deprecated
81+
session-scoped route on the SDK client OpenCode injects into plugins.
82+
3983
### Changed
4084

4185
- Serving with no AirPods connected degrades to a plain voice agent instead of announcing
Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
import Foundation
2+
import TapQCursorAdapter
3+
import TapQPOSIXBridgeClient
4+
import TapQWireProtocol
5+
#if canImport(Darwin)
6+
import Darwin
7+
#elseif canImport(Glibc)
8+
import Glibc
9+
#endif
10+
11+
// Thin executable edge for Cursor agent hooks: stdin JSON in, one authenticated broker
12+
// round-trip per broker-backed event, documented hook JSON out. Decision and fail-open
13+
// policy live in CursorHookShim so they can be tested independently of this edge.
14+
15+
let stdinData = FileHandle.standardInput.readDataToEndOfFile()
16+
let discovery = BrokerDiscovery()
17+
18+
enum CursorShimVersionError: Error {
19+
case mismatch(app: Int, shim: Int)
20+
case unknownApprovalSource(String)
21+
}
22+
23+
let result = CursorHookShim.handle(stdinData: stdinData) { message, timeout in
24+
let (socketPath, token, appVersion, _) = try discovery.readDiscovery()
25+
26+
let sourceRaw = message["approval_source"]?.stringValue
27+
let approvalSource = sourceRaw.flatMap(ApprovalSource.init(rawValue:))
28+
if let sourceRaw, approvalSource == nil {
29+
throw CursorShimVersionError.unknownApprovalSource(sourceRaw)
30+
}
31+
32+
// Cursor's approval hooks are strict pre-tool gates, the same policy class as Claude's
33+
// PreToolUse, so they may bridge to a discovered legacy v2 runtime.
34+
guard let outboundVersion = WireProtocol.outboundVersion(
35+
for: appVersion,
36+
approvalSource: approvalSource
37+
) else {
38+
throw CursorShimVersionError.mismatch(
39+
app: appVersion ?? -1,
40+
shim: WireProtocol.version
41+
)
42+
}
43+
44+
var authenticated = message
45+
authenticated["token"] = .string(token)
46+
authenticated["protocol_version"] = .number(Double(outboundVersion))
47+
if outboundVersion == WireProtocol.legacyBridgeVersion {
48+
authenticated.removeValue(forKey: "approval_source")
49+
}
50+
51+
let payload = try JSONEncoder().encode(authenticated)
52+
return try UnixSocketClient.request(payload, socketPath: socketPath, timeout: timeout)
53+
}
54+
55+
if let stdout = result.stdout {
56+
print(stdout)
57+
}
58+
exit(result.exitCode)
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
import Foundation
2+
import TapQOpenCodeAdapter
3+
import TapQPOSIXBridgeClient
4+
import TapQWireProtocol
5+
6+
// Thin executable edge for the TapQ OpenCode plugin: relay JSON in on stdin, one
7+
// authenticated broker round-trip per relayed event, one decision object out on stdout.
8+
// Decision and fail-open policy live in OpenCodeHookShim so they can be tested
9+
// independently of the executable edge.
10+
11+
let stdinData = FileHandle.standardInput.readDataToEndOfFile()
12+
let discovery = BrokerDiscovery()
13+
14+
enum OpenCodeShimVersionError: Error {
15+
case mismatch(app: Int, shim: Int)
16+
case unknownApprovalSource(String)
17+
}
18+
19+
let result = OpenCodeHookShim.handle(stdinData: stdinData) { message, timeout in
20+
let (socketPath, token, appVersion, _) = try discovery.readDiscovery()
21+
22+
let sourceRaw = message["approval_source"]?.stringValue
23+
let approvalSource = sourceRaw.flatMap(ApprovalSource.init(rawValue:))
24+
if let sourceRaw, approvalSource == nil {
25+
throw OpenCodeShimVersionError.unknownApprovalSource(sourceRaw)
26+
}
27+
28+
// An OpenCode permission prompt carries the same policy significance as Claude's and
29+
// Codex's native PermissionRequest and therefore requires wire v3. Notification
30+
// traffic may temporarily bridge to a discovered v2 runtime.
31+
guard let outboundVersion = WireProtocol.outboundVersion(
32+
for: appVersion,
33+
approvalSource: approvalSource
34+
) else {
35+
throw OpenCodeShimVersionError.mismatch(
36+
app: appVersion ?? -1,
37+
shim: WireProtocol.version
38+
)
39+
}
40+
41+
var authenticated = message
42+
authenticated["token"] = .string(token)
43+
authenticated["protocol_version"] = .number(Double(outboundVersion))
44+
if outboundVersion == WireProtocol.legacyBridgeVersion {
45+
authenticated.removeValue(forKey: "approval_source")
46+
}
47+
48+
let payload = try JSONEncoder().encode(authenticated)
49+
return try UnixSocketClient.request(payload, socketPath: socketPath, timeout: timeout)
50+
}
51+
52+
if let stdout = result.stdout {
53+
print(stdout)
54+
}
55+
exit(result.exitCode)

‎Package.swift‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,14 @@ var products: [Product] = [
1313
.library(name: "TapQPOSIXBridgeClient", targets: ["TapQPOSIXBridgeClient"]),
1414
.library(name: "TapQClaudeAdapter", targets: ["TapQClaudeAdapter"]),
1515
.library(name: "TapQCodexAdapter", targets: ["TapQCodexAdapter"]),
16+
.library(name: "TapQCursorAdapter", targets: ["TapQCursorAdapter"]),
17+
.library(name: "TapQOpenCodeAdapter", targets: ["TapQOpenCodeAdapter"]),
1618
.library(name: "TapQVoiceBackends", targets: ["TapQVoiceBackends"]),
1719
.executable(name: "tapq", targets: ["tapq"]),
1820
.executable(name: "tapq-hook", targets: ["tapq-hook"]),
1921
.executable(name: "tapq-codex-hook", targets: ["tapq-codex-hook"]),
22+
.executable(name: "tapq-cursor-hook", targets: ["tapq-cursor-hook"]),
23+
.executable(name: "tapq-opencode-hook", targets: ["tapq-opencode-hook"]),
2024
]
2125

2226
var targets: [Target] = [
@@ -66,6 +70,16 @@ var targets: [Target] = [
6670
dependencies: ["TapQContracts", "TapQPOSIXSupport", "TapQWireProtocol"],
6771
swiftSettings: swiftSettings
6872
),
73+
.target(
74+
name: "TapQCursorAdapter",
75+
dependencies: ["TapQContracts", "TapQPOSIXSupport", "TapQWireProtocol"],
76+
swiftSettings: swiftSettings
77+
),
78+
.target(
79+
name: "TapQOpenCodeAdapter",
80+
dependencies: ["TapQContracts", "TapQPOSIXSupport", "TapQWireProtocol"],
81+
swiftSettings: swiftSettings
82+
),
6983
// Portable: the OpenAI Realtime adapter reaches the network only through an injected
7084
// transport seam, so the target itself imports nothing beyond Foundation and contracts.
7185
.target(
@@ -80,7 +94,9 @@ var targets: [Target] = [
8094
"TapQCodexAdapter",
8195
"TapQContextBaseline",
8296
"TapQContracts",
97+
"TapQCursorAdapter",
8398
"TapQDetectionBaseline",
99+
"TapQOpenCodeAdapter",
84100
"TapQPOSIXSupport",
85101
"TapQVoiceBackends",
86102
"TapQWireProtocol",
@@ -99,6 +115,12 @@ var targets: [Target] = [
99115
path: "Executables/tapq-codex-hook",
100116
swiftSettings: swiftSettings
101117
),
118+
.executableTarget(
119+
name: "tapq-cursor-hook",
120+
dependencies: ["TapQCursorAdapter", "TapQPOSIXBridgeClient", "TapQWireProtocol"],
121+
path: "Executables/tapq-cursor-hook",
122+
swiftSettings: swiftSettings
123+
),
102124
.testTarget(
103125
name: "TapQContractsTests",
104126
dependencies: ["TapQContracts"],
@@ -159,6 +181,42 @@ var targets: [Target] = [
159181
],
160182
swiftSettings: swiftSettings
161183
),
184+
.executableTarget(
185+
name: "tapq-opencode-hook",
186+
dependencies: ["TapQOpenCodeAdapter", "TapQPOSIXBridgeClient", "TapQWireProtocol"],
187+
path: "Executables/tapq-opencode-hook",
188+
swiftSettings: swiftSettings
189+
),
190+
.testTarget(
191+
name: "TapQOpenCodeAdapterTests",
192+
dependencies: [
193+
"TapQContracts",
194+
"TapQOpenCodeAdapter",
195+
"TapQPOSIXSupport",
196+
"TapQWireProtocol",
197+
],
198+
swiftSettings: swiftSettings
199+
),
200+
.testTarget(
201+
name: "TapQOpenCodeProcessTests",
202+
dependencies: [
203+
"TapQBrokerRuntime",
204+
"TapQContracts",
205+
"TapQWireProtocol",
206+
],
207+
resources: [.copy("Fixtures")],
208+
swiftSettings: swiftSettings
209+
),
210+
.testTarget(
211+
name: "TapQCursorAdapterTests",
212+
dependencies: [
213+
"TapQContracts",
214+
"TapQCursorAdapter",
215+
"TapQPOSIXSupport",
216+
"TapQWireProtocol",
217+
],
218+
swiftSettings: swiftSettings
219+
),
162220
.testTarget(
163221
name: "TapQCodexProcessTests",
164222
dependencies: [

‎README.md‎

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,8 @@ AI agents need to interact with you for the best outcome. TapQ turns those
2727
interactions into speech in your ear and your response into a gesture: nod to
2828
approve, shake to deny, tilt and tap to choose an option — or say a word when
2929
that's easier. It runs quietly in the background and works hands-free through
30-
devices you already wear — AirPods today, with Claude Code and Codex as the first
31-
supported agents — so you never touch a keyboard or look at a screen to keep an
30+
devices you already wear — AirPods today, with Claude Code, Codex, and OpenCode as
31+
the first supported agents — so you never touch a keyboard or look at a screen to keep an
3232
agent moving. You can also build your own gesture agent with [TapQ's SDK](#sdk).
3333

3434
## What it does
@@ -66,11 +66,12 @@ agent moving. You can also build your own gesture agent with [TapQ's SDK](#sdk).
6666

6767
## Current support
6868

69-
TapQ works today with Claude Code (hook support) and a local Codex CLI
70-
(`0.142.5` or newer), on macOS 14+, with any AirPods that expose head motion —
71-
AirPods Pro (all generations), AirPods 3 and later, and AirPods Max; stem
69+
TapQ works today with Claude Code (hook support), a local Codex CLI
70+
(`0.142.5` or newer), Cursor (agent hooks), and OpenCode (`1.18.15` or newer,
71+
through a TapQ-managed plugin), on macOS 14+, with any AirPods that expose head
72+
motion — AirPods Pro (all generations), AirPods 3 and later, and AirPods Max; stem
7273
swipes need AirPods Pro 2 or later. Linux runs the portable core and management
73-
CLI. Cursor and Apple Watch are next on the [roadmap](#roadmap).
74+
CLI. Apple Watch is next on the [roadmap](#roadmap).
7475

7576
## Controls
7677

@@ -96,8 +97,8 @@ normal on-screen flow.
9697
TapQ is source-only for now — no Homebrew formula or signed download yet. You need
9798
Swift 6, macOS 14 or newer with Xcode 16 (or a compatible toolchain), an AirPods
9899
model with headphone motion (AirPods Pro, AirPods 3 or later, or AirPods Max —
99-
tested on AirPods Pro), and Claude Code with hook support or a local Codex CLI
100-
(`0.142.5` or newer). Keep the AirPods connected,
100+
tested on AirPods Pro), and Claude Code with hook support, a local Codex CLI
101+
(`0.142.5` or newer), or OpenCode (`1.18.15` or newer). Keep the AirPods connected,
101102
in-ear, and selected as the audio output.
102103

103104
Without AirPods, `tapq serve` still runs. TapQ says so once and degrades to a plain
@@ -126,6 +127,12 @@ build/TapQRuntime.app/Contents/MacOS/tapq integration claude install --permissio
126127

127128
# Codex — then open Codex, run /hooks, and trust the TapQ hooks:
128129
build/TapQRuntime.app/Contents/MacOS/tapq integration codex install
130+
131+
# Cursor — restart Cursor if an already-open session does not pick the hooks up:
132+
build/TapQRuntime.app/Contents/MacOS/tapq integration cursor install
133+
134+
# OpenCode — then restart OpenCode so it loads the TapQ plugin:
135+
build/TapQRuntime.app/Contents/MacOS/tapq integration opencode install
129136
```
130137

131138
**3. Start TapQ** and keep it running while you use the agent:
@@ -136,7 +143,8 @@ scripts/run-runtime-app.sh serve
136143

137144
That's the whole loop: the next time the agent stops to ask, you'll hear it.
138145

139-
For permission-policy details, the exact Codex hook contract, question classifiers,
146+
For permission-policy details, the exact Codex hook and OpenCode plugin contracts,
147+
question classifiers,
140148
the risk reasoner, and packaging, see the
141149
[integration guide](docs/INTEGRATIONS.md); for every command and flag, see the
142150
[CLI reference](docs/CLI.md).
@@ -154,7 +162,7 @@ watch this repository for the first SDK release.
154162
## Roadmap
155163

156164
TapQ aims to be an agent-neutral, device-neutral interaction layer for hands-free
157-
computing. Next up, in priority order: a **Cursor** adapter, **Apple Watch** support
165+
computing. Next up, in priority order: **Apple Watch** support
158166
(wrist gestures, Digital Crown, haptics), a **quiet output mode** for meetings, and
159167
**prompt filtering** so routine approvals are auto-answered under your policy and
160168
only the prompts that deserve you reach you.
@@ -169,7 +177,7 @@ roadmap — agent integrations, wearables, and interaction capabilities — live
169177
- [CLI reference](docs/CLI.md) — every command and flag, including `tapq capture`
170178
and `tapq replay` for recording motion and scoring gesture accuracy offline
171179
- [Integration guide](docs/INTEGRATIONS.md) — permission policies, the Codex hook
172-
contract, question classifiers, the risk reasoner, and packaging
180+
and OpenCode plugin contracts, question classifiers, the risk reasoner, and packaging
173181
- [Roadmap](docs/ROADMAP.md)
174182
- [Troubleshooting](TROUBLESHOOTING.md)
175183
- [Contributing](CONTRIBUTING.md) — includes the build/test/boundary checks to run

0 commit comments

Comments
 (0)