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
In this repository7 other files it gives its agents.
- agent-integrationsSkill
- buildSkill
- context-packetSkill
- herdr-apiSkill
- run-appSkill
- sftp-over-sshSkill
- verify-transportSkill
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
- Very specific: line 24
Not sandboxed, Developer ID signed and notarized (see docs/RELEASE.md).
- Very specific: line 39
Use /verify-transport <name> [host] before claiming a transport works.
- Very specific: line 43
Verify API signatures with the apple-api-researcher agent when unsure.
- Very specific: line 44
Run swift-reviewer on a feature before calling it done.
- Very specific: line 47
Never write to ~/.claude, ~/.codex, or ~/.config/opencode directly.
- Very specific: line 48
Keep docs/PRODUCT.md in sync when a decision changes, and say so in the commit message.
- Distinctive: line 49
Commit only when asked.
≈ “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.
Files
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 becomessh -ooptions. An alias named like an integration host (web,github,atlassian) is listed as<name>-sshand 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
sshbinary 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 thesftp-over-sshskill. The master runs withLogLevel=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'sProcess. - Send targets: Herdr socket, OpenCode HTTP API, tmux, clipboard. See
herdr-apiandagent-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) andadd_favorite(issue #4). Drafts leave the app only when the user presses Send (issue #5, 2026-10-05): there are no prompt hooks (an olderUserPromptSubmithook 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-packetskill. 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-onlyFileSystemProviders, so documents, notes, the packet and the MCP tools are not duplicated. TheIntegrationsclients issue GET only (a test asserts it); the packet'sResource: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.envat 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-7and 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/hooksthat 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 fromscripts/release.sh, which publishes to GitHub and lists the release inappcast.xmlat 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.xmlon 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:
IssueReporterfiles issues oncolinc86/glossonly, 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.mdis the front page and the only user documentation (the user guide was removed 2026-10-06; keep the README short) anddocs/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 therun-appskill (--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 gitignoredConfig/Signing.local.xcconfigwith the maintainer's team. Never set a team in Xcode's Signing tab: it writesDEVELOPMENT_TEAMback into the project file. After adding or updating a package, runscripts/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 gitignoredintegrations.env(withGLOSS_ATLASSIAN_SITEandGLOSS_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-researcheragent when unsure; never guess a framework or package API. - Run
swift-revieweron 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/opencodedirectly; the in-app installer is the only thing that touches them. - Keep
docs/PRODUCT.mdin sync when a decision changes, and say so in the commit message. - Commit only when asked.
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
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.

