Skip to content

armgit / chops

Public Imported from GitHub
0

Your AI agent skills, finally organized. A macOS app to browse, edit, and manage skills across Claude Code, Cursor, Codex, Windsurf, and Amp.

Unified Library sidebar, ⌘K command palette, and keyboard/menu polish (#101)

Matt Andersonf16d2fc78f8a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8366fc6..c0dae60 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@
- Browse Skills now opens to a Trending list of popular skills
- Faster, broader skill search with an Official-only filter
+- New ⌘K command palette to jump to any tool's library, browse the registry, or create a skill/agent/rule
+- Added keyboard shortcuts: ⌘B to toggle the sidebar and ⌘⇧L to jump to Skills
## [1.15.0] - 2026-04-28
diff --git a/CLAUDE.md b/CLAUDE.md
index 9d597e0..40a250e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## What is Chops
-A native macOS app (SwiftUI + SwiftData) for discovering, organizing, and editing AI coding agent skills across tools (Claude Code, Cursor, Codex, Windsurf, Copilot, Aider, Amp). Fully open source (MIT), public repo at github.com/Shpigford/chops. No sandbox — requires full filesystem access to read user dotfiles.
+A native macOS app (SwiftUI + SwiftData) for discovering, organizing, and editing AI coding agent skills across tools (Claude Code, Cursor, Codex, Windsurf, Copilot, Aider, Amp, and many others — see `Chops/Models/ToolSource.swift` for the full set). Source-available under FSL-1.1-MIT (converts to MIT after two years), public repo at github.com/Shpigford/chops. No sandbox — requires full filesystem access to read user dotfiles.
## Build & Run
@@ -58,9 +58,11 @@ SwiftData store path is explicit: `~/Library/Application Support/Chops/Chops.sto
- Both share `OneShotResponseParser` (`Chops/Services/Agents/OneShotResponseParser.swift`) — the parser tries a structured-edits JSON envelope first and falls back to summary + fenced full-file. Either format produces a `PendingWrite`.
- Both conform to `AgentSession` (`Chops/Services/Agents/AgentSession.swift`); `AgentFactory.make(for:)` returns the right one. `ComposePanel` keys off the protocol so the UI doesn't care which transport is in use.
-**Views:** Three-column `NavigationSplitView` (Sidebar → List → Detail). Editor uses native `NSTextView` with markdown highlighting. Cmd+S save via `FocusedValues`. Agent responses render via `MarkdownMessageView` (MarkdownUI `.gitHub` theme + syntax highlighting).
+**Views:** Three-column `NavigationSplitView` (Sidebar → List → Detail). A ⌘K command palette (`Chops/Views/Shared/CommandPaletteView.swift`, presented via `AppState.showingCommandPalette`) provides fuzzy-search navigation and quick actions. Editor uses native `NSTextView` with markdown highlighting. Agent responses render via `MarkdownMessageView` (MarkdownUI `.gitHub` theme + syntax highlighting). Menus and global shortcuts are wired in `ChopsApp.swift`: ⌘S save (via `FocusedValues`), ⌘B toggle sidebar (via the `.toggleSidebar` NotificationCenter post), ⌘⇧L go to Skills, ⌘K command palette.
-**Tool sources** are defined in `ToolSource.swift` — each enum case knows its display name, icon, and filesystem paths to scan.
+**Registry/Discovery:** `SkillRegistry` fetches trending skills scraped from skills.sh (no public JSON API exists for this), cached in memory for the session via `SkillRegistry.shared`.
+
+**Tool sources** are defined in `Chops/Models/ToolSource.swift` — each enum case knows its display name, icon, and filesystem paths to scan.
## Release Pipeline
diff --git a/Chops.xcodeproj/project.pbxproj b/Chops.xcodeproj/project.pbxproj
index 51302c4..fbf163b 100644
--- a/Chops.xcodeproj/project.pbxproj
+++ b/Chops.xcodeproj/project.pbxproj
@@ -55,6 +55,7 @@
C2A028F40A1C665D29495DB6 /* StoreBootstrap.swift in Sources */ = {isa = PBXBuildFile; fileRef = 3D23D43EC788E51ED1C265FE /* StoreBootstrap.swift */; };
C30BEAE03E54BD36F257A925 /* ToolFilterView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 9A5774429CCE83C2AFBE046C /* ToolFilterView.swift */; };
C6CFF37CC0B155E8846344A4 /* ChopsIcon.icon in Resources */ = {isa = PBXBuildFile; fileRef = 04C3C644B72DD508A7CBC403 /* ChopsIcon.icon */; };
+ CAD849D5D67E6ECBEFC2D556 /* CommandPaletteView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5252495017119789B3F4B78F /* CommandPaletteView.swift */; };
CBD8FECF1C5A453C8B021665 /* FrontmatterParser.swift in Sources */ = {isa = PBXBuildFile; fileRef = 7C77C5B30E6C885B39444E5B /* FrontmatterParser.swift */; };
CCD92CB102DFA0965D6AFDB5 /* SidebarView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 2CF7822031FD82A28978D9C5 /* SidebarView.swift */; };
CECE9BEEC1D933C543B66A4E /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 17F7FE50C96124BA4EE43A6F /* Assets.xcassets */; };
@@ -97,6 +98,7 @@
3D23D43EC788E51ED1C265FE /* StoreBootstrap.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = StoreBootstrap.swift; sourceTree = "<group>"; };
4CA102A49ACFB23BC15794F8 /* CollectionListView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CollectionListView.swift; sourceTree = "<group>"; };
5155D141EF812A3FE9ADF59C /* SkillParser.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SkillParser.swift; sourceTree = "<group>"; };
+ 5252495017119789B3F4B78F /* CommandPaletteView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CommandPaletteView.swift; sourceTree = "<group>"; };
5487D9027B97F7E9EE9A1F4A /* ToolSource.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ToolSource.swift; sourceTree = "<group>"; };
5CAA9B98C7A69F32C6950710 /* ComposeModel.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ComposeModel.swift; sourceTree = "<group>"; };
60E0F71982C4AF0045962380 /* ContentView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ContentView.swift; sourceTree = "<group>"; };
@@ -185,6 +187,7 @@
children = (
125B3A8A0094D3BF9E068E75 /* ActivityRow.swift */,
F8C32D91C01AA0A0D63D00ED /* AgentLogViewer.swift */,
+ 5252495017119789B3F4B78F /* CommandPaletteView.swift */,
5CAA9B98C7A69F32C6950710 /* ComposeModel.swift */,
937F83BF3496CB231C535608 /* ComposePanel.swift */,
B955C8B935BD62ED4811FCA2 /* DiffReviewPanel.swift */,
@@ -429,6 +432,7 @@
B007633F077CBD9EBA65B017 /* CodexCLIAgent.swift in Sources */,
7A17C99C5EFAE3AA9E788D50 /* Collection.swift in Sources */,
7EC6156934D559226BC78859 /* CollectionListView.swift in Sources */,
+ CAD849D5D67E6ECBEFC2D556 /* CommandPaletteView.swift in Sources */,
E46A2BA5FA20531A06AFB418 /* ComposeModel.swift in Sources */,
74045816B0CF10369DB51ADD /* ComposePanel.swift in Sources */,
D4C107BE303FC07CAF9C66AF /* ContentView.swift in Sources */,
diff --git a/Chops/App/AppState.swift b/Chops/App/AppState.swift
index 57763e6..e3f9249 100644
--- a/Chops/App/AppState.swift
+++ b/Chops/App/AppState.swift
@@ -7,12 +7,22 @@ final class AppState {
var searchText: String = ""
var showingNewSkillSheet: Bool = false
var showingRegistrySheet: Bool = false
+ var showingCommandPalette: Bool = false
+ /// Action chosen in the command palette, run after the palette sheet dismisses
+ /// (so we never present two sheets at once).
+ var pendingPaletteAction: PaletteAction?
var newItemKind: ItemKind = .skill
var sidebarFilter: SidebarFilter = .allSkills
/// Filter by item kind within a tool view (nil = show all)
var toolKindFilter: ItemKind?
}
+enum PaletteAction: Equatable {
+ case navigate(SidebarFilter)
+ case openDiscovery
+ case newItem(ItemKind)
+}
+
enum SidebarFilter: Hashable {
case allSkills
case allAgents
diff --git a/Chops/App/ChopsApp.swift b/Chops/App/ChopsApp.swift
index 554c239..3c06902 100644
--- a/Chops/App/ChopsApp.swift
+++ b/Chops/App/ChopsApp.swift
@@ -39,6 +39,24 @@ struct ChopsApp: App {
.modelContainer(sharedModelContainer)
.commands {
TextEditingCommands()
+ CommandGroup(after: .sidebar) {
+ Button("Toggle Sidebar") {
+ NotificationCenter.default.post(name: .toggleSidebar, object: nil)
+ }
+ .keyboardShortcut("b", modifiers: .command)
+
+ Button("Go to Skills") {
+ appState.sidebarFilter = .allSkills
+ }
+ .keyboardShortcut("l", modifiers: [.command, .shift])
+
+ Button("Command Palette") {
+ appState.showingCommandPalette = true
+ }
+ .keyboardShortcut("k", modifiers: .command)
+
+ Divider()
+ }
CommandGroup(replacing: .saveItem) {
Button("Save") {
NotificationCenter.default.post(name: .saveCurrentSkill, object: nil)
diff --git a/Chops/App/ContentView.swift b/Chops/App/ContentView.swift
index 963e704..24183d8 100644
--- a/Chops/App/ContentView.swift
+++ b/Chops/App/ContentView.swift
@@ -37,6 +37,9 @@ struct ContentView: View {
.sheet(isPresented: $appState.showingRegistrySheet) {
RegistrySheet()
}
+ .sheet(isPresented: $appState.showingCommandPalette, onDismiss: runPaletteAction) {
+ CommandPaletteView()
+ }
.onChange(of: appState.sidebarFilter) {
appState.toolKindFilter = nil
}
@@ -44,6 +47,25 @@ struct ContentView: View {
.onReceive(NotificationCenter.default.publisher(for: .customScanPathsChanged)) { _ in
scanner?.scanAll()
}
+ .onReceive(NotificationCenter.default.publisher(for: .toggleSidebar)) { _ in
+ columnVisibility = columnVisibility == .doubleColumn ? .all : .doubleColumn
+ }
+ }
+
+ /// Runs the action chosen in the command palette, after that sheet has
+ /// fully dismissed — avoids presenting two sheets simultaneously.
+ private func runPaletteAction() {
+ guard let action = appState.pendingPaletteAction else { return }
+ appState.pendingPaletteAction = nil
+ switch action {
+ case .navigate(let filter):
+ appState.sidebarFilter = filter
+ case .openDiscovery:
+ appState.showingRegistrySheet = true
+ case .newItem(let kind):
+ appState.newItemKind = kind
+ appState.showingNewSkillSheet = true
+ }
}
private func startScanning() {
diff --git a/Chops/Views/Detail/SkillEditorView.swift b/Chops/Views/Detail/SkillEditorView.swift
index 1ea16d8..9636e1b 100644
--- a/Chops/Views/Detail/SkillEditorView.swift
+++ b/Chops/Views/Detail/SkillEditorView.swift
@@ -222,6 +222,7 @@ struct SkillEditorView: View {
extension Notification.Name {
static let saveCurrentSkill = Notification.Name("saveCurrentSkill")
+ static let toggleSidebar = Notification.Name("toggleSidebar")
}
// MARK: - Syntax-highlighted NSTextView wrapper
diff --git a/Chops/Views/Settings/SettingsView.swift b/Chops/Views/Settings/SettingsView.swift
index 45e12f7..6e3ddc6 100644
--- a/Chops/Views/Settings/SettingsView.swift
+++ b/Chops/Views/Settings/SettingsView.swift
@@ -44,10 +44,12 @@ struct SettingsView: View {
@State private var selectedTab: SettingsTab = .general
@State private var customPaths: [String] = []
@AppStorage("defaultTool") private var defaultTool: ToolSource = .claude
+ @FocusState private var navFocused: Bool
var body: some View {
VStack(spacing: 0) {
- // Tab bar
+ // Tab bar — focused on open so the keyboard can drive navigation
+ // immediately; ←/→ move between sections.
HStack(spacing: 1) {
ForEach(SettingsTab.allCases) { tab in
SettingsTabButton(tab: tab, isSelected: selectedTab == tab) {
@@ -58,6 +60,13 @@ struct SettingsView: View {
.padding(.horizontal, 12)
.padding(.top, 8)
.padding(.bottom, 4)
+ .focusable()
+ .focused($navFocused)
+ .focusEffectDisabled()
+ .onKeyPress(.leftArrow) { selectAdjacentTab(-1) }
+ .onKeyPress(.rightArrow) { selectAdjacentTab(1) }
+ .accessibilityElement(children: .contain)
+ .accessibilityLabel("Settings sections")
Divider()
@@ -67,11 +76,23 @@ struct SettingsView: View {
}
.frame(width: 520)
.fixedSize(horizontal: false, vertical: true)
+ .defaultFocus($navFocused, true)
.onAppear {
loadCustomPaths()
}
}
+ /// Move the selection one tab left/right, clamped at the ends. Returns
+ /// `.handled` so the arrow key never falls through to scroll the window.
+ private func selectAdjacentTab(_ direction: Int) -> KeyPress.Result {
+ let tabs = SettingsTab.allCases
+ guard let current = tabs.firstIndex(of: selectedTab) else { return .ignored }
+ let target = current + direction
+ guard tabs.indices.contains(target) else { return .handled }
+ selectedTab = tabs[target]
+ return .handled
+ }
+
@ViewBuilder
private var tabContent: some View {
switch selectedTab {
diff --git a/Chops/Views/Shared/CommandPaletteView.swift b/Chops/Views/Shared/CommandPaletteView.swift
new file mode 100644
index 0000000..3d44800
--- /dev/null
+++ b/Chops/Views/Shared/CommandPaletteView.swift
@@ -0,0 +1,197 @@
+import SwiftUI
+import SwiftData
+
+/// A ⌘K command palette: fuzzy-search and run quick actions — jump to a tool's
+/// library, open the registry, or create a new skill/agent/rule. Keyboard-first
+/// (↑/↓ to move, ↵ to run, ⎋ to dismiss); mouse hover/click also work.
+struct CommandPaletteView: View {
+ @Environment(AppState.self) private var appState
+ @Environment(\.dismiss) private var dismiss
+ @Query(sort: \Skill.name) private var allSkills: [Skill]
+
+ @State private var query = ""
+ @State private var selectedIndex = 0
+ @State private var hoveredID: String?
+ @FocusState private var searchFocused: Bool
+
+ private var activeTools: [ToolSource] {
+ ToolSource.allCases.filter { tool in
+ tool.listable && allSkills.contains { $0.toolSources.contains(tool) }
+ }
+ }
+
+ private var commands: [PaletteCommand] {
+ var result: [PaletteCommand] = [
+ PaletteCommand(title: "Skills", subtitle: nil, systemImage: "doc.text",
+ tool: nil, category: "Navigate", action: .navigate(.allSkills)),
+ PaletteCommand(title: "Agents", subtitle: nil, systemImage: "person.crop.rectangle",
+ tool: nil, category: "Navigate", action: .navigate(.allAgents)),
+ PaletteCommand(title: "Rules", subtitle: nil, systemImage: "list.bullet.rectangle",
+ tool: nil, category: "Navigate", action: .navigate(.allRules)),
+ PaletteCommand(title: "Favorites", subtitle: nil, systemImage: "star",
+ tool: nil, category: "Navigate", action: .navigate(.favorites)),
+ ]
+ for tool in activeTools {
+ result.append(PaletteCommand(title: tool.displayName, subtitle: nil,
+ systemImage: tool.iconName, tool: tool,
+ category: "Navigate", action: .navigate(.tool(tool))))
+ }
+ result.append(PaletteCommand(title: "Browse Registry",
+ subtitle: nil, systemImage: "safari",
+ tool: nil, category: "Discover", action: .openDiscovery))
+ for kind in ItemKind.allCases {
+ result.append(PaletteCommand(title: "New \(kind.singularName)", subtitle: nil,
+ systemImage: "plus", tool: nil,
+
+ category: "Create", action: .newItem(kind)))
+ }
+ return result
+ }
+
+ private var filtered: [PaletteCommand] {
+ guard !query.isEmpty else { return commands }
+ return commands.filter {
+ $0.title.localizedCaseInsensitiveContains(query) ||
+ ($0.subtitle?.localizedCaseInsensitiveContains(query) ?? false) ||
+ $0.category.localizedCaseInsensitiveContains(query)
+ }
+ }
+
+ var body: some View {
+ VStack(spacing: 0) {
+ HStack(spacing: 8) {
+ Image(systemName: "magnifyingglass")
+ .foregroundStyle(.secondary)
+ TextField("Search commands…", text: $query)
+ .textFieldStyle(.plain)
+ .font(.title3)
+ .focused($searchFocused)
+ .onSubmit(runSelected)
+ .onChange(of: query) { selectedIndex = 0 }
+ .onKeyPress(.downArrow) { move(1); return .handled }
+ .onKeyPress(.upArrow) { move(-1); return .handled }
+ }
+ .padding(.horizontal, 16)
+ .padding(.vertical, 14)
+
+ Divider()
+
+ if filtered.isEmpty {
+ Text("No matching commands")
+ .foregroundStyle(.secondary)
+ .frame(maxWidth: .infinity)
+ .padding(.vertical, 28)
+ } else {
+ resultsList
+ }
+ }
+ .frame(width: 560)
+ .background(.thickMaterial)
+ .onAppear { searchFocused = true }
+ .onExitCommand { dismiss() }
+ }
+
+ private var resultsList: some View {
+ ScrollViewReader { proxy in
+ ScrollView {
+ LazyVStack(alignment: .leading, spacing: 1) {
+ ForEach(Array(filtered.enumerated()), id: \.element.id) { index, command in
+ VStack(alignment: .leading, spacing: 1) {
+ if index == 0 || filtered[index - 1].category != command.category {
+ Text(command.category.uppercased())
+ .font(.caption2.weight(.semibold))
+ .foregroundStyle(.secondary)
+ .padding(.horizontal, 20)
+ .padding(.top, index == 0 ? 10 : 14)
+ .padding(.bottom, 2)
+ }
+ CommandRow(command: command,
+ selected: index == selectedIndex,
+ hovered: command.id == hoveredID)
+ .contentShape(Rectangle())
+ .onTapGesture { run(command) }
+ .onHover { hovering in
+ if hovering { hoveredID = command.id }
+ else if hoveredID == command.id { hoveredID = nil }
+ }
+ }
+ .id(command.id)
+ }
+ }
+ .padding(.bottom, 8)
+ }
+ .frame(maxHeight: 360)
+ .onChange(of: selectedIndex) {
+ guard filtered.indices.contains(selectedIndex) else { return }
+ proxy.scrollTo(filtered[selectedIndex].id, anchor: .center)
+ }
+ }
+ }
+
+ private func move(_ delta: Int) {
+ guard !filtered.isEmpty else { return }
+ selectedIndex = min(max(selectedIndex + delta, 0), filtered.count - 1)
+ }
+
+ private func runSelected() {
+ guard filtered.indices.contains(selectedIndex) else { return }
+ run(filtered[selectedIndex])
+ }
+
+ private func run(_ command: PaletteCommand) {
+ appState.pendingPaletteAction = command.action
+ dismiss()
+ }
+}
+
+private struct PaletteCommand: Identifiable {
+ let title: String
+ let subtitle: String?
+ let systemImage: String
+ let tool: ToolSource?
+ let category: String
+ let action: PaletteAction
+
+ var id: String { "\(category)/\(title)" }
+}
+
+private struct CommandRow: View {
+ let command: PaletteCommand
+ let selected: Bool
+ let hovered: Bool
+
+ private var background: Color {
+ if selected { return .accentColor }
+ if hovered { return .primary.opacity(0.08) }
+ return .clear
+ }
+
+ var body: some View {
+ HStack(spacing: 10) {
+ Group {
+ if let tool = command.tool {
+ ToolIcon(tool: tool, size: 16)
+ } else {
+ Image(systemName: command.systemImage)
+ }
+ }
+ .frame(width: 20, height: 18)
+ .foregroundStyle(selected ? .white : .secondary)
+
+ VStack(alignment: .leading, spacing: 1) {
+ Text(command.title)
+ .foregroundStyle(selected ? .white : .primary)
+ if let subtitle = command.subtitle {
+ Text(subtitle)
+ .font(.caption)
+ .foregroundStyle(selected ? .white.opacity(0.85) : .secondary)
+ }
+ }
+ Spacer(minLength: 0)
+ }
+ .padding(.horizontal, 12)
+ .padding(.vertical, 7)
+ .background(background, in: RoundedRectangle(cornerRadius: 6))
+ .padding(.horizontal, 8)
+ }
+}
diff --git a/Chops/Views/Shared/RegistrySheet.swift b/Chops/Views/Shared/RegistrySheet.swift
index bec86b6..38096ed 100644
--- a/Chops/Views/Shared/RegistrySheet.swift
+++ b/Chops/Views/Shared/RegistrySheet.swift
@@ -184,8 +184,12 @@ struct RegistrySheet: View {
.contentShape(Rectangle())
}
.buttonStyle(.plain)
+ // Match the Trending/Official-only header's 20pt gutters.
+ .listRowInsets(EdgeInsets(top: 8, leading: 10, bottom: 8, trailing: 10))
}
.listStyle(.plain)
+ // Keep the last row clear of the sheet's rounded bottom corners.
+ .contentMargins(.bottom, 12, for: .scrollContent)
}
if let error {
diff --git a/Chops/Views/Sidebar/SidebarView.swift b/Chops/Views/Sidebar/SidebarView.swift
index 45181d0..d0444f1 100644
--- a/Chops/Views/Sidebar/SidebarView.swift
+++ b/Chops/Views/Sidebar/SidebarView.swift
@@ -41,6 +41,14 @@ struct SidebarView: View {
Label("Favorites", systemImage: "star")
.badge(allSkills.filter(\.isFavorite).count)
.tag(SidebarFilter.favorites)
+
+ // Opens the registry sheet; not a selectable filter.
+ Button {
+ appState.showingRegistrySheet = true
+ } label: {
+ Label("Discovery", systemImage: "safari")
+ }
+ .buttonStyle(.plain)
}
Section("Tools") {
diff --git a/README.md b/README.md
index 9a52316..e6c1314 100644
--- a/README.md
+++ b/README.md
@@ -30,7 +30,30 @@ One macOS app to discover, organize, and edit coding agent skills and agents acr
- **Remote servers** — Connect to servers running [OpenClaw](https://openclaw.ai), [Hermes](https://github.com/NousResearch/hermes-agent), or other layouts to discover, browse, and install skills
- **Skills Discovery** — Browse, search, and install skills directly from the [skills.sh registry](https://skills.sh)
-## Prerequisites
+## Supported Tools
+
+Chops scans these directories for skills and agents:
+
+| Tool | Skills | Agents |
+|------|--------|--------|
+| Global | `~/.agents/skills/` | — |
+| Claude Code | `~/.claude/skills/` | `~/.claude/agents/` |
+| Cursor | `~/.cursor/skills/`, `~/.cursor/rules` | `~/.cursor/agents/` |
+| Windsurf | `~/.codeium/windsurf/memories/`, `~/.windsurf/rules` | — |
+| Codex | `~/.codex/skills/` | `~/.codex/agents/` |
+| Amp | `~/.config/amp/skills/` | — |
+
+Copilot and Aider are also supported but only detect project-level skills and agents (no global paths). Custom scan paths can be added for any tool.
+
+Tool definitions live in `Chops/Models/ToolSource.swift` — each enum case knows its display name, icon, color, and filesystem paths.
+
+---
+
+## Running from source
+
+Build and run Chops locally with the steps below. End users can [download the latest release](https://github.com/Shpigford/chops/releases/latest/download/Chops.dmg) instead.
+
+### Prerequisites
- **macOS 15** (Sequoia) or later
- **Xcode** with command-line tools (`xcode-select --install`)
@@ -39,7 +62,7 @@ One macOS app to discover, organize, and edit coding agent skills and agents acr
Sparkle (auto-update framework) is the only external dependency and is pulled automatically by Xcode via Swift Package Manager. No manual setup needed.
-## Quick Start
+### Quick Start
```bash
git clone https://github.com/Shpigford/chops.git
@@ -59,7 +82,11 @@ Then hit **Cmd+R** to build and run.
xcodebuild -scheme Chops -configuration Debug build
```
-## Project Structure
+## Contributing
+
+Want to change the app? The sections below cover project layout, architecture, and common tasks.
+
+### Project Structure
```
Chops/
@@ -92,11 +119,11 @@ scripts/ # Release pipeline (release.sh)
site/ # Marketing website (Astro 6)
```
-## Architecture
+### Architecture
**SwiftUI + SwiftData**, native macOS with zero web views.
-### App lifecycle
+#### App lifecycle
1. `ChopsApp` initializes a SwiftData `ModelContainer` (persists `Skill` and `SkillCollection`)
2. Sparkle updater starts in the background
@@ -105,60 +132,43 @@ site/ # Marketing website (Astro 6)
5. `SkillScanner` probes all tool directories and upserts discovered skills
6. `FileWatcher` attaches FSEvents listeners — on any change, the scanner re-runs automatically
-### Key design decisions
+#### Key design decisions
- **No sandbox.** The app needs unrestricted filesystem access to read dotfiles across `~/`. This is intentional and required for core functionality. The entitlements file explicitly disables the app sandbox.
- **Dedup via symlinks.** Skills are uniquely identified by their resolved symlink path. If the same file is symlinked into multiple tool directories, it shows up as one skill with multiple tool badges.
- **No test suite.** Validate changes manually — build, run, trigger the feature you changed, observe the result.
-### State management
+#### State management
`AppState` is an `@Observable` class that holds all UI state: selected tool filter, selected skill, search text, sidebar filter mode. It's injected via `@Environment` and accessible from any view.
-### UI layout
+#### UI layout
Three-column `NavigationSplitView`:
- **Sidebar** — tool filters and collections
- **List** — filtered/searched skill list
- **Detail** — skill editor (wraps `NSTextView` for native text editing with Cmd+S save)
-## Supported Tools
+### Common Dev Tasks
-Chops scans these directories for skills and agents:
-
-| Tool | Skills | Agents |
-|------|--------|--------|
-| Claude Code | `~/.claude/skills/` | `~/.claude/agents/` |
-| Cursor | `~/.cursor/skills/`, `~/.cursor/rules` | `~/.cursor/agents/` |
-| Windsurf | `~/.codeium/windsurf/memories/`, `~/.windsurf/rules` | — |
-| Codex | `~/.codex/skills/` | `~/.codex/agents/` |
-| Amp | `~/.config/amp/skills/` | — |
-| Global | `~/.agents/skills/` | — |
-
-Copilot and Aider are also supported but only detect project-level skills and agents (no global paths). Custom scan paths can be added for any tool.
-
-Tool definitions live in `Chops/Models/ToolSource.swift` — each enum case knows its display name, icon, color, and filesystem paths.
-
-## Common Dev Tasks
-
-### Add support for a new tool
+#### Add support for a new tool
1. Add a new case to the `ToolSource` enum in `Chops/Models/ToolSource.swift`
2. Fill in `displayName`, `iconName`, `color`, and `globalPaths`
3. Optionally add a logo to the asset catalog and return it from `logoAssetName`
4. Update `SkillScanner` if the new tool uses a non-standard file layout
-### Modify skill parsing
+#### Modify skill parsing
- **Frontmatter (`.md`)** — edit `Chops/Utilities/FrontmatterParser.swift`
- **Cursor `.mdc` files** — edit `Chops/Utilities/MDCParser.swift`
- **Dispatch logic** — edit `Chops/Services/SkillParser.swift` (decides which parser to use)
-### Change the UI
+#### Change the UI
Views are in `Chops/Views/`, organized by column (Sidebar, Detail) and shared components. The main layout is in `Chops/App/ContentView.swift`.
-## Testing
+### Testing
No automated test suite. Validate manually:
@@ -167,6 +177,10 @@ No automated test suite. Validate manually:
3. Observe the result — check for correct behavior and error messages
4. Test edge cases (empty states, missing directories, malformed files)
+### AI Agent Setup
+
+This repo includes a Claude Code skill at `.claude/skills/setup.md` that gives AI coding agents full context on the project — architecture, key files, and common tasks. If you're using Claude Code, it'll pick this up automatically.
+
## Website
The marketing site lives in `site/` and is built with [Astro](https://astro.build/).
@@ -178,10 +192,6 @@ npm run dev # local dev server
npm run build # production build → site/dist/
```
-## AI Agent Setup
-
-This repo includes a Claude Code skill at `.claude/skills/setup.md` that gives AI coding agents full context on the project — architecture, key files, and common tasks. If you're using Claude Code, it'll pick this up automatically.
-
## License
FSL-1.1-MIT — see [LICENSE](LICENSE).
diff --git a/docs/feature/images/command-palette.png b/docs/feature/images/command-palette.png
new file mode 100644
index 0000000..e4f5908
Binary files /dev/null and b/docs/feature/images/command-palette.png differ
diff --git a/docs/feature/keyboard-navigation.md b/docs/feature/keyboard-navigation.md
new file mode 100644
index 0000000..88ffe61
--- /dev/null
+++ b/docs/feature/keyboard-navigation.md
@@ -0,0 +1,68 @@
+# Keyboard Navigation
+
+Chops is keyboard-driven. The ⌘K command palette is the fastest way to jump
+anywhere or create something; everything it does is also bound to a menu
+shortcut.
+
+## ⌘K — Command Palette
+
+Press **⌘K** (also under the **View** menu) to open the palette. Start typing to
+fuzzy-filter across command title and category. It is keyboard-first:
+
+| Key | Action |
+|-----|--------|
+| Type | Filter the command list |
+| ↑ / ↓ | Move the selection |
+| ↵ | Run the selected command |
+| ⎋ | Dismiss the palette |
+| Click | Run a command directly (hover highlights, but never moves the keyboard selection) |
+
+The chosen command runs after the palette closes, so it never collides with the
+sheet it opens.
+
+### Commands shown
+
+**Navigate** — switches the sidebar selection / list view:
+- **Skills**, **Agents**, **Rules** — each library section
+- **Favorites** — items marked favorite
+- **One row per tool** that currently has items — e.g. Global, Claude Code,
+ Cursor, Codex, OpenCode — each jumps to that tool's library. Tools with no
+ items are omitted (matching the sidebar).
+
+**Discover**:
+- **Browse Registry** — opens the registry sheet to discover skills from
+ skills.sh (see [skills-discovery](skills-discovery.md))
+
+**Create** — opens the New Item sheet pre-set to that kind:
+- **New Skill**
+- **New Agent**
+- **New Rule**
+
+## App shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| ⌘K | Open the command palette |
+| ⌘B | Toggle the sidebar |
+| ⌘⇧L | Go to Skills |
+| ⌘S | Save the current skill (disabled when nothing is selected) |
+| ⌘, | Open Settings |
+
+⌘, opens the standard macOS **Settings** window (a separate window, not a modal
+sheet). It is provided automatically by SwiftUI's `Settings` scene and listed as
+**Settings…** under the **Chops** app menu — no custom binding is needed. The
+window opens with the section tab bar focused, so **← / →** switch sections
+(General, Library, AI Assist, Scan Directories, Servers, About) without reaching
+for the mouse.
+
+Standard macOS text-editing shortcuts (⌘C/⌘V/⌘Z, etc.) apply in the editor.
+
+## Sheet & panel conventions
+
+Modal sheets and panels follow the usual macOS defaults:
+
+| Shortcut | Action |
+|----------|--------|
+| ↵ | Confirm the primary button (e.g. **Create**, **Add**) |
+| ⌘↵ | Send / accept in the compose and diff-review panels |
+| ⎋ or ⌘. | Cancel / dismiss |