Cistern

Never say "drop/item/task/ticket/issue" for work units — always droplet.

Installation

• CLI: ~/go/bin/ct
• Config: ~/.cistern/cistern.yaml
• DB: ~/.cistern/cistern.db
• Log: ~/.cistern/castellarius.log
• Dashboard: http://192.168.0.138:5737 (ttyd)
• Build: cd ~/cistern && COMMIT=$(git rev-parse --short HEAD) && PATH="/usr/local/go/bin:$PATH" go build -ldflags "-X main.version=${COMMIT} -X main.commit=${COMMIT}" -o ~/go/bin/ct ./cmd/ct/

Repos configured

Worktree Rule

Never edit ~/cistern directly. That's the primary clone — touching it corrupts all agent worktrees.

All manual Cistern work goes in the primary clone at ~/cistern:

cd ~/cistern
git checkout -B lobsterdog-work origin/main   # Always sync before starting

ScaledTest worktree: ~/.cistern/sandboxes/ScaledTest/lobsterdog

⚠️ Do NOT use ~/.cistern/sandboxes/cistern/ for manual work — that entire directory is owned by the Castellarius pipeline. A lobsterdog worktree there was removed 2026-04-02; placing anything inside the sandbox root risks collision with the pipeline.

Pipeline

implement → review → qa → security-review → docs → delivery

Adding a Droplet

⛔ Always get explicit confirmation before filing any droplet.

Direct — when requirements are already clear:

ct droplet add \
  --title "Short imperative description" \
  --repo <repo-name> \
  --complexity standard \
  --description "What, why, acceptance criteria"

Filtered — for non-trivial or exploratory work:

Filtration is a thinking tool, not a filing tool. It refines ideas into clear specs — filing is always done separately with ct droplet add.

⚠️ Filtration pitfalls:

• Never set ANTHROPIC_API_KEY before running ct filter — ct filter uses claude CLI OAuth, not API key auth. Setting ANTHROPIC_API_KEY in the environment causes claude to attempt API key auth, which fails with "Invalid API key" and ct filter exits with a confusing usage-help message.
• Run ct filter from ~/cistern — it uses --allowedTools to read codebase context. Running from another directory gives the agent no context.
• Don't use --description for long text — pass the title only; provide full context in the first interactive turn instead.

Step 1 — Start (from ~/cistern, no ANTHROPIC_API_KEY exported):

cd ~/cistern
ct filter --title "Rough idea"

Step 2 — Resume with answers:

ct filter --resume <session-id> "answers and context..."

Step 3 — When spec is approved, file manually:

# File each droplet explicitly, wiring deps with --depends-on
ct droplet add --title "First droplet" --repo <repo> --complexity standard \
  --description "..."
ct droplet add --title "Second droplet" --repo <repo> --complexity standard \
  --description "..." --depends-on <first-id>

Rules:

• Never use ct droplet add --filter — fires-and-forgets, no conversation
• Never use ct filter --file — the finalize JSON step is lossy and drops depends_on; always file manually after filtration
• Minimum 3 rounds. Keep going past 3 until the spec is unambiguous — every cataracta (implement, reviewer, QA, delivery) should be able to read CONTEXT.md and have the same understanding of what needs to change, with no guessing about scope, file locations, or acceptance criteria. Stop when the spec is concrete, not when the count hits a number.
• After each round, present the updated spec as a numbered list with dependencies stated in plain text (e.g. "Droplet 2 requires droplet 1 to be delivered first")
• After each session, give a recommendation: ready to file, or needs more passes? Say why.
• Get explicit "yes" before filing any droplet
• File follow-up droplets with --depends-on <id> rather than injecting notes into flowing work

Telegram buttons during filtration

When running on Telegram (channel=telegram), use inline buttons at decision points instead of waiting for typed responses. Send buttons with:

CHAT_ID=8569372105
openclaw message send --channel telegram --target "$CHAT_ID" \
  --message "<summary of current spec>" \
  --buttons '<buttons-json>'

After each filtration round (present the numbered spec, then):

[ [{"text":"✅ Ready to file","callback_data":"filter:file"},
   {"text":"🔄 Another round","callback_data":"filter:continue"}],
  [{"text":"❌ Cancel","callback_data":"filter:cancel"}] ]

Button click responses arrive as callback_data: filter:file etc. Map them:

• filter:file → file each droplet manually with ct droplet add, wiring --depends-on explicitly; confirm each ID after filing
• filter:continue → ask what to refine, do another round
• filter:cancel → confirm cancellation, do not file

Key Commands

# Status
ct status
ct droplet list
ct droplet list --repo <repo>
ct droplet show <id>

# Manage
ct droplet restart <id>                           # Restart from current cataractae
ct droplet restart <id> --cataractae delivery     # Re-enter at a specific cataractae
ct droplet pool <id>
ct droplet cancel <id> --reason "..."
ct droplet note <id> "..."
ct droplet deps <id> --add <dep-id>

# Daemon
ct castellarius start/status
journalctl --user -u cistern-castellarius -f
systemctl --user restart cistern-castellarius

# Cataractae
ct cataractae list
ct cataractae generate

# Dashboard (reload after rebuild)
kill $(ss -tlnp | grep 5737 | grep -o 'pid=[0-9]*' | cut -d= -f2) 2>/dev/null
systemctl --user start cistern-ttyd.service

Infrastructure

• Castellarius: systemd user service cistern-castellarius.service (Restart=always)
• Auth: Claude CLI manages its own credentials via ~/.claude/.credentials.json — no ANTHROPIC_API_KEY env var needed in service
• start-castellarius.sh just runs exec ct castellarius start — no credential setup
• ttyd dashboard: port 5737, managed by cistern-ttyd.service
• Self-restart: git_sync drought hook + binary mtime detection → os.Exit(0) → systemd restarts

Troubleshooting

Run ct doctor first — it checks daemon status, claude CLI auth, and common config issues automatically.