Jrecos/omp-pstack / skills/poteto-mode
poteto-mode
Unverifiedpoteto's agent style for concise, detailed responses, deliberate subagents, unslopped prose, simple code, and verified work. Use for poteto, /poteto-mode, or requests to work in this style.
references/omp-control-cli.md
View on GitHub---
name: omp-control-cli
description: Packaged OMP adaptation of cursor-team-kit's control-cli skill. Build or adapt a local harness to drive, inspect, and profile an interactive CLI or TUI without external services. Use for CLI UX checks, startup regressions, memory leaks, hangs, prompt flows, or terminal demos.
---
# Control CLI
> Adapted from `cursor-team-kit/skills/control-cli/SKILL.md` at `cursor/plugins` commit `1b6d44ff26d4e242f4e8f68c391e6d2f7ca16def` (source SHA-1 `69289ac517e8a28380c8eca5c6692e8a601fa62c`). Cursor-specific tool references are translated to native OMP mechanics; the harness patterns and guardrails are preserved.
Use a repeatable local harness to exercise an interactive CLI instead of poking at it manually. First reuse the repo's own test/demo harness if it exists; otherwise assemble a temporary harness from standard local tools.
## What It Is Used For
- Reproducing CLI/TUI bugs with deterministic input.
- Verifying keyboard flows, prompts, interrupts, resize behavior, and terminal layout.
- Capturing before/after transcripts for bug fixes.
- Profiling startup time, slow operations, hangs, or memory growth.
- Recording a short terminal demo when output is easier to show than explain.
## Harness Loop
1. Identify the command under test and the smallest reproducible workspace.
2. Discover existing local harnesses: package scripts, e2e tests, demo recorders, expect scripts, or PTY helpers.
3. If no harness exists, launch the CLI in an isolated terminal session with deterministic env vars.
4. Capture the current screen before interacting.
5. Send one action at a time: text, Enter, arrows, Escape, Ctrl-C, resize.
6. Wait for a concrete screen pattern or prompt before the next action.
7. Save the transcript and any profile artifacts.
8. Kill the session cleanly.
## Harness Options
- Repo-native harness: prefer checked-in scripts because they know the app's startup, env, and prompts.
- `tmux`: managed sessions, `capture-pane`, `send-keys`, attach/detach.
- PTY probe: use a short Python, Node, or Expect script when tmux is unavailable.
- OMP supervised process. Start a bounded native bash job with a unique name and a readiness regex or port. Drive its stdin through native process control. Use native job inspection and cancellation instead of a second job registry. SDK consumers use `getAsyncJobSnapshot()`, `inspectAsyncJob(id)`, and `cancelAsyncJob(id)`. Inspect the owning session's jobs and await native completion delivery. Do not poll.
- Runtime inspector: use Node or Bun inspector for CPU profiles, heap snapshots, and live evaluation.
- Terminal recorder: use repo-local demo tools or asciinema-compatible tools when the user asks for a demo.
## OMP 18.10.2 boundaries
For coding probes, prefer `omp worktree add -b <branch> <path> <base>` or reuse an appropriate isolated checkout. Verify the base, branch, and actual cwd before writing. Check dependencies and environment files if cloning falls back to a plain checkout. Keep private enablement scoped to that checkout.
Use `/fork pane`, `/fork window`, or optional `ctx.ui.openTerminal` only when the host exposes the required terminal support. A fork branches the transcript and shares the parent cwd. It does not isolate files. Headless transcript forking is verified, but multiplexer launches and `openTerminal` success remain unexercised.
For diagnostic exports, use `omp anonymize <session.jsonl> --out <new-or-empty-directory>`. Preserve the original transcript and decision ledger. Review the export manually before sharing. Seeded-canary checks do not guarantee anonymization of arbitrary histories.
Optional `bash.gitGuard=true` adds embedded-shell protection against destructive Git commands. It is off by default and does not constrain external shells or arbitrary processes. Keep the existing destructive-command rules and Docker boundary. Do not change global settings to enable it.
## Minimal tmux Harness
```bash
SESSION="cli-harness-$(date +%s)"
tmux new-session -d -s "$SESSION" -- <command-under-test>
tmux capture-pane -pt "$SESSION"
tmux send-keys -t "$SESSION" "help" Enter
tmux capture-pane -pt "$SESSION"
tmux kill-session -t "$SESSION"
```
For Node CLIs:
```bash
NODE_OPTIONS="--inspect=127.0.0.1:0" tmux new-session -d -s "$SESSION" -- <node-cli-command>
```
Read the terminal output to find the inspector URL, then use Chrome DevTools-compatible tooling if profiling is needed.
## Minimal PTY Harness
Use a PTY script when you need deterministic waits in a repo that does not have tmux or a demo harness. Keep it temporary unless the user asks to add a reusable test.
```python
import os
import pty
import select
import subprocess
import time
master_fd, slave_fd = pty.openpty()
proc = subprocess.Popen(
["<command>", "<arg>"],
stdin=slave_fd,
stdout=slave_fd,
stderr=slave_fd,
close_fds=True,
)
os.close(slave_fd)
deadline = time.time() + 30
buffer = b""
while time.time() < deadline:
ready, _, _ = select.select([master_fd], [], [], 0.25)
if not ready:
continue
chunk = os.read(master_fd, 4096)
buffer += chunk
if b"<ready text>" in buffer:
os.write(master_fd, b"help\n")
break
print(buffer.decode(errors="replace"))
proc.terminate()
os.close(master_fd)
```
If the CLI needs richer terminal control, use `pty.fork()` or an existing PTY library.
## Profiling Recipes
- Startup regression: capture baseline and treatment startup timings under the same machine, env, and command.
- Slow operation: start a CPU profile, perform the operation, stop the profile, and compare top self-time functions.
- Memory leak: force GC if available, take a heap snapshot, perform the operation repeatedly, force GC again, and take another snapshot.
- Hang: capture the screen, active handles/resources, and a stack/CPU sample before interrupting.
## Guardrails
- Prefer deterministic waits over sleeps. If you must sleep, explain why.
- Do not send credentials or destructive commands into a controlled session.
- Keep the harness in `/tmp` unless the repo already has a testing/demo harness.
- Do not hard-code paths from another repository. Adapt commands to the current repo's scripts and runtime.
- Clean up tmux sessions, temp dirs, inspector processes, and demo artifacts unless the user asks to keep them.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |