From 7664152d39fc37fcdce9aa2d5d2c69723775eb6a Mon Sep 17 00:00:00 2001
From: Oded Messer <18181802+omesser@users.noreply.github.com>
Date: Tue, 6 Oct 2026 02:36:46 +0300
Subject: [PATCH 1/7] docs: Show Instance Prompt examples in the README
---
README.md | 19 ++++++++++++++++++-
1 file changed, 18 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 8a146ec9c..2df544970 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,7 @@ Try the gestures in your browser: [Fidget Cues](https://omesser.github.io/fidget
## What It Does
- **Keeps you company.** It walks, naps, and reacts to your open windows. It works offline, with no AI account or subscription, for presence and play; hook it up to an AI and it takes on a life of its own, with full conversation and tool use.
-- **Pick a built-in character, or build your own.** Each character has its own sprites, animation loops, and personality. Edit any character's prompt or behavior using a plain-text personality file and a simple [manifest format](./docs/DEVELOPMENT.md#character-packages). Create your own characters, or [import and convert](./docs/DEVELOPMENT.md#importing-pets) one from the [Pets Codex](https://petscodex.com/) and [Shimeji Shop](https://shimejishop.com/) galleries.
+- **Pick a built-in character, or build your own.** Each character has its own sprites, animation loops, and personality. Edit any character's prompt or behavior using a plain-text personality file and a simple [manifest format](./docs/DEVELOPMENT.md#character-packages). Create your own characters, or [import and convert](./docs/DEVELOPMENT.md#importing-pets) one from the [Pets Codex](https://petscodex.com/) and [Shimeji Shop](https://shimejishop.com/) galleries. Or keep the character and [give it a brief of your own](#give-it-a-brief).
- **Pitches in.** Double-click to chat with the agent you already use (Claude Code, Codex, Cursor, or any ACP [harness](#harness-support)); it acts on your machine and answers in speech and motion.
- **Knows what you're up to.** It can see and react to your open windows - titles only, and only with consent, for context-aware chatter. It never reads screen pixels and [never takes screenshots](#computer-use); Reading titles and application names needs your explicit consent.
- **Gets out of your way when you ask it to.** Automatically fades away when in fullscreen, hides at will on hotkey, and comes back when you want it to.
@@ -98,6 +98,23 @@ The bar at the bottom says what the fidget is doing and when it next thinks.
Advanced opens the ladder: Behavior, Primitive, Animation, State, Facing, and
the Director's countdown. Answers need a Director; see [Get It](#get-it).
+### Give It a Brief
+
+Each fidget takes a brief of your own, up to 2000 characters, on top of its Character's personality. Summon it (double-click), open the **Prompt** tab, paste one of these under **Your own layer**, and edit it to fit. Saving starts a new conversation, and the brief stays with that fidget if you switch its Character. The brief changes how the fidget reacts each time it wakes. It doesn't schedule anything.
+
+| Paste and edit | How it reacts on a wake |
+|---|---|
+| `I'm deep in debugging today. If iTerm2 is still in front around mid-afternoon (say 15:00), tell me to wrap up. A technician is coming.` | Sees the time and that iTerm2 is still in front, and tells you to wrap up. ¹ ² |
+| `You're my screen-guard buddy. Every couple of hours, nag me to get up and stretch my legs.` | Checks the time against the last nag and sends you off to stretch, in its own voice. ¹ |
+| `If my editor stays in front for a long stretch, ask me to explain the bug to you, like a rubber duck.` | Sees your editor still in front, wake after wake, and asks you to walk it through the bug. ¹ ² |
+| `You're a theatre critic. When you're perched on a window, review that app in one dramatic line.` | Perch it on a window and it reviews the app it's standing on. ² |
+| `When I ask you to check something on my machine, do it, then report back in one line, in character.`
 | Your [Harness](#harness-support) does the work with its own tools, and the fidget answers. ³ |
+
+> [!IMPORTANT]
+> ¹ **No timers.** Fidget doesn't schedule anything. It acts on the brief when it next wakes, and the gap between unprompted wakes grows to as much as two hours, so "around 15:00" can land well after 15:00. A poke, a pickup, a Perch, or a chat wakes it at once and resets the gap. **Use a real alarm for anything you can't miss.**
+
+² Needs the **Window and application names** consent in Settings → Privacy: app names and window titles only, never pixels, and Fidget [never takes screenshots](#computer-use) ([ADR-0032](./docs/adr/0032-one-consent-for-titles-and-application-names.md)). ³ A Model API can't run tools.
+
## Characters
Buddy Bot is the default. Eight Characters ship; each moves and speaks differently. A name links to its full prompt.
From e76d44cdc562f1724d98725b050054691775eb3f Mon Sep 17 00:00:00 2001
From: Oded Messer <18181802+omesser@users.noreply.github.com>
Date: Tue, 6 Oct 2026 02:42:36 +0300
Subject: [PATCH 2/7] docs: Drop invented timing from brief examples
---
README.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/README.md b/README.md
index 2df544970..724bb9d5f 100644
--- a/README.md
+++ b/README.md
@@ -105,8 +105,8 @@ Each fidget takes a brief of your own, up to 2000 characters, on top of its Char
| Paste and edit | How it reacts on a wake |
|---|---|
| `I'm deep in debugging today. If iTerm2 is still in front around mid-afternoon (say 15:00), tell me to wrap up. A technician is coming.` | Sees the time and that iTerm2 is still in front, and tells you to wrap up. ¹ ² |
-| `You're my screen-guard buddy. Every couple of hours, nag me to get up and stretch my legs.` | Checks the time against the last nag and sends you off to stretch, in its own voice. ¹ |
-| `If my editor stays in front for a long stretch, ask me to explain the bug to you, like a rubber duck.` | Sees your editor still in front, wake after wake, and asks you to walk it through the bug. ¹ ² |
+| `You're my screen-guard buddy. Every couple of hours, nag me to get up and stretch my legs.` | Sees the time on a wake and nags you to stretch, in its own voice. ¹ |
+| `If my editor stays in front for a long stretch, ask me to explain the bug to you, like a rubber duck.` | Sees the editor in front on a wake and asks you to walk it through the bug. ¹ ² |
| `You're a theatre critic. When you're perched on a window, review that app in one dramatic line.` | Perch it on a window and it reviews the app it's standing on. ² |
| `When I ask you to check something on my machine, do it, then report back in one line, in character.`
 | Your [Harness](#harness-support) does the work with its own tools, and the fidget answers. ³ |
From 6b9bf46f5c1c6d3cfb812abe7b0591e7012d2da2 Mon Sep 17 00:00:00 2001
From: Oded Messer <18181802+omesser@users.noreply.github.com>
Date: Tue, 6 Oct 2026 02:51:12 +0300
Subject: [PATCH 3/7] docs: Name the Instance Prompt and give it its own bullet
---
README.md | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
diff --git a/README.md b/README.md
index 724bb9d5f..a07b14650 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,8 @@ Try the gestures in your browser: [Fidget Cues](https://omesser.github.io/fidget
## What It Does
- **Keeps you company.** It walks, naps, and reacts to your open windows. It works offline, with no AI account or subscription, for presence and play; hook it up to an AI and it takes on a life of its own, with full conversation and tool use.
-- **Pick a built-in character, or build your own.** Each character has its own sprites, animation loops, and personality. Edit any character's prompt or behavior using a plain-text personality file and a simple [manifest format](./docs/DEVELOPMENT.md#character-packages). Create your own characters, or [import and convert](./docs/DEVELOPMENT.md#importing-pets) one from the [Pets Codex](https://petscodex.com/) and [Shimeji Shop](https://shimejishop.com/) galleries. Or keep the character and [give it a brief of your own](#give-it-a-brief).
+- **Pick a built-in character, or build your own.** Each character has its own sprites, animation loops, and personality. Edit any character's prompt or behavior using a plain-text personality file and a simple [manifest format](./docs/DEVELOPMENT.md#character-packages). Create your own characters, or [import and convert](./docs/DEVELOPMENT.md#importing-pets) one from the [Pets Codex](https://petscodex.com/) and [Shimeji Shop](https://shimejishop.com/) galleries.
+- **Takes an Instance Prompt.** Write your own text for one fidget, up to 2000 characters, on top of its Character's personality, and it changes how that fidget reacts. See [Give It an Instance Prompt](#give-it-an-instance-prompt) for examples.
- **Pitches in.** Double-click to chat with the agent you already use (Claude Code, Codex, Cursor, or any ACP [harness](#harness-support)); it acts on your machine and answers in speech and motion.
- **Knows what you're up to.** It can see and react to your open windows - titles only, and only with consent, for context-aware chatter. It never reads screen pixels and [never takes screenshots](#computer-use); Reading titles and application names needs your explicit consent.
- **Gets out of your way when you ask it to.** Automatically fades away when in fullscreen, hides at will on hotkey, and comes back when you want it to.
@@ -98,9 +99,9 @@ The bar at the bottom says what the fidget is doing and when it next thinks.
Advanced opens the ladder: Behavior, Primitive, Animation, State, Facing, and
the Director's countdown. Answers need a Director; see [Get It](#get-it).
-### Give It a Brief
+### Give It an Instance Prompt
-Each fidget takes a brief of your own, up to 2000 characters, on top of its Character's personality. Summon it (double-click), open the **Prompt** tab, paste one of these under **Your own layer**, and edit it to fit. Saving starts a new conversation, and the brief stays with that fidget if you switch its Character. The brief changes how the fidget reacts each time it wakes. It doesn't schedule anything.
+An Instance Prompt is your own text for one fidget, up to 2000 characters, layered on top of its Character's personality. To write one, double-click the fidget to summon it, open the **Prompt** tab, and type in the **Your own layer** box. That box is the Instance Prompt. Paste one of the examples below and edit it to fit. Saving starts a new conversation, and the Instance Prompt stays with that fidget if you switch its Character. The Instance Prompt changes how the fidget reacts each time it wakes. It doesn't schedule anything.
| Paste and edit | How it reacts on a wake |
|---|---|
@@ -111,7 +112,7 @@ Each fidget takes a brief of your own, up to 2000 characters, on top of its Char
| `When I ask you to check something on my machine, do it, then report back in one line, in character.`
 | Your [Harness](#harness-support) does the work with its own tools, and the fidget answers. ³ |
> [!IMPORTANT]
-> ¹ **No timers.** Fidget doesn't schedule anything. It acts on the brief when it next wakes, and the gap between unprompted wakes grows to as much as two hours, so "around 15:00" can land well after 15:00. A poke, a pickup, a Perch, or a chat wakes it at once and resets the gap. **Use a real alarm for anything you can't miss.**
+> ¹ **No timers.** Fidget doesn't schedule anything. It acts on the Instance Prompt when it next wakes, and the gap between unprompted wakes grows to as much as two hours, so "around 15:00" can land well after 15:00. A poke, a pickup, a Perch, or a chat wakes it at once and resets the gap. **Use a real alarm for anything you can't miss.**
² Needs the **Window and application names** consent in Settings → Privacy: app names and window titles only, never pixels, and Fidget [never takes screenshots](#computer-use) ([ADR-0032](./docs/adr/0032-one-consent-for-titles-and-application-names.md)). ³ A Model API can't run tools.
From e673f6bfcc48e0dcd42d67de30c517c2806e4274 Mon Sep 17 00:00:00 2001
From: Oded Messer <18181802+omesser@users.noreply.github.com>
Date: Tue, 6 Oct 2026 03:28:32 +0300
Subject: [PATCH 4/7] docs: State Instance Prompt setup once above the table
Move the No timers callout and the Harness, tool use, and window-names
consent assumptions above the examples, so the table lists only what
each prompt does with that setup in place.
---
README.md | 24 ++++++++++++++----------
1 file changed, 14 insertions(+), 10 deletions(-)
diff --git a/README.md b/README.md
index a07b14650..da4a9b929 100644
--- a/README.md
+++ b/README.md
@@ -101,20 +101,24 @@ the Director's countdown. Answers need a Director; see [Get It](#get-it).
### Give It an Instance Prompt
-An Instance Prompt is your own text for one fidget, up to 2000 characters, layered on top of its Character's personality. To write one, double-click the fidget to summon it, open the **Prompt** tab, and type in the **Your own layer** box. That box is the Instance Prompt. Paste one of the examples below and edit it to fit. Saving starts a new conversation, and the Instance Prompt stays with that fidget if you switch its Character. The Instance Prompt changes how the fidget reacts each time it wakes. It doesn't schedule anything.
+An Instance Prompt is your own text for one fidget, up to 2000 characters, layered on top of its Character's personality. To write one, double-click the fidget to summon it, open the **Prompt** tab, and type in the **Your own layer** box. That box is the Instance Prompt. Paste one of the examples below and edit it to fit. Saving starts a new conversation, and the Instance Prompt stays with that fidget if you switch its Character.
-| Paste and edit | How it reacts on a wake |
-|---|---|
-| `I'm deep in debugging today. If iTerm2 is still in front around mid-afternoon (say 15:00), tell me to wrap up. A technician is coming.` | Sees the time and that iTerm2 is still in front, and tells you to wrap up. ¹ ² |
-| `You're my screen-guard buddy. Every couple of hours, nag me to get up and stretch my legs.` | Sees the time on a wake and nags you to stretch, in its own voice. ¹ |
-| `If my editor stays in front for a long stretch, ask me to explain the bug to you, like a rubber duck.` | Sees the editor in front on a wake and asks you to walk it through the bug. ¹ ² |
-| `You're a theatre critic. When you're perched on a window, review that app in one dramatic line.` | Perch it on a window and it reviews the app it's standing on. ² |
-| `When I ask you to check something on my machine, do it, then report back in one line, in character.`
 | Your [Harness](#harness-support) does the work with its own tools, and the fidget answers. ³ |
+Every example below assumes this setup:
+
+- A [Harness](#harness-support) is attached. A Model API can't run tools.
+- The Harness is allowed to use its own tools.
+- The **Window and application names** consent is on in Settings → Privacy. Fidget then reads app names and window titles only, never pixels, and it [never takes screenshots](#computer-use) ([ADR-0032](./docs/adr/0032-one-consent-for-titles-and-application-names.md)).
> [!IMPORTANT]
-> ¹ **No timers.** Fidget doesn't schedule anything. It acts on the Instance Prompt when it next wakes, and the gap between unprompted wakes grows to as much as two hours, so "around 15:00" can land well after 15:00. A poke, a pickup, a Perch, or a chat wakes it at once and resets the gap. **Use a real alarm for anything you can't miss.**
+> **No timers.** Fidget doesn't schedule anything. It acts on the Instance Prompt when it next wakes, and the gap between unprompted wakes grows to as much as two hours, so "around 15:00" can land well after 15:00. A poke, a pickup, a Perch, or a chat wakes it at once and resets the gap. **Use a real alarm for anything you can't miss.**
-² Needs the **Window and application names** consent in Settings → Privacy: app names and window titles only, never pixels, and Fidget [never takes screenshots](#computer-use) ([ADR-0032](./docs/adr/0032-one-consent-for-titles-and-application-names.md)). ³ A Model API can't run tools.
+| Paste and edit | How it reacts on a wake |
+|---|---|
+| `I'm deep in debugging today. If iTerm2 is still in front around mid-afternoon (say 15:00), tell me to wrap up. A technician is coming.` | Sees the time and that iTerm2 is still in front, and tells you to wrap up. |
+| `You're my screen-guard buddy. Every couple of hours, nag me to get up and stretch my legs.` | Sees the time on a wake and nags you to stretch, in its own voice. |
+| `If my editor stays in front for a long stretch, ask me to explain the bug to you, like a rubber duck.` | Sees the editor in front on a wake and asks you to walk it through the bug. |
+| `You're a theatre critic. When you're perched on a window, review that app in one dramatic line.` | Perch it on a window and it reviews the app it's standing on. |
+| `When I ask you to check something on my machine, do it, then report back in one line, in character.` | Does the check with your Harness's tools and reports back in one line, in character. |
## Characters
From 2dfd7ef5c37463de205e1d12b687434e9e68563a Mon Sep 17 00:00:00 2001
From: Oded Messer <18181802+omesser@users.noreply.github.com>
Date: Tue, 6 Oct 2026 03:30:38 +0300
Subject: [PATCH 5/7] docs: Retitle the Instance Prompt feature bullet
---
README.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/README.md b/README.md
index da4a9b929..d7fdfca1e 100644
--- a/README.md
+++ b/README.md
@@ -28,7 +28,7 @@ Try the gestures in your browser: [Fidget Cues](https://omesser.github.io/fidget
- **Keeps you company.** It walks, naps, and reacts to your open windows. It works offline, with no AI account or subscription, for presence and play; hook it up to an AI and it takes on a life of its own, with full conversation and tool use.
- **Pick a built-in character, or build your own.** Each character has its own sprites, animation loops, and personality. Edit any character's prompt or behavior using a plain-text personality file and a simple [manifest format](./docs/DEVELOPMENT.md#character-packages). Create your own characters, or [import and convert](./docs/DEVELOPMENT.md#importing-pets) one from the [Pets Codex](https://petscodex.com/) and [Shimeji Shop](https://shimejishop.com/) galleries.
-- **Takes an Instance Prompt.** Write your own text for one fidget, up to 2000 characters, on top of its Character's personality, and it changes how that fidget reacts. See [Give It an Instance Prompt](#give-it-an-instance-prompt) for examples.
+- **Personalize your Fidget's behavior.** Write your own text for any fidget's behavior through its Instance Prompt. It holds on top of its Character's personality, and changes how that fidget reacts. See [Give It an Instance Prompt](#give-it-an-instance-prompt) for examples.
- **Pitches in.** Double-click to chat with the agent you already use (Claude Code, Codex, Cursor, or any ACP [harness](#harness-support)); it acts on your machine and answers in speech and motion.
- **Knows what you're up to.** It can see and react to your open windows - titles only, and only with consent, for context-aware chatter. It never reads screen pixels and [never takes screenshots](#computer-use); Reading titles and application names needs your explicit consent.
- **Gets out of your way when you ask it to.** Automatically fades away when in fullscreen, hides at will on hotkey, and comes back when you want it to.
From 623ecdbeeec5aa1687148acab1c0a039269ca162 Mon Sep 17 00:00:00 2001
From: Oded Messer <18181802+omesser@users.noreply.github.com>
Date: Tue, 6 Oct 2026 03:35:01 +0300
Subject: [PATCH 6/7] docs: Drop the length limit and ADR link from Instance
Prompt copy
---
README.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/README.md b/README.md
index d7fdfca1e..a574a35ad 100644
--- a/README.md
+++ b/README.md
@@ -101,13 +101,13 @@ the Director's countdown. Answers need a Director; see [Get It](#get-it).
### Give It an Instance Prompt
-An Instance Prompt is your own text for one fidget, up to 2000 characters, layered on top of its Character's personality. To write one, double-click the fidget to summon it, open the **Prompt** tab, and type in the **Your own layer** box. That box is the Instance Prompt. Paste one of the examples below and edit it to fit. Saving starts a new conversation, and the Instance Prompt stays with that fidget if you switch its Character.
+An Instance Prompt is your own text for one fidget, layered on top of its Character's personality. To write one, double-click the fidget to summon it, open the **Prompt** tab, and type in the **Your own layer** box. That box is the Instance Prompt. Paste one of the examples below and edit it to fit. Saving starts a new conversation, and the Instance Prompt stays with that fidget if you switch its Character.
Every example below assumes this setup:
- A [Harness](#harness-support) is attached. A Model API can't run tools.
- The Harness is allowed to use its own tools.
-- The **Window and application names** consent is on in Settings → Privacy. Fidget then reads app names and window titles only, never pixels, and it [never takes screenshots](#computer-use) ([ADR-0032](./docs/adr/0032-one-consent-for-titles-and-application-names.md)).
+- The **Window and application names** consent is on in Settings → Privacy. Fidget then reads app names and window titles only, never pixels, and it [never takes screenshots](#computer-use).
> [!IMPORTANT]
> **No timers.** Fidget doesn't schedule anything. It acts on the Instance Prompt when it next wakes, and the gap between unprompted wakes grows to as much as two hours, so "around 15:00" can land well after 15:00. A poke, a pickup, a Perch, or a chat wakes it at once and resets the gap. **Use a real alarm for anything you can't miss.**
From ad4bfcd1086167538fdec1609d36d1ed3d7d404a Mon Sep 17 00:00:00 2001
From: Cursor Agent
Date: Tue, 6 Oct 2026 00:56:14 +0000
Subject: [PATCH 7/7] docs: Remove timer examples from Instance Prompt section
Co-authored-by: Oded Messer
---
README.md | 5 -----
1 file changed, 5 deletions(-)
diff --git a/README.md b/README.md
index a574a35ad..b05c656de 100644
--- a/README.md
+++ b/README.md
@@ -109,13 +109,8 @@ Every example below assumes this setup:
- The Harness is allowed to use its own tools.
- The **Window and application names** consent is on in Settings → Privacy. Fidget then reads app names and window titles only, never pixels, and it [never takes screenshots](#computer-use).
-> [!IMPORTANT]
-> **No timers.** Fidget doesn't schedule anything. It acts on the Instance Prompt when it next wakes, and the gap between unprompted wakes grows to as much as two hours, so "around 15:00" can land well after 15:00. A poke, a pickup, a Perch, or a chat wakes it at once and resets the gap. **Use a real alarm for anything you can't miss.**
-
| Paste and edit | How it reacts on a wake |
|---|---|
-| `I'm deep in debugging today. If iTerm2 is still in front around mid-afternoon (say 15:00), tell me to wrap up. A technician is coming.` | Sees the time and that iTerm2 is still in front, and tells you to wrap up. |
-| `You're my screen-guard buddy. Every couple of hours, nag me to get up and stretch my legs.` | Sees the time on a wake and nags you to stretch, in its own voice. |
| `If my editor stays in front for a long stretch, ask me to explain the bug to you, like a rubber duck.` | Sees the editor in front on a wake and asks you to walk it through the bug. |
| `You're a theatre critic. When you're perched on a window, review that app in one dramatic line.` | Perch it on a window and it reviews the app it's standing on. |
| `When I ask you to check something on my machine, do it, then report back in one line, in character.` | Does the check with your Harness's tools and reports back in one line, in character. |