Skip to content

👾 Open Computer Use – Open-Source Alternative to Codex Computer Use

docs(skill): document full-text snapshot usage

tisfeng9f1e550cb2ea
diff --git a/docs/histories/2026-06/20260605-1640-unify-snapshot-text-limit.md b/docs/histories/2026-06/20260605-1640-unify-snapshot-text-limit.md
index 85ddb2d..fd98f27 100644
--- a/docs/histories/2026-06/20260605-1640-unify-snapshot-text-limit.md
+++ b/docs/histories/2026-06/20260605-1640-unify-snapshot-text-limit.md
@@ -25,3 +25,17 @@ Default truncation protects snapshot size and preserves upstream-compatible beha
- `packages/OpenComputerUseKit/Sources/OpenComputerUseKit/OpenComputerUseCLI.swift`
- `apps/OpenComputerUseLinux/runtime.py`
- `apps/OpenComputerUseWindows/runtime.ps1`
+
+### Follow-up 2026-06-18
+
+**Scope:** Agent-facing Open Computer Use skill docs.
+
+**Key Actions:**
+- Documented when agents should request full text with `show_full_text: true`.
+- Added CLI examples for `get_app_state` full-text mode and `snapshot --show-full-text`.
+- Added troubleshooting guidance for visible text ending in `...`, clarifying that full-text mode only removes the text character limit and does not relax other snapshot protections.
+
+**Files Modified:**
+- `skills/open-computer-use/SKILL.md`
+- `skills/open-computer-use/references/usage.md`
+- `skills/open-computer-use/references/troubleshooting.md`
diff --git a/skills/open-computer-use/SKILL.md b/skills/open-computer-use/SKILL.md
index d3929de..fcf7860 100644
--- a/skills/open-computer-use/SKILL.md
+++ b/skills/open-computer-use/SKILL.md
@@ -18,11 +18,12 @@ It supports the same core tool surface across macOS, Linux, and Windows:
1. Check the CLI is installed with `open-computer-use -h`. If installation or setup is missing, read [references/installation.md](references/installation.md).
2. On macOS, run `open-computer-use doctor` before the first real GUI task. If permissions are missing, ask the user to approve Accessibility and Screen Recording in the onboarding UI.
3. Inspect available apps before acting: `open-computer-use call list_apps`.
-4. Capture current UI state with `open-computer-use call get_app_state --args '{"app":"TextEdit"}'`.
-5. Prefer element-targeted actions using `element_index` from the latest `get_app_state` result.
-6. For multi-step CLI work, use `open-computer-use call --calls '<json-array>'` so one process can reuse the latest element index mapping.
-7. For agent runtimes that support local MCP servers, configure `open-computer-use mcp` and call the exposed Computer Use tools directly. Read [references/usage.md](references/usage.md).
-8. If communication, permission, or desktop-session access fails, read [references/troubleshooting.md](references/troubleshooting.md).
+4. Capture current UI state with `open-computer-use call get_app_state --args '{"app":"TextEdit"}'`. The default state is usually enough for UI operation.
+5. When the task needs complete long text, such as chat history, email bodies, document text, or long form content, call `get_app_state` with `show_full_text: true`.
+6. Prefer element-targeted actions using `element_index` from the latest `get_app_state` result.
+7. For multi-step CLI work, use `open-computer-use call --calls '<json-array>'` so one process can reuse the latest element index mapping.
+8. For agent runtimes that support local MCP servers, configure `open-computer-use mcp` and call the exposed Computer Use tools directly. Read [references/usage.md](references/usage.md).
+9. If communication, permission, or desktop-session access fails, read [references/troubleshooting.md](references/troubleshooting.md).
## Operating Rules
@@ -41,6 +42,7 @@ open-computer-use -h
open-computer-use doctor
open-computer-use call list_apps
open-computer-use call get_app_state --args '{"app":"TextEdit"}'
+open-computer-use call get_app_state --args '{"app":"TextEdit","show_full_text":true}'
open-computer-use call click --args '{"app":"TextEdit","element_index":"0"}'
open-computer-use call type_text --args '{"app":"TextEdit","text":"Hello from Open Computer Use"}'
```
diff --git a/skills/open-computer-use/references/troubleshooting.md b/skills/open-computer-use/references/troubleshooting.md
index 9628359..0d079d1 100644
--- a/skills/open-computer-use/references/troubleshooting.md
+++ b/skills/open-computer-use/references/troubleshooting.md
@@ -37,6 +37,19 @@ Common causes:
Ask the user to bring the target app/window into a visible state when automation cannot do so safely.
+## Truncated Text
+
+Snapshot text is limited to 500 characters by default. If a visible chat message, email body, document paragraph, or form value ends with `...`, do not assume the page itself is missing content.
+
+Request full accessibility text explicitly:
+
+```sh
+open-computer-use call get_app_state --args '{"app":"TextEdit","show_full_text":true}'
+open-computer-use snapshot --show-full-text TextEdit
+```
+
+`show_full_text` only disables the text character limit. It does not remove node count, tree depth, screenshot size, permission, or desktop-session protections.
+
## Element Action Fails
If an element-targeted action fails:
diff --git a/skills/open-computer-use/references/usage.md b/skills/open-computer-use/references/usage.md
index 897b318..c7b8d39 100644
--- a/skills/open-computer-use/references/usage.md
+++ b/skills/open-computer-use/references/usage.md
@@ -65,6 +65,21 @@ Use `--calls-file` when the sequence is too large for a readable shell command:
open-computer-use call --calls-file examples/textedit-overlay-seq.json --sleep 0.5
```
+## Full Text Snapshots
+
+Snapshot text is truncated to 500 characters by default and ends with `...` when truncation happens. This keeps normal UI state compact for agent planning and element-targeted actions.
+
+Use full-text mode when the task depends on complete semantic text, such as chat histories, email bodies, document text, or long form content:
+
+```sh
+open-computer-use call get_app_state --args '{"app":"TextEdit","show_full_text":true}'
+open-computer-use snapshot --show-full-text TextEdit
+```
+
+The same `show_full_text` tool argument and `--show-full-text` snapshot flag apply on macOS, Linux, and Windows.
+
+Action tools return refreshed app state with the default 500 character text limit. If full text is still needed after an action, run `get_app_state` again with `show_full_text: true`.
+
## Choosing Targets
- Prefer app names or bundle identifiers returned by `list_apps`.