# shpigford/chops architecture

> Architecture diagram of the GitHub repository shpigford/chops, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shpigford/chops
- Repository: https://github.com/shpigford/chops

## Overview

Chops is a macOS app for discovering, organizing, editing, and creating coding-agent skills, agents, and rules across local tool directories and remote servers. The principal workflow scans tool paths, parses files, deduplicates and persists them, then presents searchable items for browsing and editing; file changes trigger rescans. Other major capabilities include registry discovery and agent-assisted composition with diff review. Relationships among unsampled subsystems are included only where the README or source index supports them; implementation details beyond the provided excerpts remain unverified.

Main entry points: [`Chops/Views/Shared/ComposePanel.swift`](https://github.com/shpigford/chops/blob/main/Chops/Views/Shared/ComposePanel.swift) (Agent composition), [`Chops/Services/SkillScanner.swift`](https://github.com/shpigford/chops/blob/main/Chops/Services/SkillScanner.swift) (Local and remote scanner), [`Chops/App/ContentView.swift`](https://github.com/shpigford/chops/blob/main/Chops/App/ContentView.swift) (Main workspace), [`Chops/Services/SkillParser.swift`](https://github.com/shpigford/chops/blob/main/Chops/Services/SkillParser.swift) (Skill parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and navigation"]
  node_appstate["App state<br/>[AppState.swift]"]
  node_mainview["Main workspace<br/>[ContentView.swift]"]
  node_sidebar["Browse sidebar<br/>[SidebarView.swift]"]
  node_itemlist["Skill and agent list"]
end

subgraph group_discovery["Discovery and storage"]
  node_scanner["Local and remote scanner<br/>[SkillScanner.swift]"]
  node_toolpaths["Tool definitions<br/>[ToolSource.swift]"]
  node_parser["Skill parser<br/>[SkillParser.swift]"]
  node_frontmatter["Frontmatter parser"]
  node_mdc["Cursor MDC parser<br/>[MDCParser.swift]"]
  node_watcher["File watcher<br/>[FileWatcher.swift]"]
  node_search["Full-text search"]
  node_skillmodel[("Skill records<br/>[Skill.swift]")]
  node_collections[("Collections<br/>[Collection.swift]")]
end

subgraph group_editing["Editing and creation"]
  node_detail["Skill detail"]
  node_editor["Skill editor"]
  node_newitem["Create skill or agent"]
end

subgraph group_agents["Agent composition"]
  node_compose["Agent composition<br/>[ComposePanel.swift]"]
  node_template["Prompt templates"]
  node_agentfactory["Agent factory<br/>[AgentFactory.swift]"]
  node_agentsession["Agent session<br/>[AgentSession.swift]"]
  node_claude["Claude CLI agent"]
  node_codex["Codex CLI agent"]
  node_diff["Diff review"]
  node_agentconfig["Agent configuration"]
  node_agenttarget["Agent targets<br/>[AgentTarget.swift]"]
  node_wizardtype["Wizard templates"]
end

subgraph group_integrations["External integrations"]
  node_registry["Skills registry"]
  node_registryservice["Registry client"]
  node_remotesettings["Remote server setup"]
  node_ssh["SSH operations<br/>[SSHService.swift]"]
end

node_user(("User"))
node_remotehost(("Remote server"))

node_user -->|"uses"| node_mainview
node_mainview -->|"reads state"| node_appstate
node_mainview -->|"renders"| node_sidebar
node_mainview -->|"renders"| node_itemlist
node_mainview -->|"starts scan"| node_scanner
node_mainview -->|"starts watching"| node_watcher
node_watcher -->|"triggers rescan"| node_scanner
node_scanner -->|"scans paths"| node_toolpaths
node_scanner -->|"parses files"| node_parser
node_parser -->|"dispatches parsing"| node_frontmatter
node_parser -->|"dispatches parsing"| node_mdc
node_scanner -->|"upserts records"| node_skillmodel
node_scanner -->|"syncs remote skills"| node_ssh
node_ssh -->|"runs commands"| node_remotehost
node_remotesettings -->|"tests connection"| node_ssh
node_remotesettings -->|"requests sync"| node_scanner
node_sidebar -->|"selects items"| node_itemlist
node_itemlist -.->|"searches items"| node_search
node_user -->|"opens item"| node_detail
node_detail -->|"shows editor"| node_editor
node_editor -.->|"saves changes"| node_skillmodel
node_user -->|"creates item"| node_newitem
node_user -->|"discovers skills"| node_registry
node_registry -->|"searches registry"| node_registryservice
node_user -->|"requests edits"| node_compose
node_compose -->|"builds prompt"| node_template
node_compose -->|"creates agent"| node_agentfactory
node_agentfactory -->|"selects implementation"| node_claude
node_agentfactory -->|"selects implementation"| node_codex
node_claude -->|"implements session"| node_agentsession
node_codex -->|"implements session"| node_agentsession
node_compose -->|"drives session"| node_agentsession
node_compose -->|"reviews proposal"| node_diff
node_compose -->|"loads configuration"| node_agentconfig
node_compose -->|"selects template"| node_wizardtype
node_registry -->|"targets installs"| node_agenttarget

click node_appstate "https://github.com/shpigford/chops/blob/main/Chops/App/AppState.swift"
click node_mainview "https://github.com/shpigford/chops/blob/main/Chops/App/ContentView.swift"
click node_sidebar "https://github.com/shpigford/chops/blob/main/Chops/Views/Sidebar/SidebarView.swift"
click node_itemlist "https://github.com/shpigford/chops/blob/main/Chops/Views/Sidebar/SkillListView.swift"
click node_scanner "https://github.com/shpigford/chops/blob/main/Chops/Services/SkillScanner.swift"
click node_toolpaths "https://github.com/shpigford/chops/blob/main/Chops/Models/ToolSource.swift"
click node_parser "https://github.com/shpigford/chops/blob/main/Chops/Services/SkillParser.swift"
click node_frontmatter "https://github.com/shpigford/chops/blob/main/Chops/Utilities/FrontmatterParser.swift"
click node_mdc "https://github.com/shpigford/chops/blob/main/Chops/Utilities/MDCParser.swift"
click node_watcher "https://github.com/shpigford/chops/blob/main/Chops/Services/FileWatcher.swift"
click node_search "https://github.com/shpigford/chops/blob/main/Chops/Services/SearchService.swift"
click node_skillmodel "https://github.com/shpigford/chops/blob/main/Chops/Models/Skill.swift"
click node_collections "https://github.com/shpigford/chops/blob/main/Chops/Models/Collection.swift"
click node_detail "https://github.com/shpigford/chops/blob/main/Chops/Views/Detail/SkillDetailView.swift"
click node_editor "https://github.com/shpigford/chops/blob/main/Chops/Views/Detail/SkillEditorView.swift"
click node_newitem "https://github.com/shpigford/chops/blob/main/Chops/Views/Shared/NewSkillSheet.swift"
click node_registry "https://github.com/shpigford/chops/blob/main/Chops/Views/Shared/RegistrySheet.swift"
click node_registryservice "https://github.com/shpigford/chops/blob/main/Chops/Services/SkillRegistry.swift"
click node_remotesettings "https://github.com/shpigford/chops/blob/main/Chops/Views/Settings/RemoteServersSettingsView.swift"
click node_ssh "https://github.com/shpigford/chops/blob/main/Chops/Services/SSHService.swift"
click node_compose "https://github.com/shpigford/chops/blob/main/Chops/Views/Shared/ComposePanel.swift"
click node_template "https://github.com/shpigford/chops/blob/main/Chops/Services/TemplateManager.swift"
click node_agentfactory "https://github.com/shpigford/chops/blob/main/Chops/Services/Agents/AgentFactory.swift"
click node_agentsession "https://github.com/shpigford/chops/blob/main/Chops/Services/Agents/AgentSession.swift"
click node_claude "https://github.com/shpigford/chops/blob/main/Chops/Services/Agents/Claude/ClaudeCLIAgent.swift"
click node_codex "https://github.com/shpigford/chops/blob/main/Chops/Services/Agents/Codex/CodexCLIAgent.swift"
click node_diff "https://github.com/shpigford/chops/blob/main/Chops/Views/Shared/DiffReviewPanel.swift"
click node_agentconfig "https://github.com/shpigford/chops/blob/main/Chops/Models/AgentConfiguration.swift"
click node_agenttarget "https://github.com/shpigford/chops/blob/main/Chops/Models/AgentTarget.swift"
click node_wizardtype "https://github.com/shpigford/chops/blob/main/Chops/Models/WizardTemplateType.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_appstate,node_mainview,node_sidebar,node_itemlist,node_user toneBlue
class node_scanner,node_toolpaths,node_parser,node_frontmatter,node_mdc,node_watcher,node_search,node_skillmodel,node_collections toneAmber
class node_detail,node_editor,node_newitem,node_remotehost toneMint
class node_compose,node_template,node_agentfactory,node_agentsession,node_claude,node_codex,node_diff,node_agentconfig,node_agenttarget,node_wizardtype toneRose
class node_registry,node_registryservice,node_remotesettings,node_ssh toneIndigo
```

## Components

### App and navigation

- [App state](https://github.com/shpigford/chops/blob/main/Chops/App/AppState.swift): `Chops/App/AppState.swift`
- [Main workspace](https://github.com/shpigford/chops/blob/main/Chops/App/ContentView.swift): `Chops/App/ContentView.swift`
- [Browse sidebar](https://github.com/shpigford/chops/blob/main/Chops/Views/Sidebar/SidebarView.swift): `Chops/Views/Sidebar/SidebarView.swift`
- [Skill and agent list](https://github.com/shpigford/chops/blob/main/Chops/Views/Sidebar/SkillListView.swift): `Chops/Views/Sidebar/SkillListView.swift`

### Discovery and storage

- [Local and remote scanner](https://github.com/shpigford/chops/blob/main/Chops/Services/SkillScanner.swift): `Chops/Services/SkillScanner.swift`
- [Tool definitions](https://github.com/shpigford/chops/blob/main/Chops/Models/ToolSource.swift): `Chops/Models/ToolSource.swift`
- [Skill parser](https://github.com/shpigford/chops/blob/main/Chops/Services/SkillParser.swift): `Chops/Services/SkillParser.swift`
- [Frontmatter parser](https://github.com/shpigford/chops/blob/main/Chops/Utilities/FrontmatterParser.swift): `Chops/Utilities/FrontmatterParser.swift`
- [Cursor MDC parser](https://github.com/shpigford/chops/blob/main/Chops/Utilities/MDCParser.swift): `Chops/Utilities/MDCParser.swift`
- [File watcher](https://github.com/shpigford/chops/blob/main/Chops/Services/FileWatcher.swift): `Chops/Services/FileWatcher.swift`
- [Full-text search](https://github.com/shpigford/chops/blob/main/Chops/Services/SearchService.swift): `Chops/Services/SearchService.swift`
- [Skill records](https://github.com/shpigford/chops/blob/main/Chops/Models/Skill.swift): `Chops/Models/Skill.swift`
- [Collections](https://github.com/shpigford/chops/blob/main/Chops/Models/Collection.swift): `Chops/Models/Collection.swift`

### Editing and creation

- [Skill detail](https://github.com/shpigford/chops/blob/main/Chops/Views/Detail/SkillDetailView.swift): `Chops/Views/Detail/SkillDetailView.swift`
- [Skill editor](https://github.com/shpigford/chops/blob/main/Chops/Views/Detail/SkillEditorView.swift): `Chops/Views/Detail/SkillEditorView.swift`
- [Create skill or agent](https://github.com/shpigford/chops/blob/main/Chops/Views/Shared/NewSkillSheet.swift): `Chops/Views/Shared/NewSkillSheet.swift`

### Agent composition

- [Agent composition](https://github.com/shpigford/chops/blob/main/Chops/Views/Shared/ComposePanel.swift): `Chops/Views/Shared/ComposePanel.swift`
- [Prompt templates](https://github.com/shpigford/chops/blob/main/Chops/Services/TemplateManager.swift): `Chops/Services/TemplateManager.swift`
- [Agent factory](https://github.com/shpigford/chops/blob/main/Chops/Services/Agents/AgentFactory.swift): `Chops/Services/Agents/AgentFactory.swift`
- [Agent session](https://github.com/shpigford/chops/blob/main/Chops/Services/Agents/AgentSession.swift): `Chops/Services/Agents/AgentSession.swift`
- [Claude CLI agent](https://github.com/shpigford/chops/blob/main/Chops/Services/Agents/Claude/ClaudeCLIAgent.swift): `Chops/Services/Agents/Claude/ClaudeCLIAgent.swift`
- [Codex CLI agent](https://github.com/shpigford/chops/blob/main/Chops/Services/Agents/Codex/CodexCLIAgent.swift): `Chops/Services/Agents/Codex/CodexCLIAgent.swift`
- [Diff review](https://github.com/shpigford/chops/blob/main/Chops/Views/Shared/DiffReviewPanel.swift): `Chops/Views/Shared/DiffReviewPanel.swift`
- [Agent configuration](https://github.com/shpigford/chops/blob/main/Chops/Models/AgentConfiguration.swift): `Chops/Models/AgentConfiguration.swift`
- [Agent targets](https://github.com/shpigford/chops/blob/main/Chops/Models/AgentTarget.swift): `Chops/Models/AgentTarget.swift`
- [Wizard templates](https://github.com/shpigford/chops/blob/main/Chops/Models/WizardTemplateType.swift): `Chops/Models/WizardTemplateType.swift`

### External integrations

- [Skills registry](https://github.com/shpigford/chops/blob/main/Chops/Views/Shared/RegistrySheet.swift): `Chops/Views/Shared/RegistrySheet.swift`
- [Registry client](https://github.com/shpigford/chops/blob/main/Chops/Services/SkillRegistry.swift): `Chops/Services/SkillRegistry.swift`
- [Remote server setup](https://github.com/shpigford/chops/blob/main/Chops/Views/Settings/RemoteServersSettingsView.swift): `Chops/Views/Settings/RemoteServersSettingsView.swift`
- [SSH operations](https://github.com/shpigford/chops/blob/main/Chops/Services/SSHService.swift): `Chops/Services/SSHService.swift`

### Other components

- **User**
- **Remote server**

## Connections

- User → Main workspace: uses
- Main workspace → App state: reads state (evidence: `Chops/App/ContentView.swift`)
- Main workspace → Browse sidebar: renders (evidence: `Chops/App/ContentView.swift`)
- Main workspace → Skill and agent list: renders (evidence: `Chops/App/ContentView.swift`)
- Main workspace → Local and remote scanner: starts scan (evidence: `Chops/App/ContentView.swift`)
- Main workspace → File watcher: starts watching (evidence: `Chops/App/ContentView.swift`)
- File watcher → Local and remote scanner: triggers rescan
- Local and remote scanner → Tool definitions: scans paths (evidence: `Chops/Services/SkillScanner.swift`)
- Local and remote scanner → Skill parser: parses files (evidence: `Chops/Services/SkillScanner.swift`)
- Skill parser → Frontmatter parser: dispatches parsing
- Skill parser → Cursor MDC parser: dispatches parsing (evidence: `Chops/Utilities/MDCParser.swift`)
- Local and remote scanner → Skill records: upserts records (evidence: `Chops/Services/SkillScanner.swift`)
- Local and remote scanner → SSH operations: syncs remote skills (evidence: `Chops/Services/SkillScanner.swift`)
- SSH operations → Remote server: runs commands (evidence: `Chops/Services/SSHService.swift`)
- Remote server setup → SSH operations: tests connection (evidence: `Chops/Views/Settings/RemoteServersSettingsView.swift`)
- Remote server setup → Local and remote scanner: requests sync (evidence: `Chops/Views/Settings/RemoteServersSettingsView.swift`)
- Browse sidebar → Skill and agent list: selects items (evidence: `Chops/Views/Sidebar/SidebarView.swift`)
- Skill and agent list → Full-text search: searches items
- User → Skill detail: opens item
- Skill detail → Skill editor: shows editor (evidence: `Chops/Views/Detail/SkillDetailView.swift`)
- Skill editor → Skill records: saves changes
- User → Create skill or agent: creates item
- User → Skills registry: discovers skills
- Skills registry → Registry client: searches registry (evidence: `Chops/Views/Shared/RegistrySheet.swift`)
- User → Agent composition: requests edits
- Agent composition → Prompt templates: builds prompt (evidence: `Chops/Views/Shared/ComposePanel.swift`)
- Agent composition → Agent factory: creates agent (evidence: `Chops/Views/Shared/ComposePanel.swift`)
- Agent factory → Claude CLI agent: selects implementation (evidence: `Chops/Services/Agents/AgentFactory.swift`)
- Agent factory → Codex CLI agent: selects implementation (evidence: `Chops/Services/Agents/AgentFactory.swift`)
- Claude CLI agent → Agent session: implements session (evidence: `Chops/Services/Agents/Claude/ClaudeCLIAgent.swift`)
- Codex CLI agent → Agent session: implements session (evidence: `Chops/Services/Agents/Codex/CodexCLIAgent.swift`)
- Agent composition → Agent session: drives session (evidence: `Chops/Views/Shared/ComposePanel.swift`)
- Agent composition → Diff review: reviews proposal (evidence: `Chops/Views/Shared/ComposePanel.swift`)
- Agent composition → Agent configuration: loads configuration (evidence: `Chops/Views/Shared/ComposePanel.swift`)
- Agent composition → Wizard templates: selects template (evidence: `Chops/Views/Shared/ComposePanel.swift`)
- Skills registry → Agent targets: targets installs (evidence: `Chops/Views/Shared/RegistrySheet.swift`)