Metadata-Version: 2.4
Name: lac-py
Version: 2025.5.15
Summary: A CLI for managing AI agent config files without committing them to the repo.
Project-URL: Homepage, https://github.com/2ykwang/lac
Project-URL: Repository, https://github.com/2ykwang/lac
Project-URL: Issues, https://github.com/2ykwang/lac/issues
Project-URL: Changelog, https://github.com/2ykwang/lac/blob/main/CHANGELOG.md
Author-email: Youngkwang Yang <me@youngkwang.dev>
License: MIT
License-File: LICENSE
Keywords: ai-agent,claude-code,cli,codex,config,cursor
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.0
Requires-Dist: rich-click>=1.7
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# lac

A CLI for managing AI agent config files without committing them to the repo.

```
  machine A                          machine B
  ─────────                          ─────────
  ~/repo/CLAUDE.md (untracked)       ~/repo/CLAUDE.md (untracked)
        │                                   │
        └─→  lac storage  ←─────────────────┘
              (git push/pull)
```

## Highlights

- **Untracked by design**: CLAUDE.md, AGENTS.md, .cursorrules, .mcp.json live in lac storage and are symlinked into each repo. Links are automatically excluded from git.
- **Portable across machines**: lac storage is itself a git repo — push it to a private remote, clone elsewhere, and re-register your repos.
- **Per-repo identity**: each repo gets its own storage directory, matched by git remote URL or path. The same repo on two machines maps to the same storage.
- **Agent config files**: CLAUDE.md / AGENTS.md / .claude/ / .agents/ / .cursorrules / .mcp.json. Add custom files with `lac link <name>`.

## Use cases

AI agent config files (CLAUDE.md, AGENTS.md, .cursorrules, .mcp.json) are sometimes shared, sometimes personal. Open-source projects can't always agree on agent rules; teams under code review may disagree on what belongs in the repo; even on solo repos you might want personal tweaks that don't pollute commits. In all these cases the config stays untracked — and lac keeps the canonical copy in one place that travels with you across machines.

## How it works

### Lifecycle

```
$ lac register      → storage directory + metadata (no files touched yet)
$ lac link --all    → agent config files copied to storage
                       symlinks created in the repo
                       auto-excluded from git
$ ... (work)        → edit anywhere — there's only one source
$ lac unregister    → files restored in the repo + storage kept as backup
```

### Agent config files

The set lac knows about by default:

- CLAUDE.md
- AGENTS.md
- .claude/
- .agents/
- .cursorrules
- .mcp.json

Add anything else with `lac link <filename>`.

### Cross-machine sync

lac storage is a git repo. To use the same config on another machine:

```bash
# on machine A — initial push
cd "$(lac home)"
git remote add origin <your-private-remote-url>
git add . && git commit -m "initial" && git push -u origin main

# on machine B — clone and reuse
git clone <your-private-remote-url> "$(lac home)"
cd ~/projects/repo
lac register   # matched by git remote URL (or path)
lac link --all
```

The match between machines happens via the repo's git remote URL when available, or by the repo's path otherwise.

## Install

```bash
brew install 2ykwang/2ykwang/lac
lac --version
# lac, version 2025.5.15
```

## Quick Start

In any git repo:

```bash
cd ~/projects/my-project

lac register
# ✓ registered at /Users/x/.local/share/lac/my-project-abc123
# ℹ run 'lac link' to link agent config files in this repo

lac link --all
# ✓ CLAUDE.md linked
# ✓ AGENTS.md linked
# ✓ .claude linked
# ✓ .agents linked
# ✓ .cursorrules linked
# ✓ .mcp.json linked
```

## Commands

| Command | What it does |
|---|---|
| `lac register` | Register the current repo with lac storage. |
| `lac link` | Interactive checkbox — pick which files to link. |
| `lac link --all` | Link all agent config files at once. |
  
| `lac link <file>` | Link a single file by name (custom or known). |
| `lac status` | Show registration state of the current repo. |
| `lac doctor` | Check storage health (broken symlinks, orphaned entries, missing targets). |
| `lac list` | List all registered repos. |
| `lac unregister` | Restore files into the repo and back up the storage. |
| `lac home` | Print the lac storage root. |
| `lac path [file]` | Print storage path for the repo (or a file inside it). |
| `lac rename <name>` | Rename the current repo's storage directory. |

## Limits

- macOS and Linux only. Windows is not supported.
- Python ≥3.11.
- Single-user tool. Not designed for team-shared lac storage.
- Git-tracked files in the repo are skipped during link; lac never overwrites them.
- Cross-machine sync of lac storage is manual (`git push` / `git pull`); lac does not auto-sync.

## License

MIT
