agentleFS
colinc86colinc86/gloss/CLAUDE.md

gloss

CLAUDE.md0 starsChanged 43 days agoMITView on GitHub

Native macOS app: file explorer on the left, viewer on the right, annotate any region of any file and send the notes to Claude Code, Codex, or OpenCode. Replaces what was lost moving from Orca to Warp and Herdr. The product description with scope, data model, and acceptance checks is @docs/PRODUCT.md. Milestone 1 is built, reviewed, and committed on main: explorer and viewers, anchored notes, the clipboard, tmux, Herdr, MCP, hook, and OpenCode transports, SSH/SFTP remote editing, the Herdr plugin,…

  • Reads credentials

The file

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

7 rules. About 0 are common, 1 is distinctive, and 6 are 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.

  • 6

    Very specific

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

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

    Not sandboxed, Developer ID signed and notarized (see docs/RELEASE.md).

    line 24
  2. Very specific:

    Use /verify-transport <name> [host] before claiming a transport works.

    line 39
  3. Very specific:

    Verify API signatures with the apple-api-researcher agent when unsure.

    line 43
  4. Very specific:

    Run swift-reviewer on a feature before calling it done.

    line 44
  5. Very specific:

    Never write to ~/.claude, ~/.codex, or ~/.config/opencode directly.

    line 47
  6. Very specific:

    Keep docs/PRODUCT.md in sync when a decision changes, and say so in the commit message.

    line 48
  7. Distinctive:

    Commit only when asked.

    line 49

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 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

Gloss

Native macOS app: file explorer on the left, viewer on the right, annotate any region of any file and send the notes to Claude Code, Codex, or OpenCode. Replaces what was lost moving from Orca to Warp and Herdr. The product description with scope, data model, and acceptance checks is @docs/PRODUCT.md.

State (2026-10-04)

Milestone 1 is built, reviewed, and committed on main: explorer and viewers, anchored notes, the clipboard, tmux, Herdr, MCP, hook, and OpenCode transports, SSH/SFTP remote editing, the Herdr plugin, and the hardening pass. Milestone 2 (the review browser with element notes and remote dev-server tunnels, GitHub pull requests as roots with tinted changed lines, Jira issues and Confluence pages as read-only Markdown, Settings → Integrations) is built and reviewed on main. A tidy-up pass (2026-10-04, phases A–F in the plan file) fixed what four audits found: browser lifecycle and navigation, provider and key handling, ssh aliases named like the integration hosts, Confluence paths and packets, parsing and HTTP limits, and polish. The acceptance checks in docs/PRODUCT.md are ticked with how each was verified; the ones that need a real agent session are left to the maintainer. Open items live only in docs/PRODUCT.md and the git log, not here.

Settled decisions (do not re-litigate)

  • Deployment target macOS 26. Swift 6 language mode, strict concurrency. SwiftUI shell, AppKit where SwiftUI falls short (outline view, text editor, PDF, image canvas). Chrome controls live in the toolbar so macOS 26 draws them as glass; sidebar and inspector keep system vibrancy.
  • Storage is SQLite via GRDB. Notes are keyed by host + absolute path and never written into the file.
  • Hosts are database rows: local, aliases imported from ~/.ssh/config (a toggle in Settings → Hosts), and hosts added in the app with host name, user, port, and identity file that become ssh -o options. An alias named like an integration host (web, github, atlassian) is listed as <name>-ssh and keeps its real alias in its options for ssh. Nothing about a specific machine or key agent is hard-wired.
  • Remote access uses the system ssh binary with ControlMaster, SFTP v3 spoken by the app, exec channel for commands, OpenSSH forwarding for the Herdr socket and the MCP port. No pure-Swift SSH library. See the sftp-over-ssh skill. The master runs with LogLevel=DEBUG; the UI shows ssh's own stages while connecting and names a silent key agent after 20 s instead of spinning. ssh ends lines with CRLF, which Swift reads as one Character: split on any newline.
  • Child processes are spawned with posix_spawn (close-on-exec defaults, responsibility disclaimed), never Foundation's Process.
  • Send targets: Herdr socket, OpenCode HTTP API, tmux, clipboard. See herdr-api and agent-integrations. MCP is how agents read and resolve what they were sent, and how they point the user at things: open_in_viewer, ask_user (an anchored question that waits for the user's answer under Attention) and add_favorite (issue #4). Drafts leave the app only when the user presses Send (issue #5, 2026-10-05): there are no prompt hooks (an older UserPromptSubmit hook handed every draft under a folder to any prompt, including the one a send submits), MCP tools see sent notes only, and Copy as Packet leaves notes as drafts.
  • Packet format is fixed by the context-packet skill. Every transport emits the same text.
  • The app reads, the agent writes. Integrations (GitHub, Atlassian, live web pages) are virtual hosts (github, atlassian, web) serving read-only FileSystemProviders, so documents, notes, the packet and the MCP tools are not duplicated. The Integrations clients issue GET only (a test asserts it); the packet's Resource: line names the pull request, issue or page so the agent changes it with its own tools. Keys live in the Keychain, entered in Settings → Integrations; debug builds load them with --integrations-env (into memory under --reset-db).
  • integrations.env at the repo root holds real keys: gitignored, never committed, used only to read while testing; test notes go to the clipboard target, never to an agent with GitHub or Atlassian tools.
  • Only made-up identifiers go into the repo: fixtures, docs, and commit messages use o/r, acme/…, example.atlassian.net, CP-7 and the like. A live check against a real account records what happened (“a merged three-file pull request”), never the real org, repo, pull request title, issue key, space, site or sha. The maintainer's clone has local hooks in .git/hooks that refuse a commit naming a term in .git/info/private-terms; the hooks and the list are private and not in the repo, so in any other clone check by hand.
  • Markdown viewer toggles rendered and source; anchors are stored in source coordinates. Text and markdown are editable; images, PDFs, spreadsheets are not.
  • Notes are created from a floating "Add Note" button beside the selection in every viewer; its shortcut, ⌘↩ while it shows (⌘⇧N otherwise, e.g. whole-file notes), is secondary, never the only path.
  • MCP registration and the Herdr plugin are installed only from Settings → Agents, with backups, never silently. Install (and Remove) also take out the prompt hook older builds added; a machine that still has it shows Update.
  • Not sandboxed, Developer ID signed and notarized (see docs/RELEASE.md). Releases come from scripts/release.sh, which publishes to GitHub and lists the release in appcast.xml at the repo root.
  • Updates are Sparkle 2 (linked directly by the app target, Gloss/Services/UpdaterService.swift); debug builds never start it. The repository is public: the feed (appcast.xml on raw.githubusercontent.com) and the release assets are read without a key; the delegate only asks downloads for an octet stream (releases from the private days list the asset's API URL).
  • Feedback (the toolbar ladybug) is the app's one write to GitHub: IssueReporter files issues on colinc86/gloss only, falling back to GitHub's filled-in new-issue form; the integrations clients stay GET-only.

Layout

  • Gloss/ app target: App/ (model, routes, launch options), Explorer/, Documents/ (sessions, viewer pane, conflict sheet), Notes/, Services/ (hosts, agent installs, send coordinator), Settings/.
  • Packages/Core (ids, schema, note store, anchors, packet builder, local file system), Packages/Remote (child processes, ssh config, ControlMaster, SFTP, exec, search, staging), Packages/Transports (connection registry, tmux, Herdr, MCP server, hooks installer and script, OpenCode, Herdr plugin bundle), Packages/Viewers (text, markdown, image, PDF, CSV, QuickLook, the review browser), Packages/Integrations (GET-only GitHub and Atlassian clients, the pull request and Jira/Confluence file systems, ADF to Markdown). Each has its own tests.
  • README.md is the front page and the only user documentation (the user guide was removed 2026-10-06; keep the README short) and docs/media/ holds the README's pictures. docs/ also has the product and design notes plus release instructions. .claude/skills/ holds the verified protocol references; read the relevant one before touching that area.

Build and test

  • There is exactly one copy of the app: Xcode's default DerivedData. Build with plain xcodebuild (never -derivedDataPath) or /build; launch and screenshot per the run-app skill (--host <alias>, --root, --open, --reset-db, --follow). A scripted build can collide with Xcode's ⌘R on code signing; just build again.
  • Signing comes from Config/Signing.xcconfig (ad hoc by default) and the gitignored Config/Signing.local.xcconfig with the maintainer's team. Never set a team in Xcode's Signing tab: it writes DEVELOPMENT_TEAM back into the project file. After adding or updating a package, run scripts/acknowledgments.py; a test fails until you do.
  • Package tests: swift test --package-path Packages/<Name>. Tests that need the environment skip when it is absent: loopback ssh, a running Herdr, tmux, GLOSS_REMOTE_HOST=<alias> for real-host checks, and the gitignored integrations.env (with GLOSS_ATLASSIAN_SITE and GLOSS_LIVE_PULL_REQUEST=owner/repo#n) for read-only integration checks. They create only throwaway resources and remove them on every path.
  • Use /verify-transport <name> [host] before claiming a transport works.

Working rules

  • Verify API signatures with the apple-api-researcher agent when unsure; never guess a framework or package API.
  • Run swift-reviewer on a feature before calling it done.
  • Quote every path: the project and scheme names contain spaces.
  • Remote and Herdr code must never leave test panes, sessions, buffers, masters, or temp files behind; check with pgrep -f '^/usr/bin/ssh -o ControlMaster=yes' after remote work.
  • Never write to ~/.claude, ~/.codex, or ~/.config/opencode directly; the in-app installer is the only thing that touches them.
  • Keep docs/PRODUCT.md in sync when a decision changes, and say so in the commit message.
  • Commit only when asked.

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.