turtle
Read and propose Turtle project-bucket context - local resources, external services, handoffs, and restore plans - through the `turtle` CLI. Use when asked what a project contains, where its external services live, what the handoff says, or to record a folder, URL, external resource, or handoff into a project bucket. Also use before starting work on a project that has a Turtle bucket, to recover context instead of reconstructing it.
- License 许可
- Apache-2.0
- 所属仓库
- op-q/turtle
- 最近更新
- 2026-07-29
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- turtle
- description
- Read and propose Turtle project-bucket context - local resources, external services, handoffs, and restore plans - through the `turtle` CLI. Use when asked what a project contains, where its external services live, what the handoff says, or to record a folder, URL, external resource, or handoff into a project bucket. Also use before starting work on a project that has a Turtle bucket, to recover context instead of reconstructing it.
03 SKILL.md 正文
Turtle project buckets
Turtle keeps everything needed to understand and resume a project — local resources, external service references, working state, and safe context — in one private local bucket.
You can read any bucket and propose additions. You can never write one.
Before anything else: is the runtime up?
The CLI is a thin client over a Unix socket. Nothing works without the runtime.
turtle project list
runtime_unavailable→ nothing is running. Ask the user to start eitherturtle app(desktop companion plus the runtime) orturtle serve(headless). Do not start it yourself — it is the sole writer, and a second one would fight the first for the socket.- In this repository, use
./scripts/turtleinstead ofturtle.
turtle app and turtle serve are mutually exclusive; turtle app already serves the socket, so
every command below works the same either way.
XDG_RUNTIME_DIR must be set. Turtle deliberately has no /tmp fallback.
The one rule that matters
Proposals are yours. Decisions are the user's.
Every write goes through a CaptureProposal that a human must approve. turtle capture accept
requires an interactive terminal and the user typing the exact proposal ID. Piped or scripted
stdin is refused with confirmation_required and exit code 2.
This is not a limitation to work around. Never attempt to accept a proposal on the user's behalf, never write bucket files directly, and never edit anything under the Turtle data root. Propose, then show the user the proposal ID and let them accept.
Reading context
Start here when you need to understand a project:
turtle context show # full bucket as Markdown
turtle context show --format json # same content, structured
turtle context show --project <id-or-name> # a project other than the selected one
context show returns everything at once: handoff, local resources, external resources, agents.
Prefer it over assembling the narrower commands.
Narrower reads:
turtle handoff show # Current state / Next / Important
turtle external list # id, provider, kind, label, url
turtle agents list # id, kind, label, cwd, resume hint
turtle restore plan # side-effect-free; prints actions, opens nothing
turtle project list # `*` marks the selected project
turtle capture show <proposal-id> # exactly what a pending proposal would store
turtle status # is the runtime up, and what is installed
restore plan never opens or launches anything. It is safe to run.
turtle status is the exception to the rule above: it is the one command that works with no
runtime listening, so it is what to run when everything else answers runtime_unavailable.
Three things only the user may do
These change the user's machine directly and none of them goes through the proposal queue. Print the command and let the user run it.
turtle here # this folder becomes a selected, scanned project
turtle project add-root /abs/path # widens what Turtle is allowed to scan
turtle restore run # actually opens folders, files, and URLs
turtle here is the fastest setup path — it selects or creates the project for a folder, approves
that folder, and scans it in one step — but it both creates a project and widens the scan scope, so
it is the user's call. Suggest it when a project has no bucket yet.
project add-root is the only way to approve a further folder for an existing project, and
approving a root is what lets the collectors read it. Widening that scope is the user's call, not
yours.
restore run opens real windows on the user's desktop. Run it only when the user has asked for a
restore in that turn. It reports opened and failed per resource, never stops at the first
failure, and never closes anything. --only <resource-id> restores a single resource; get IDs
from turtle restore plan.
Letting Turtle find things for itself
turtle inspect # scan approved roots, queue what is new
turtle inspect --format json # queued / skipped / failures
The bundled collectors read the approved roots and propose a git remote as an external resource,
the repository root, README and manifests as local resources, and .env.example variable names
only. Everything they find is marked detected, never confirmed, and lands in the same review
queue as a manual proposal — detection never stores anything.
One more collector reads outside the roots, by design: it looks at the local Codex CLI's own session headers and proposes an agent reference for any session whose working directory is inside an approved root. It reads the first line of a rollout file and nothing else, so no conversation content is ever read, and it degrades to a reported failure if Codex changes that format.
Findings that already match a stored record come back under skipped with reason
already_stored, one the user dismissed comes back as dismissed and is never re-offered, and a
finding still awaiting a decision is simply listed again — so running it repeatedly is safe and
idempotent. The desktop window scans a project by itself whenever it is opened, so a finding you
see there may already be waiting without anyone having run inspect. Prefer turtle inspect over
hand-writing proposals for anything a collector can find; it produces better provenance
(collector:git@1) and real evidence.
Proposing
All proposal commands print a proposal ID and exit without changing the bucket.
turtle capture folder --label "Repo" --path /abs/path/inside/an/approved/root
turtle capture documentation --label "Plan" --url https://example.com/plan
turtle capture url --label "Board" --url https://example.com/board
turtle handoff propose --current-state "..." --next "..." --important "..."
turtle agents propose \
--kind codex --session-id <id> --label "..." --cwd /abs/path \
[--branch main] [--resume-hint "codex resume <id>"]
turtle external propose \
--provider <anything> --kind <anything> --label "..." \
[--url ...] [--environment production] \
[--identifier KEY=VALUE]... [--config-path rel/path]... [--tag t]... [--notes "..."]
Add --format json to any of them to get the proposal ID and the exact record programmatically.
Provider and kind are free-form — use the real name
--provider and --kind are plain data, not enums. An internal or obscure service is a
first-class citizen and needs no new code. Write what the thing actually is
(--provider unfamiliar-service --kind widget-forge), never a forced fit into a familiar vendor.
Confidence must be honest
--confidence confirmed|detected|suggested (default confirmed).
Use confirmed only for something the user stated or you read directly from a file. Use
detected when you inferred it from evidence, suggested when you are guessing. Never
fabricate an identifier, URL, or account reference — omit the flag instead. A wrong identifier
in a bucket is worse than a missing one, because the user will trust it later.
What Turtle will refuse
These are enforced server-side and rejecting them is correct behavior, not a bug to route around:
| Attempt | Error |
|---|---|
| Any credential, token, key, or password in any field | secret_rejected, with the exact JSON path |
| A path outside the project's approved roots | invalid_value |
| An unknown resource kind | rejected — window, url, folder, file, terminal_cwd, documentation only |
Never try to store an API key, token, connection string with a password, cookie, .env value, or
provider auth file. Store the reference — the dashboard URL, the non-secret project ref, the
path to the config file — never the secret itself. Do not read .env values; .env.example
variable names are acceptable.
Batching gotcha
Accepting one proposal invalidates every other pending proposal of the same record type
(resource, external, agent, handoff) because the target digest changes. They auto-refresh, and the
user re-accepts the same ID on a second pass — but if you queue five external resources at once,
warn the user that approval takes more than one round. Proposing one at a time is friendlier.
Not available yet
Do not suggest these; they appear in the plan but are not implemented:
turtle external open— no CLI command opens an external resource (the desktop UI can open one, the CLI cannot)turtle capture propose --json -andhandoff propose --stdin— no stdin proposal path--source agent:claude— the CLI records every manual proposal asmanual; agent provenance is not yet distinguishable in the bucket- Window and browser-tab capture — nothing captures or restores a native window or a Firefox tab
yet;
restore runopens folders, files, and URLs only, and reports every other stored kind asunsupported
If the user asks for one of these, say plainly that it is not built yet rather than improvising a substitute.
The desktop UI
turtle app runs the persistent turtle shell plus the runtime in one process. Clicking the turtle
(or Ctrl+Super+T, once scripts/install-shortcut.sh has been run) opens the window, where the
user can create a project (N), approve a folder (F), run detect (D), write the handoff
(H), accept or dismiss each finding (A / X), and resume the project (R). Any single local
resource opens with Enter, and an agent row copies its resume command. The interface is dark
throughout; ~/.config/turtle/style.css overrides any token.
turtle show raises that window from the command line. It only works while turtle app is
running, and it is what the global shortcut invokes.
You can run turtle show, but never launch turtle app yourself — it is a long-lived graphical
process the user owns.