agentleFS
Konadu-Akwasi-AkuokoKonadu-Akwasi-Akuoko/katto/CLAUDE.md

katto

CLAUDE.md2 starsChanged 5 months agoMITView on GitHub

Personal, macOS-only, menu-bar-resident Tauri 2 app running the owner's entire YouTube production workflow: planning → SD ingest → AI rough cut → NLE export → assets → thumbnails, with every AI task visible in a Claude session dock. One user, one Mac. Not a public product. - prd/ is the in-repo source of truth. Start at prd/index.md (doc map, feature→phase matrix, status). Each prd/phase-N.md is a complete PRD — implement a phase from its PRD without re-deriving decisions. Locked decisions…

The file

We split this CLAUDE.md into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    prd/ is the in-repo source of truth: Start at prd/index.md (doc map, feature→phase matrix, status).

    line 9
  2. Distinctive:

    No numeric scoring/ranking anywhere in planning or curation — AI suggests, human decides.

    line 59

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

katto — Studio OS

Personal, macOS-only, menu-bar-resident Tauri 2 app running the owner's entire YouTube production workflow: planning → SD ingest → AI rough cut → NLE export → assets → thumbnails, with every AI task visible in a Claude session dock. One user, one Mac. Not a public product.

Source of truth

  • prd/ is the in-repo source of truth. Start at prd/index.md (doc map, feature→phase matrix, status). Each prd/phase-N.md is a complete PRD — implement a phase from its PRD without re-deriving decisions. Locked decisions + rationale: prd/README.md.
  • The original design specs live in docs/superpowers/, mostly gitignored (local-only, private) — don't reference the private ones as if committed; the PRDs distill everything needed from them. The one committed exception is docs/superpowers/specs/2026-07-03-katto-design-system.md (the approved design-system spec, referenced by .claude/rules/design-system.md). Same local-only rule for root agents/ (cut-decider prompt) and skills/ (clean-audio reference pipeline): local-only inputs, ported into the repo when their phase implements them.
  • hyper-frames/ is a read-only reference mirror of the owner's skills/agents/tools repo. Where a katto module overlaps it (studio DB schema, promote flow, cut-video ffmpeg math, audio-editor UX, curation judgment), read the mirror first and reuse its schemas verbatim.

Workspace

  • crates/katto-engine — pure Rust library (media pipeline, validators, emitters). Never depends on tauri or UI concerns.
  • crates/katto-cli — thin CLI over the engine.
  • src-tauri — the Tauri app crate (katto, lib katto_lib); thin IPC shell over the engine.
  • src/ — React 19 + TypeScript + Vite frontend. Package manager: bun (never npm/yarn).

Dependency direction is one-way: app → engine, cli → engine.

Commands

  • Gate: just check (fmt-check + clippy -D warnings + cargo test + tsc). CI mirrors it 1:1. Never claim work done without it passing. Run from the workspace root.
  • Dev app: bun run tauri dev. Frontend only: bun run dev. The owner runs the dev server personally most of the time — don't start it yourself; assume it's already running or ask.

Verify before you build

  • Whenever code is edited or a new feature is written against an external API — a crate, an npm package, a plugin, a CLI flag — confirm the actual contract first (docs.rs, crates.io, official docs, or the installed package's types) instead of writing signatures from memory. Plans and code carry exact, verified names and signatures; where a version quirk is still possible, note the checked fallback inline.
  • The owner has granted standing permission to research anything not fully understood or in doubt — WebSearch/WebFetch, docs, source mirrors — without asking first. When in doubt, look it up; never guess.

Invariants (non-negotiable)

  • Rational time (Rational {num, den}) end-to-end in the engine; floats only at UI and model/transcript boundaries.
  • Media bytes never cross invoke — asset protocol only. JS owns live edit state; debounced auto-save is the only interactive bridge call; long ops stream via Channel<T>.
  • Folders are truth; SQLite is an index reconciled on launch.
  • Nothing fails silently: every background op is a jobs row + events row.
  • No numeric scoring/ranking anywhere in planning or curation — AI suggests, human decides.
  • Versioned exports (timelines/*-vN) are never overwritten; artifact writes are atomic (.tmp → rename).
  • Desktop shell: the window never scrolls. src/styles/main.css locks body (overflow: hidden, overscroll-behavior: none, user-select: none); AppShell (src/components/layout/app-shell.tsx) is a fixed 100dvh grid — titlebar + sidebar are pinned and its single content pane ([data-scroll-root], overflow-y-auto min-h-0) is the only scroll region. Nest further scrollers inside it, never restore document scroll. The residual macOS WKWebView elastic bounce is killed natively (scrollView.bounces = false via objc2) in Phase 2.
  • Conventional commits, one concern per commit, tests travel with their feature commit.

Guidance layout

  • Per-language style rules auto-load from .claude/rules/ (rust, tauri-commands, frontend, testing, design-system) — follow them; don't restate them here. The visual language (design-system) has its full spec in docs/superpowers/specs/2026-07-03-katto-design-system.md.
  • Procedures: add-tauri-command, add-db-migration, add-feature-surface, emitter-snapshot-change skills. Invoke before doing those tasks by hand.
  • Hooks enforce formatting, protect generated files (src-tauri/gen/, bindings.gen.ts, lockfiles, .snap.new), and gate turn-end on a fast check. Reviewer agents rust-reviewer and frontend-reviewer run on the diff before a task is declared done.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.