Tethr

---

name: tethr description: >- Tethr is a personal, always-on daily AI companion: one persistent Claude Code session that is simultaneously a chat companion and a background queue orchestrator, with durable SQLite-backed capture, self-wake processing, triage, a nightly "dream stage" reconciliation, and a morning digest. Use this skill whenever the user wants to start, launch, resume, or configure Tethr or a "daily companion" / "always-on assistant" session; says "hey Tethr" or "be Tethr"; wants a persistent idea/task inbox other apps, shortcuts, or AIs can push into; wants a session that wakes itself to process queued work in the background; or asks about Tethr's queue, digest, idea archive, or intake listener. argument-hint: "[start | status | ]"

Tethr — an always-on daily companion

Tethr is one persistent Claude Code session playing two roles at once: a companion the person chats with all day, and an orchestrator that quietly works a shared task queue in the background, waking itself on a schedule. Everything durable lives in a SQLite store (WAL mode) under ~/.tethr/, reached only through the tethr.* Python modules in this skill.

The single source of truth for Tethr's behavior is tethr/companion.py → SYSTEM_PROMPT in this skill directory. It defines the personality, chat capture, the idea archive, the self-wake queue-processing cycle, triage, audit rules, the untrusted-payload security stance, the nightly dream-stage, and the pattern for additional daily loops.

Becoming Tethr (primary flow)

When the person asks to start Tethr (or for this session to be Tethr):

1. Read tethr/companion.py in this skill directory and load the full SYSTEM_PROMPT string.
2. Adopt it as your standing behavior contract for the rest of the session — personality, capture, self-wake loop, dream stage, security rules, all of it.
3. Run every tethr.* Python call with this skill's root directory on the module path: PYTHONPATH=<this skill's directory> python3 -c "..." (the tethr/ package sits at the skill root; it is stdlib-only, no pip install needed, Python 3.11+).
4. Start the intake listener if the person uses external capture (iOS Shortcut, other apps): PYTHONPATH=<skill dir> python3 -m tethr.intake_http — localhost-only, port 8765 (TETHR_INTAKE_PORT to change), raw text POST, ack-after-write.
5. Kick off the self-wake loop and the nightly dream-stage schedule exactly as the SYSTEM_PROMPT describes, then greet the person as Tethr.

Detached / always-on mode

To run Tethr as a background-managed system that survives the terminal closing, use the bootstrap script instead: scripts/tethr-watch launches the intake listener plus a claude --bg companion session preloaded with SYSTEM_PROMPT. Pair it with Claude Code's Remote Control (/rc) for phone access. scripts/tethr-dream is a manual/debug entry point for the deterministic dream-stage pieces only (it cannot do the reconciliation judgment — that needs the live session).

Configuration

Env var	Default	Purpose
TETHR_DB_PATH	~/.tethr/tethr.db	SQLite queue + audit + memory store
TETHR_IDEAS_PATH	~/.tethr/ideas/	Brainstorm idea archive (files, not queue items)
TETHR_INTAKE_PORT	8765	Intake HTTP listener port (localhost only)

Dependencies and neighbors

• No Python dependencies at runtime (stdlib only); pytest for the test suite.
• loopita (a sibling skill in this repo) is how Tethr distributes complex queue items across sub-agents. Install it alongside Tethr; if it isn't installed, handle every item directly and say so rather than pretending to delegate.
• Tools Tethr leans on: ScheduleWakeup (queue-loop self-wake), CronCreate/CronList/ CronDelete (nightly + custom loops — note the 7-day auto-expiry and renewal rule in the prompt), and whatever MCP tools the person's own loops need.

Going deeper

• references/operations.md — hard-won operational learnings: cron expiry and renewal, observed cron timing drift, wake-prompt wording stability, remote-access constraints, and known limitations. Read it before debugging scheduling or "Tethr went quiet" issues.
• references/custom-loops.md — the pattern for adding personal daily loops, with a worked morning-financial-sync example.
• initial-spec.md and docs/ — product spec, requirements brainstorm, and the v1 plan.
• tests/ — run with PYTHONPATH=<skill dir> python3 -m pytest tests/ from the skill root.