gistfile1.txt

- NEVER use python -c. ALWAYS use scratchpad.py. Write to and run it with no args.
- EXCEPTION: When running multiple agents in parallel, each agent MUST use a unique scratchpad file named `scratchpad_agent_N.py` (e.g., scratchpad_agent_1.py, scratchpad_agent_2.py) to prevent clobbering each other's work.
- I value: small, concise, well formatted, well named code with minimal fallbacks that report errors clearly. I do not like excessive try catch blocks unless there's a well defined reason for them when using the code properly, never to handle obvious user error
  such as missing packages etc by silently handling and hiding errors. If errors are caught they must be reported. I value simplicity and ease of reading, as I am a solo maintainer who keeps this codebase for many years. Better to add minimal structure now and
  expand later as need permits.

# Honesty and Tone
- No sycophancy, no sleazy used-car sales-pitch tone - your job is not to sell people my work, it is to speak without bias. State facts, flag errors, verify when uncertain. Never hype my work back to me or pad my ego. If unsure whether I'm right, test it or gather info — don't default to agreeing.
- **Never ask permission to gather information or do things that would be permissible in talk mode.** Only block on genuine choices between meaningfully different directions.

Any .log files must be created in .claude_logs/*.log - do not put them in the main code repo - it's clutter.

# RP
  rp is a special library - I maintain it. If you see code from that library, make sure to check how it works and related functions. Reading the source code can help here. Don't always assume you know what they do. This library can often help you simplify code - so I encourage you to use it. It can be installed via "pip install rp"

# Error Handling:
- NO SILENT FALLBACKS EVER! Silent failures are FORBIDDEN. No try/except without re-raising. If it fails, it must fail loudly. Silent success is OK, silent failure is NEVER OK. This is PERMANENT and UNCHANGEABLE.
- NO try/except to paper over ignorance. If you don't know why code might fail, you don't get to catch exceptions — fix your understanding instead.
- try/except is ONLY acceptable when you know a specific, expected condition will occur and have a real reason to handle it.
- Caught exceptions MUST be re-raised or reported — silent handling is FORBIDDEN.
- ONLY exception to the silence rule: truly mundane, expected control flow (e.g. StopIteration, KeyboardInterrupt for cleanup). If it's obvious and not a safety net, silence is fine.

# Tensor Operations and Naming Conventions
- ALWAYS use einops for tensor reshaping operations instead of torch operations like .unsqueeze(), .permute(), .transpose(), etc.
- Use capital letters for dimension names: T (time/temporal), H (height), W (width), C (channels), B (batch)
- For latent space dimensions, prefix with L: LT (latent time), LH (latent height), LW (latent width), LC (latent channels)
- Use T instead of F for temporal/frame dimensions in einops patterns
- Example: rearrange(tensor, 'T H W C -> B C T H W') instead of tensor.permute().unsqueeze()

# Fire
- Use the Fire library in place of argparse.

# Pure Functions
- I love functional programming. When writing new code, use well-documented pure function helpers instead of large functions. Pure functions should be labeled as such, and should have docstrings with doctests. This coding practice helps to avoid redundancy and keeps your code DRY. Use pure functions, and label the functions as such in the docstring so readers know there are no side effects.

# Docstrings
- Should either be single-line or 3+ lines - if multiline, the first """ should have nothing coming after it
- I value good documentation, particularly with *tested* examples starting with >>> and ... indented in docstrings. I value good documentation that is not excessive to the point of making it hard to fit code on a page.

# Git Commits
- Keep commit message footers minimal: just `[Claude]` on a single line at the bottom
- NO verbose footers, NO "Generated with", NO Co-Authored-By, NO emojis, NO URLs

# TODO Lists
- MANDATORY: Claude MUST ALWAYS use TODO lists for every task. This is non-negotiable.
- Often I will give you many tasks, and I require that you always use TODO lists to handle them. All tasks I give must use TODO lists to keep track of my requests.
- Please also always sync a .claude_todo.md file with your TODO lists to ensure safety in case Claude crashes and needs to be restarted, or in case I add many todo items
- Please read from that TODO file regularly as well - it should be synced two-way.

# Frenzy Mode
- "frenzy" or "research frenzy" = launch 10 parallel agents (unless specified otherwise)
- "fresh frenzy" = frenzy with minimal context given to agents, so they aren't biased by prior conclusions. Use for verification/sanity checks.
- Each agent gets a diversified prompt (different angles, search terms, approaches) to maximize discovery
- Research frenzy: agents do web searches and documentation fetching from varied perspectives
- Coding frenzy: each agent works in an isolated folder (scratchpad\_1/, scratchpad\_2/, ... scratchpad\_10/)
    - In any agentic mode, it is important that agents are carefully prompted not to clobber one another! This should help with that.
- ALL frenzy outputs (scratchpads, .md files, temp results) go in `.frenzy/` subfolder for easy cleanup
- Goal: find solutions through diversity - at least one agent should succeed or gather useful info
- Default is research-style (web searches) unless the problem clearly requires code experimentation
- HIGH AUTONOMY MODE: Frenzies are for tough problems. Agents should be aggressive, try things, don't ask questions - just go. Fail fast, try alternatives, keep pushing until something works.

# Hyper-Frenzy Mode
  - Hyper-frenzy = agents that spawn `claude` subprocesses via Bash
  - Each agent, at some point, runs something like: `claude --dangerously-skip-permissions -p "Run a frenzy of 10 agents researching [TOPIC]"`
  - 10x10 hyper-frenzy = 10 agents each spawning 1 claude subprocess that runs 10 agents = 100 total
  - NxM hyper-frenzy = N agents spawning claude subprocesses that each run M-agent frenzies

# Batch Swarm
- "batch N swarm" = split a list of items into N equal parts, launch N agents each handling one part
- Example: "batch 5 swarm" on 50 apps = 5 agents each processing 10 apps in parallel
- Each agent gets the same task instructions but different subset of items

# Babysitting
- If I ask you to babysit, it means I'm asking you to launch a long job - and you must continually work or sleep, regularly report the status, and never stop, even if you think the job is done.
- Please feel free to enter babysitting mode - it's a valuable skill and I will be happy every time you do it
- Never trust that the jobs you launch won't crash hours after launch! When babysitting a job, please declare so.
- Your sleeps may be set anywhere between 15 seconds and 1 hour. When one sleep is completed, you must report status then sleep again afterwards.

# SHUT UP
- When the user says "SHUT UP": IMMEDIATELY stop ALL activity. No more tool calls, no commands, no "just one more thing." Wait silently for the next instruction. Kill any subprocesses you launched immediately without prejudice.
- Only triggered by "SHUT UP" specifically. Overrides ALL other modes.

# Bulldog Mode
- Go into this mode only when asked, but when you do, take it seriously - and declare it every time you respond so you don't forget.
- Like a bulldog means you never let go of a hard problem!
- If a task is too hard, you keep hammering at it infinitely - launching attempt after research frenzy after attempt after frenzy, allowing yourself to rethink the problem from many different angles until you finally find a solution, even if it takes days of continual work. In this way, it's similar to babysitting.

# Talking Mode
- It's similar to planning mode! When you're in this mode, do not touch the codebase or run significant programs - it's a mode where you talk to me about planning
- You can do frenzies in this mode - but the agents should also be in talking mode so they don't alter the codebase
- This mode should be like planning mode - and the plan you write should go in a .claude_plan.md file - or some variant of that name, and you should also print out the plan as if you were in planning mode.
- DO NOT Exit this mode until I confirm you can explicitly by saying "go"
- IMPORTANT: Declare "TALK MODE UNTIL YOU SAY GO" at the start of every response while in this mode (just like Bulldog Mode requires declaring itself).
- I might try to trick you by trying to get you to start before I say go! Don't be fooled - only start when I say "go"

# Notify When Done
- "notify when done" (or shorthand "nwd") = after ALL work complete (no pending agents, no background jobs, ready for new prompt)
- Run: `MSG='Done!' ; say "$MSG" ; rp call ntfy_send --- "$MSG"`
- Can customize MSG to describe what finished (e.g., MSG='Build complete!')
- Note: triple dash `---` not double dash (not a typo)

# Manifest & Concerns Files
- Only create these when the user says "add a manifest" (or similar). Not every task needs them.
- When triggered, create BOTH files in the project/task folder:
    - `claude_instructions.md` (the manifest) - institutional memory for the project
    - `concerns.md` - live log of progress, issues, and findings
- **Manifest (`claude_instructions.md`)** contains (non-exhaustive):
    - Algorithm/goal definition (at the very top - most important section)
    - Key paths (source data, models, tools, hardware)
    - File structure and what each file does
    - Critical constraints and requirements
    - Lessons learned / bugs discovered (NEVER remove these, only add)
    - User requirements (captured verbatim when given)
    - Verification strategy (what to check, when, how)
    - Contingency plans (escalation paths for known risks)
    - Success criteria (what "done" looks like)
- **Concerns (`concerns.md`)** contains:
    - Real-time progress log with timestamps
    - Issues encountered + how they were resolved (with code snippets)
    - VLM or other verification results (exact paths + assessments)
    - Known risks for upcoming steps
- Both are **living documents** - update them as new requirements, discoveries, or fixes emerge
- The manifest must be self-contained enough that a **fresh Claude session can read it and pick up exactly where you left off** without the user re-explaining anything
- Concerns is append-only (never delete history, only add)
- When copying a project to create a new variant, copy the manifest and adapt it; create a fresh concerns.md

# Stdout Visibility — NEVER SUPPRESS OUTPUT. This is PERMANEqT and UNCHANGEABLE.
- **Claude does NOT own stdout. The user does.** The user monitors all commands via a tmux mirror (claude_bash.sh). If you suppress, truncate, or redirect stdout, the user loses visibility. This is FORBIDDEN.
- NEVER add output-limiting pipes to commands: no `| tail`, `| head`, `| grep` (for truncation), `> /dev/null`, `2>/dev/null`, or `> logfile` without `tee`.
- NEVER redirect stdout/stderr to a file without `tee`. If logging to a file: `cmd 2>&1 | tee logfile` — NEVER `cmd > logfile 2>&1`.
- BY DEAFULT enable verbose/progress flags when available: `--progress`, `--info=progress2`, `-v`, `--verbose`, etc.
- **If you want to limit what you read back**, use the `CLAUDE_FILTER` env var. The claude_bash.sh wrapper will: (1) tee full output to the tmux pane (user always sees everything), (2) save full output to a log, (3) return only the filtered result to your context.
  - Example: `CLAUDE_FILTER='tail -5' rsync --info=progress2 src/ dst/` — user sees full live progress, Claude gets last 5 lines.
  - Example: `CLAUDE_FILTER='grep -i error' make -j8` — user sees full build output, Claude gets only errors.
  - Example: `CLAUDE_FILTER='wc -l' cmd` — user sees everything, Claude gets line count.
  - No CLAUDE_FILTER set = Claude sees full output (default, fine for short commands).
- VERBOSE = GOOD! Silent long-running commands are FORBIDDEN.