talking-stick 0.1.0 → 0.1.2

package/README.md

@@ -2,32 +2,51 @@
 
 An MCP coordination server that lets multiple AI coding agents share a single workspace without stepping on each other. One agent holds the stick at a time; handoffs carry structured context so the next agent doesn't have to re-derive it.
 
-**Version:** 0.1.0. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box.
+**Version:** 0.1.2. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box.
 
 ## Quickstart
 
-Three commands from zero to coordinated agents. No repo clone required.
+Three steps, then you're coordinating two agents in the same repo.
+
+### 1. Install the `tt` binary
 
 ```bash
-# 1. Install the `tt` binary from npm
 npm i -g talking-stick
+```
 
-# 2. Register Talking Stick as an MCP server + install the coordination skill
-#    across every harness detected on your machine
-tt install --all
-tt install-skill --all
+### 2. Register the MCP server and skill in every harness
 
-# 3. Restart your agent harness (Claude Code, Codex, Gemini, OpenCode).
-#    The `talking_stick` tools now appear in any workspace.
+```bash
+tt install --all
 ```
 
-That's it. The next time two agents `cd` into the same repo, they see each other as members of one room, take turns automatically, and hand off structured context when they release the stick.
+Restart any harness that was already running so it loads the new MCP server. The `talking_stick` tools and skill now appear in every workspace.
+
+### 3. Try it: two agents, one repo
+
+Open two terminal panes side by side — tmux split, iTerm split, two windows, whatever you like. `cd` into the same repo in each, and launch a different harness in each pane:
+
+| Pane A — Claude Code | Pane B — Codex |
+|---|---|
+| `cd ~/myrepo && claude [--dangerously-skip-permissions]` | `cd ~/myrepo && codex` |
+
+Then prompt them.
+
+**Pane A (Claude Code):**
+
+> Draft a plan to add OAuth login. When it's solid, pass the stick to Codex for critique. After Codex hands it back with revisions, finalize, then pass to Codex to implement — you'll test and review. `/talking-stick`
+
+**Pane B (Codex):**
+
+> Join the room and wait for the stick. When Claude passes you a plan, critique it sharply and pass it back with revisions. Later, when Claude hands you the implementation turn, build it and pass back for review. `$talking-stick`
+
+That's the whole workflow. They negotiate turns automatically, hand off structured context (status, next action, artifacts) at each transition, and never edit the repo at the same time.
 
 ### Install options
 
 | Method | Command | Notes |
 |---|---|---|
-| **From npm** | `npm i -g talking-stick` | Published as `0.1.0`. Requires Node ≥ 22. |
+| **From npm** | `npm i -g talking-stick` | Published as `0.1.2`. Requires Node ≥ 22. |
 | **From GitHub** | `npm i -g github:mostlydev/talking-stick` | Tracks the `master` branch; builds on install via the `prepare` hook. |
 | **From source** | `git clone … && npm install && npm link` | For contributors. |
 
@@ -35,27 +54,34 @@ All three produce a `tt` binary on your `PATH`. Everything else below works iden
 
 ### Verify without installing
 
-Want to see exactly what `tt install`/`tt install-skill` would change before touching anything?
+Want to see exactly what `tt install` would change before touching anything?
 
 ```bash
 tt install --all --print
-tt install-skill --all --print
 ```
 
 ### Install into a subset
 
 ```bash
 tt install claude-code codex
-tt install-skill gemini
 ```
 
-During normal execution, install commands skip harnesses that are not present instead of failing or creating new harness config roots. For example, `tt install-skill codex` only creates `~/.codex/skills/` if `~/.codex/` already exists.
+During normal execution, install commands skip harnesses that are not present instead of failing or creating new harness config roots.
+
+### Update
+
+Uses the right npm/pnpm/yarn by default:
+
+```bash
+tt self-update
+```
+
+Skills are symlinked automatically, so they don't need an update.
 
 ### Remove
 
 ```bash
 tt uninstall --all
-tt uninstall-skill --all
 ```
 
 ## What it gives your agent
@@ -94,7 +120,9 @@ While you wait your turn you may still need to flag something to the current own
 
 ## How installation works per harness
 
-`tt install` prefers each harness's own `mcp add` subcommand when available (so the server ends up in the right user-global config with the right schema), and falls back to direct JSON editing when it isn't.
+`tt install` installs both pieces a harness needs: the MCP server registration and the bundled `talking-stick` skill.
+
+For MCP registration, it prefers each harness's own `mcp add` subcommand when available (so the server ends up in the right user-global config with the right schema), and falls back to direct JSON editing when it isn't.
 
 | Harness       | Scope        | Under the hood                                                              |
 |---------------|--------------|-----------------------------------------------------------------------------|
@@ -105,9 +133,9 @@ While you wait your turn you may still need to flag something to the current own
 
 All four install into **user-global scope**, not project-local. A coordination server is only useful if every workspace your agent enters can see the same rooms — project-scoped MCP would defeat the point.
 
-If you'd rather register it by hand, run `tt install --print <harness>` to see the exact command or JSON edit, then apply it yourself.
+If you'd rather apply setup by hand, run `tt install --print <harness>` to see the exact MCP and skill actions, then apply them yourself.
 
-## How skill installation works per harness
+## Skill paths per harness
 
 Talking Stick also ships with a portable `talking-stick` skill:
 
@@ -116,9 +144,9 @@ Talking Stick also ships with a portable `talking-stick` skill:
 - Gemini: installed with `gemini skills install ... --scope user` or linked with `gemini skills link ... --scope user`
 - OpenCode: copied or linked into `~/.opencode/skills/talking-stick`
 
-By default, `tt install-skill` links the bundled skill into each harness so local updates are picked up immediately. Pass `--copy` if you want a standalone snapshot instead.
+By default, `tt install` links the bundled skill into each harness so local updates are picked up immediately. Pass `--copy` if you want a standalone snapshot instead.
 
-Human CLI invocations also perform a silent best-effort sync for already-installed file-based skills in Claude Code, Codex, and OpenCode. If the installed skill is a copy, it is refreshed from the bundled skill; if it is a stale symlink, it is relinked. Missing harness config directories and missing skill installs are skipped. Gemini skills are managed by Gemini's own registry, so use `tt install-skill gemini` after updating when needed.
+Human CLI invocations also perform a silent best-effort sync for already-installed file-based skills in Claude Code, Codex, and OpenCode. If the installed skill is a copy, it is refreshed from the bundled skill; if it is a stale symlink, it is relinked. Missing harness config directories and missing skill installs are skipped. Gemini skills are managed by Gemini's own registry, so use `tt install gemini` after updating when needed.
 
 ## Human CLI
 
@@ -141,10 +169,8 @@ tt takeover [path] [--reason TEXT]                        # alias for take
 tt notes add <body> [--turn N] [--path DIR] [--stdin]     # leave an async note
 tt notes list [--all] [--after ID] [--limit N] [--path DIR] # read notes
 tt mcp                                                    # run the MCP stdio server
-tt install <harness...> | --all [--print]                 # register MCP server
-tt uninstall <harness...> | --all [--print]               # remove MCP server
-tt install-skill <harness...> | --all [--print] [--copy] [--link]  # install global talking-stick skill
-tt uninstall-skill <harness...> | --all [--print]         # remove global talking-stick skill
+tt install <harness...> | --all [--print] [--copy] [--link]  # install MCP server and skill
+tt uninstall <harness...> | --all [--print]               # remove MCP server and skill
 tt self-update [--print] [--manager npm|pnpm|yarn|bun]    # update to the latest published tt
 ```
 

package/dist/cli/install-commands.js

@@ -5,17 +5,21 @@ import { detectInstallSource, isPackageManager, planSelfUpdate, resolveCurrentBi
 import { getStringOption, hasOption, normalizeBooleanFlag } from "./parser.js";
 export async function runInstallCommand(parsed) {
     normalizeBooleanFlag(parsed, "print");
+    normalizeBooleanFlag(parsed, "copy");
+    normalizeBooleanFlag(parsed, "link");
     const harnesses = selectHarnesses(parsed);
     const dryRun = hasOption(parsed, "print");
-    const installOptions = { skipMissing: true };
-    const actions = harnesses.map((harness) => planInstall(harness, installOptions));
+    const installOptions = {
+        link: resolveSkillInstallLinkMode(parsed),
+        skipMissing: true
+    };
     if (dryRun) {
-        for (const action of actions) {
+        for (const action of planCombinedInstallActions(harnesses, installOptions)) {
             printActionPlan(action);
         }
         return;
     }
-    const results = await Promise.all(actions.map((action) => runAction(action, installOptions)));
+    const results = (await Promise.all(harnesses.map((harness) => runCombinedInstall(harness, installOptions)))).flat();
     reportInstallResults(results, "install");
 }
 export async function runUninstallCommand(parsed) {
@@ -23,14 +27,14 @@ export async function runUninstallCommand(parsed) {
     const harnesses = selectHarnesses(parsed);
     const dryRun = hasOption(parsed, "print");
     const installOptions = { skipMissing: true };
-    const actions = harnesses.map((harness) => planUninstall(harness, installOptions));
+    const actions = planCombinedUninstallActions(harnesses, installOptions);
     if (dryRun) {
         for (const action of actions) {
             printActionPlan(action);
         }
         return;
     }
-    const results = await Promise.all(actions.map((action) => runAction(action, installOptions)));
+    const results = (await Promise.all(harnesses.map((harness) => runCombinedUninstall(harness, installOptions)))).flat();
     reportInstallResults(results, "uninstall");
 }
 export async function runInstallSkillCommand(parsed) {
@@ -107,6 +111,49 @@ function resolveSkillInstallLinkMode(parsed) {
     }
     return true;
 }
+function planCombinedInstallActions(harnesses, installOptions) {
+    return harnesses.flatMap((harness) => {
+        const mcpAction = planInstall(harness, installOptions);
+        if (mcpAction.kind === "skip") {
+            return [mcpAction];
+        }
+        return [
+            mcpAction,
+            planSkillInstall(harness, {
+                ...installOptions,
+                // In dry-run mode, show the skill action that will follow MCP setup
+                // even when the MCP installer is what creates the harness config root.
+                skipMissing: false
+            })
+        ];
+    });
+}
+function planCombinedUninstallActions(harnesses, installOptions) {
+    return harnesses.flatMap((harness) => [
+        planUninstall(harness, installOptions),
+        planSkillUninstall(harness, {
+            ...installOptions,
+            skipMissing: false
+        })
+    ]);
+}
+async function runCombinedInstall(harness, installOptions) {
+    const mcpAction = planInstall(harness, installOptions);
+    const mcpResult = await runAction(mcpAction, installOptions);
+    if (!mcpResult.ok || mcpResult.skipped) {
+        return [mcpResult];
+    }
+    const skillAction = planSkillInstall(harness, installOptions);
+    const skillResult = await runAction(skillAction, installOptions);
+    return [mcpResult, skillResult];
+}
+async function runCombinedUninstall(harness, installOptions) {
+    const mcpAction = planUninstall(harness, installOptions);
+    const mcpResult = await runAction(mcpAction, installOptions);
+    const skillAction = planSkillUninstall(harness, installOptions);
+    const skillResult = await runAction(skillAction, installOptions);
+    return [mcpResult, skillResult];
+}
 function selectHarnesses(parsed) {
     if (hasOption(parsed, "all")) {
         const detected = SUPPORTED_HARNESSES.filter((harness) => detectHarness(harness).detected);

package/dist/cli/output.js

@@ -134,10 +134,8 @@ Commands:
   tt notes add <body> [--turn N] [--path DIR] [--stdin]
   tt notes list [--all] [--after NOTE_ID] [--limit N] [--path DIR]
   tt mcp
-  tt install <harness...> | --all [--print]
+  tt install <harness...> | --all [--print] [--copy] [--link]
   tt uninstall <harness...> | --all [--print]
-  tt install-skill <harness...> | --all [--print] [--copy] [--link]
-  tt uninstall-skill <harness...> | --all [--print]
   tt self-update [--print] [--manager npm|pnpm|yarn|bun]
 
 Harnesses: ${SUPPORTED_HARNESSES.join(", ")}

package/dist/cli/registry.js

@@ -28,8 +28,8 @@ export const COMMAND_REGISTRY = [
         needsRuntime: false,
         startupMaintenance: false,
         internal: false,
-        usage: "tt install <harness...> | --all [--print]",
-        description: "Install Talking Stick into harness MCP configs.",
+        usage: "tt install <harness...> | --all [--print] [--copy] [--link]",
+        description: "Install Talking Stick into harness MCP configs and skills.",
         handler: ({ parsed }) => runInstallCommand(parsed)
     },
     {
@@ -38,7 +38,7 @@ export const COMMAND_REGISTRY = [
         startupMaintenance: false,
         internal: false,
         usage: "tt uninstall <harness...> | --all [--print]",
-        description: "Remove Talking Stick from harness MCP configs.",
+        description: "Remove Talking Stick from harness MCP configs and skills.",
         handler: ({ parsed }) => runUninstallCommand(parsed)
     },
     {

package/dist/mcp-server.js

@@ -27,7 +27,7 @@ export function createMcpServer(service = new TalkingStickService()) {
     const resolveConnectionIdentity = createConnectionIdentityResolver();
     const server = new McpServer({
         name: "talking-stick",
-        version: "0.1.0"
+        version: "0.1.2"
     });
     server.registerTool("list_rooms", {
         title: "List Rooms",

package/docs/releases/0.1.1.md

@@ -0,0 +1,30 @@
+# Talking Stick 0.1.1
+
+Date: 2026-04-27
+
+Patch release focused on onboarding clarity and tighter multi-agent wait
+cadence.
+
+## Changed
+
+### Clearer quickstart
+
+The README quickstart now presents the setup as three steps: install `tt`,
+register the MCP server and skill across harnesses, then try a concrete
+two-agent Claude Code / Codex workflow in one repo.
+
+### Wait cycles before scheduled wakeups
+
+The bundled skill now tells agents to prefer direct `wait_for_turn` wait cycles
+and background long-polls over scheduled wakeups. Scheduled wakeups are framed
+as fallback behavior, and active multi-agent wakeups are capped at 60-120
+seconds unless the operator explicitly pauses the room or the task is blocked
+outside the room.
+
+## Verification
+
+- `npm run typecheck`
+- `npm test` — 208 tests across 14 files
+- `npm run build`
+- `git diff --check`
+- `npm pack --dry-run --ignore-scripts`

package/docs/releases/0.1.2.md

@@ -0,0 +1,40 @@
+# Talking Stick 0.1.2
+
+Date: 2026-04-27
+
+Patch release focused on simplifying first-time setup and keeping the README in
+sync with the CLI.
+
+## Changed
+
+### Combined harness setup
+
+`tt install` now installs both pieces each harness needs: the MCP server
+registration and the bundled Talking Stick skill. The command accepts the skill
+mode flags directly, so `tt install --all --copy` produces standalone skill
+copies while the default still links the bundled skill.
+
+`tt uninstall` now removes both the MCP registration and the installed skill for
+each selected harness.
+
+The older `tt install-skill` and `tt uninstall-skill` commands remain available
+for targeted maintenance, but they are no longer part of the normal README/help
+setup path.
+
+### README setup path
+
+The quickstart, dry-run instructions, subset install example, removal example,
+installation details, skill path section, and CLI reference now document a
+single-command setup flow:
+
+```bash
+tt install --all
+```
+
+## Verification
+
+- `npm run typecheck`
+- `npm test` — 212 tests across 14 files
+- `npm run build`
+- `git diff --check`
+- `npm pack --dry-run --ignore-scripts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talking-stick",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP coordination server for path-scoped agent handoffs.",
   "type": "module",
   "bin": {

package/skills/talking-stick/SKILL.md

@@ -30,7 +30,7 @@ Prefer the Talking Stick MCP tools when they are available. If they are not avai
 
 If coordination is required and neither the MCP tools nor the `tt` CLI are available, say so briefly and ask the user whether they want to install or enable Talking Stick first. Do not pretend coordination is active.
 
-Human CLI runs silently keep already-installed Claude Code, Codex, and OpenCode skill copies/symlinks aligned with the bundled Talking Stick skill. This is best effort and only updates existing installs; Gemini skills are registry-managed and should be refreshed with `tt install-skill gemini` when needed.
+Human CLI runs silently keep already-installed Claude Code, Codex, and OpenCode skill copies/symlinks aligned with the bundled Talking Stick skill. This is best effort and only updates existing installs; Gemini skills are registry-managed and should be refreshed with `tt install gemini` when needed.
 
 ### 2. Join the workspace room once
 
@@ -70,15 +70,15 @@ Possible outcomes:
 
 **Prefer to run the wait in the background.** If your harness supports running a command or subtask in the background, launch the wait (`wait_for_turn` or `tt wait`) as a background process so your foreground stays free for other work — reading, planning, answering the operator — until your turn arrives. Blocking the whole harness on the wait defeats the point.
 
-**Even better: use a wakeup if your harness supports one.** Some harnesses (for example Claude Code with `ScheduleWakeup`, cron-backed agents, or runtime-resumed sleeps) can sleep without keeping conversation context loaded. Prefer that over repeated long-polls: a long-poll re-evaluates your full conversation each cycle, while a wakeup pays one re-entry per actual room event.
+**Prefer wait cycles over scheduled wakeups.** A direct `wait_for_turn` long-poll keeps your cadence aligned with other agents and usually notices a released stick within the same cycle. Use scheduling only when your harness cannot keep a wait running in the background, or when it must return control between checks.
 
 Wakeup pattern:
 
 1. Probe `wait_for_turn` with `max_wait_ms: 0`.
-2. If it returns `not_yet`, schedule a wakeup and return control to the harness. Use 60-240 s in active multi-agent sessions, or 1200-1800 s at idle/operator-blocked pause points. Avoid roughly 300 s; most prompt caches expire around 5 minutes, so stay under that window or choose a much longer interval.
+2. If it returns `not_yet`, schedule a wakeup and return control to the harness. Keep active multi-agent wakeups tight: use 60-120 s, and never more than 120 s unless the operator explicitly pauses the room or the task is blocked outside the room.
 3. On wakeup, repeat from step 1.
 
-This converts repeated re-prompts into roughly one re-entry per actual event. If your harness has neither background work nor wakeups, fall back to synchronous long-polls with the longest client-safe `max_wait_ms` from §3.
+Scheduled wakeups are a fallback, not a reason to check in more slowly than agents using `wait_for_turn` directly. If your harness has neither background work nor wakeups, fall back to synchronous long-polls with the longest client-safe `max_wait_ms` from §3.
 
 Whether the wait runs in the foreground or the background, call it **once** with the client-safe `max_wait_ms` budget from above and let the server long-poll. When it returns without `your_turn`, call it again. Do not busy-loop with short waits — that generates log noise and burns cache without buying anything.
 
@@ -153,7 +153,7 @@ Example:
     }
   ],
   "open_questions": [
-    "Should install-skill default to copy or link for local development?"
+    "Should tt install default to copy or link for local development?"
   ]
 }
 ```