cwtch: Instructions file for Claude Code

CLAUDE.md - cwtch

Overview

cwtch (Welsh: "cuddle/cozy nook") — Manage Claude Code profiles and sync configuration from Git.

Note: This project is not affiliated with, sponsored by, or endorsed by Anthropic PBC.

Platform: macOS only (tested on macOS Tahoe). Uses macOS Keychain for credential storage.

Tech Stack

• Language: Bash
• Platform: macOS (requires security command for Keychain access)
• Dependencies: jq for JSON parsing, yq for YAML parsing
• Standards: Doctrine Shell Guide

Repository Structure

cwtch/
├── .github/
│   └── workflows/ci.yml    # GitHub Actions CI (lint, test, e2e)
├── bin/
│   └── cwtch               # Main CLI entry point
├── lib/
│   ├── common.sh           # Shared functions, profile management
│   ├── config.sh           # Cwtchfile parsing and validation
│   └── sync.sh             # Git sync and namespace linking
├── scripts/
│   └── install.sh          # Manual installer
├── tests/
│   ├── helpers.bash        # Shared test utilities
│   ├── cwtch.bats          # Top-level CLI tests
│   ├── profile.bats        # Profile management tests
│   ├── config.bats         # Cwtchfile validation tests
│   └── sync.bats           # Sync functionality tests
└── docs/
    ├── profiles.md         # Profile management reference
    └── configuration.md    # Cwtchfile and sync reference

Architecture

Core Concepts

1. Profiles are thin — Store only credentials (.credential or .apikey)
2. Configuration is declarative — Defined in ~/.cwtch/Cwtchfile
3. Sources merge via namespaces — Multiple repos coexist as /namespace/command
4. Symlinks for instant updates — No copying, just linking

Directory Layout

~/.cwtch/
├── Cwtchfile              # Configuration (YAML)
├── .current               # Current profile name
├── profiles/{name}/       # Credentials only
│   └── .credential        # OAuth token (chmod 600)
└── sources/{repo}/        # Cloned repositories

~/.claude/                 # Built by cwtch sync
├── settings.json          # Merged settings
├── CLAUDE.md              # Symlink → source
├── commands/{namespace}/  # Symlink → source
├── agents/{namespace}/    # Symlink → source
└── hooks/{namespace}/     # Symlink → source