Content
# Claude Config
A native macOS app for viewing and editing every configuration
surface that Claude Code reads from your machine — `settings.json`
across all four scopes, MCP servers, slash commands, subagents,
`CLAUDE.md` instruction files — in one place, with a pure SwiftUI
Liquid Glass interface that targets macOS 26 (Tahoe).
The intent is to give Claude Code power users a clear, safe way to
inspect and modify their config without grepping through scattered
JSON files or remembering which scope wins which precedence battle.
Every edit is atomic, every save is backed up, and every change can
be reverted from the in-app history viewer.
## Features
### Settings (`settings.json`)
- **All four scopes** auto-discovered and listed in the sidebar:
User Global, User Local, Project Global, Project Local.
- **Annotated view** — every key from the catalog rendered as a
card with summary, description, "affects" line, examples, and the
current value pulled live from disk. Shows status (`set` / `not
set`) and tags any uncovered keys for follow-up.
- **Raw view** — JSON pretty-printed with monospaced editing,
smart-quote / dash auto-correct disabled so paste-edit-save round-
trips don't silently corrupt the file.
- **Edit mode** with Save / Revert / Cancel pills in the toolbar.
Save is bolded as the primary action; Revert is keyboard
shortcut-aware (Esc).
- **Search** — floating search field in the toolbar filters the
annotated rows by key, summary, description, or category.
- **History** — every save snapshots the previous version into a
per-file folder under
`~/Library/Application Support/ClaudeConfig/history/`. Click the
clock icon in the toolbar to diff and restore.
- **External-change protection** — mtime-based stale-write check
on every save; refuses to overwrite a file that's been modified
externally since the editor opened.
- **Source-controlled badge** for project-global files so you know
saving will dirty your repo's working tree.
### CLAUDE.md
- User-scope (`~/.claude/CLAUDE.md`) and project-scope
(`<project>/.claude/CLAUDE.md`) listed in the sidebar.
- Plain-text editor (smart-quote disabled) with the same
Save / Revert / Trash flow as the JSON editors.
- Trash button is destructive-confirmed and archives the previous
version to history before deleting.
### MCP Servers (`.mcp.json`)
- One entry per project listed under the project's sidebar group.
- Form-based editor for each server: name, command, args, env vars.
- Add / remove server controls inline.
- Trash button to delete the entire `.mcp.json` (with confirmation).
### Slash Commands & Subagents
- Auto-discovers `~/.claude/commands/*.md` and `~/.claude/agents/*.md`
for user scope, and the same paths under each project's `.claude/`
for project scope.
- Markdown editor with frontmatter parsing — `name`, `description`,
`tools`, `model` rendered as a structured form above the body.
- Create-new sheet, in-place edit, delete with history archive.
### Reference Surfaces
- **Cheat Sheet** — reference card for "where configs live", the
precedence order Claude Code applies, and a live feed of known
bugs sourced from `anthropics/claude-code` GitHub issues. The
issues panel caches with a TTL so the app doesn't hit the API on
every refresh.
- **Templates** — curated presets you can apply to a project's
`settings.json` with one click.
- **Effective Settings** — merged view that shows the resolved
value for every catalog key after the four scopes are layered,
so you can see what Claude Code is *actually* using without
doing the precedence math in your head.
- **Diagnose** — per-project static checks: missing CLAUDE.md, no
permissions, conflicting hooks, etc. Severity-tagged.
## Liquid Glass UI
- Floating Liquid Glass capsule pills in the macOS window toolbar
for every view's contextual actions (Annotated / Raw toggle,
Search, History, Edit / Save / Revert, Trash). Trailing-aligned
via `ToolbarSpacer(.flexible)`. Active state on the Annotated /
Raw selector uses an accent-tinted capsule with white text.
- Soft scroll-edge fade so list content gracefully fades behind
the toolbar instead of hard-clipping at its boundary. Scrollbar
is offset below the fade zone so its top isn't faded out at
rest.
- Sidebar selection / hover state matches Apple's auto-inversion
pattern — primary text turns white on selection without manual
state management or animation hacks.
- App icon: white Claude symbol on a Zoho-color radial-burst
squircle (red / yellow / green / blue corners over a warm cream
base), generated by `release/build-icon.sh`.
## Project Discovery
- Auto-finds projects in your `~/Documents/dev/...` family (any
folder containing a `.claude/` subdirectory).
- Add-Project picker for folders outside the auto-discovery roots.
- Refresh on app activation picks up files modified outside the
app since you last viewed them.
## Architecture
Four Swift Package Manager targets:
| Target | Role |
| --------------- | ---------------------------------------------------- |
| `ConfigCore` | Models, file I/O, atomic writes, backup store |
| `ConfigCatalog` | Bundled JSON catalog of every documented setting |
| `ConfigUI` | Every SwiftUI view, design tokens, the icon SVG |
| `ConfigApp` | `@main` executable, app delegate, `WindowGroup` |
Stack: Swift 6 / `swift-tools-version: 6.0`, SwiftUI on macOS 26
(Tahoe), `@Observable` + `@Bindable` for state, `@AppStorage` for
user preferences. No third-party dependencies.
## Running locally
```sh
swift run ClaudeConfig
```
Requires Xcode 16 or the matching Swift 6 / macOS 26 SDK
command-line tools.
## Distribution
Two paths, depending on your audience:
### Internal team (no Apple Developer Program)
```sh
./release/build-icon.sh # one-time, when icon design changes
./release/build-unsigned.sh # produces dist/ClaudeConfig.zip
```
Send the zip plus `release/INSTALL.txt` to recipients. They drag the
app to `/Applications` and run one `xattr -dr com.apple.quarantine`
command to clear Gatekeeper. See `release/INSTALL.txt` for the full
recipient-facing instructions.
### Public / wider distribution
Requires a paid Apple Developer Program membership.
```sh
./release/build-app.sh # signed with Developer ID
./release/notarize.sh # submits to Apple's notarytool, staples
```
Full setup (cert, app-specific password, `notarytool store-credentials`)
is documented in [`RELEASE.md`](./RELEASE.md).
## File layout
```
.
├── Package.swift
├── README.md # this file
├── RELEASE.md # signed/notarized build flow
├── Sources/
│ ├── ConfigCore/ # models, I/O, history
│ ├── ConfigCatalog/ # bundled catalog.json
│ ├── ConfigUI/ # SwiftUI views, DesignTokens
│ └── ConfigApp/ # @main + AppDelegate
└── release/
├── build-app.sh # signed build (Developer ID)
├── build-unsigned.sh # unsigned for internal use
├── build-icon.sh # generates AppIcon.icns
├── notarize.sh # Apple notarytool submit + staple
├── INSTALL.txt # recipient-facing install steps
├── Info.plist # bundle plist
├── entitlements.plist # codesign entitlements
└── AppIcon.icns # generated icon
```
## Status
v1.0 — fully functional for read + edit across every supported config
surface. macOS 26 (Tahoe) only.
