cram-ai 0.1.0__tar.gz

cram_ai-0.1.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: cram-ai
+Version: 0.1.0
+Summary: Cut AI coding token costs by 96-98% — curated context, MCP server, and tray app for AI coding tools
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/vishbay/cram-ai
+Project-URL: Repository, https://github.com/vishbay/cram-ai
+Project-URL: Bug Tracker, https://github.com/vishbay/cram-ai/issues
+Keywords: ai,llm,context,token,coding,claude,cursor,copilot
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: multi-provider
+Requires-Dist: litellm>=1.40.0; extra == "multi-provider"
+Provides-Extra: mac
+Requires-Dist: rumps>=0.4.0; extra == "mac"
+Provides-Extra: tray
+Requires-Dist: pystray>=0.19.0; extra == "tray"
+Requires-Dist: pillow>=10.0; extra == "tray"
+Requires-Dist: pywebview>=5.0; extra == "tray"
+Requires-Dist: flask>=3.0; extra == "tray"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# cram-ai
+
+> Slash AI coding token costs by injecting only what the model needs — nothing more.
+
+AI coding tools auto-index your entire repo at session start. That indexing generates **cache writes** — the most expensive token type (3–4× the cost of reads). cram-ai replaces auto-indexing with a small set of curated files that give the model exactly what it needs: repo structure, key decisions, and focused excerpts of only the files relevant to your current task.
+
+---
+
+## Benchmarks
+
+### cram-ai itself (31 source files, Python CLI tool)
+
+| | Tokens | Sonnet cost/session | Opus cost/session |
+|---|---|---|---|
+| **Without cram** — full repo auto-indexed | 49,683 | $0.186 | $0.932 |
+| **Without cram** — orientation set only¹ | 19,687 | $0.074 | $0.369 |
+| **With cram** — ARCHITECTURE + SYMBOLS + task context | 1,898 | $0.007 | $0.036 |
+
+**96% token reduction. $0.18 saved per session. $18 over 100 sessions (Sonnet).**
+
+---
+
+### pallets/flask (118 source files, Python web framework)
+
+| | Tokens | Sonnet cost/session | Opus cost/session |
+|---|---|---|---|
+| **Without cram** — full repo auto-indexed | 171,641 | $0.644 | $3.22 |
+| **Without cram** — orientation set only¹ | 60,863 | $0.228 | $1.14 |
+| **With cram** — ARCHITECTURE + SYMBOLS + task context | 5,929 | $0.022 | $0.111 |
+
+**96.5% token reduction. $0.62 saved per session. $62 over 100 sessions (Sonnet).**
+
+---
+
+### hoppscotch/hoppscotch (2,151 source files, TypeScript monorepo)
+
+| | Tokens | Sonnet cost/session |
+|---|---|---|
+| **Without cram** — full repo auto-indexed | 418,697 | $1.57 |
+| **With cram** | 7,239 | $0.027 |
+
+**98.3% reduction. $154 saved over 100 sessions (Sonnet).**
+
+---
+
+> ¹ *Orientation set = file tree + README + pyproject.toml/package.json + 5 largest source files. A realistic estimate for tools that don't index everything.*  
+> Pricing: Claude Sonnet 4.6 cache write $3.75/M, Opus 4.8 $18.75/M. Savings scale with team size and session frequency.
+
+---
+
+## How it works
+
+AI agents spend most tokens on **orientation** — finding relevant files, understanding structure, reading configs. cram-ai replaces that with a curated map the model reads instead of building itself.
+
+```
+your-repo/
+└── .cram-ai-context/
+    ├── ARCHITECTURE.md   ← repo structure, tech stack, key files (auto-generated by Haiku)
+    ├── DECISIONS.md      ← architectural decisions you want the AI to respect
+    ├── SYMBOLS.md        ← public function/class index across all source files (auto-generated)
+    └── CURRENT_TASK.md   ← per-session: task + focused excerpts of relevant files
+```
+
+**`SYMBOLS.md`** is the key accuracy improvement. Rather than asking a model to guess which files matter based on filenames alone, cram maps every source file to its public identifiers (`api/routes.py: handle_rate_limit, check_throttle, apply_backoff`). The model uses that map to select files *and* identify the exact functions to excerpt — so "fix the rate limiter" finds `check_throttle` even if the words don't match.
+
+`cram task "..."` runs before every session:
+
+1. **`[1/4]`** Loads `SYMBOLS.md` — 455 identifiers across 65 files, zero LLM calls
+2. **`[2/4]`** Sends architecture + symbol index to Haiku → model returns `path | RelevantFunc, OtherClass`
+3. **`[3/4]`** Extracts identifier-focused excerpts — only the lines that contain those functions, plus context window
+4. **`[4/4]`** Writes to your tool's instruction file, warns if below cache minimum for your model
+
+All stages stream live to the popup so you see exactly what's happening.
+
+---
+
+## Quick start
+
+```bash
+pip install cram-ai
+
+cd your-repo
+cram init                              # one-time setup — scans repo, generates docs, indexes symbols
+cram task "add login validation"       # run before every session
+# → context pre-loaded into your AI tool
+cram sync                              # run after every commit (or fires automatically via git hook)
+```
+
+**First command to context ready: under 60 seconds.**
+
+---
+
+## CLI commands
+
+| Command | When to run | What it does |
+|---|---|---|
+| `cram init` | Once per repo | Scans structure, generates `ARCHITECTURE.md` + `SYMBOLS.md` via Haiku |
+| `cram task "..."` | Before every session | Identifies relevant files by symbol, inlines focused excerpts |
+| `cram continue` | Mid-session before committing | Extends grace period — prevents context reset on mid-task commits |
+| `cram sync` | After every commit | Updates `ARCHITECTURE.md` + `SYMBOLS.md` from git diff |
+| `cram decide "..."` | When making arch choices | Appends a dated decision entry to `DECISIONS.md` |
+| `cram status` | Anytime | Shows `.cram-ai-context/` files and freshness |
+
+---
+
+## Provider support
+
+The tool is model-agnostic. Set `AICONTEXT_MODEL` to any provider:
+
+```bash
+# Claude CLI (default — works inside Claude Code with no API key)
+cram init
+
+# Anthropic SDK
+export ANTHROPIC_API_KEY=sk-...
+export AICONTEXT_MODEL=anthropic/claude-haiku-4-5-20251001
+cram init
+
+# OpenAI
+export OPENAI_API_KEY=sk-...
+export AICONTEXT_MODEL=openai/gpt-4o-mini
+cram init
+
+# Google Gemini
+export GEMINI_API_KEY=...
+export AICONTEXT_MODEL=gemini/gemini-2.0-flash
+cram init
+
+# Local (Ollama — free, no key needed)
+export AICONTEXT_MODEL=ollama/mistral
+cram init
+```
+
+Also supports: AWS Bedrock, GCP Vertex AI, Azure OpenAI, custom LiteLLM proxies — auto-discovered from env/credentials.
+
+---
+
+## Session discipline
+
+The context files handle orientation. These rules handle the rest:
+
+1. **Run `cram task "..."` before every session** — never let the model hunt for files itself.
+2. **Hard session boundary** — end the session the moment a feature works. New code = growing context = rising cost.
+3. **Mid-task commit?** Run `cram continue` first to extend the grace period.
+4. **Run `cram sync` after every commit** — keeps `ARCHITECTURE.md` and `SYMBOLS.md` accurate.
+5. **Architectural decision?** Run `cram decide "use Redis for sessions"` — keeps `DECISIONS.md` current without opening the file.
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `AICONTEXT_MODEL` | auto-detected | Model for context tasks — bare alias or `provider/model` |
+| `ANTHROPIC_API_KEY` | — | Anthropic API key (optional inside Claude Code) |
+| `AICONTEXT_MAX_FILES` | `5` | Max files inlined per task |
+| `AICONTEXT_MAX_LINES` | `300` | Max lines per ARCHITECTURE.md |
+| `AICONTEXT_MAX_EXCERPT_LINES` | `80` | Max lines excerpted per file in `CURRENT_TASK.md` |
+| `CRAM_TASK_GRACE_SECONDS` | `600` | Seconds after `cram task` before a commit resets context |
+
+---
+
+## Works with any AI coding tool
+
+| Tool | How context loads |
+|---|---|
+| **Claude Code** | Reads `.cram-ai-context/` recursively — all files auto-loaded |
+| **Cursor** | Writes to `.cursor/rules/cram-task.md` — auto-loaded by Cursor |
+| **Windsurf** | Writes to `.windsurf/rules/cram-task.md` — auto-loaded |
+| **Codex** | Writes to `.cram-ai-context/AGENTS.md` — auto-loaded |
+| **GitHub Copilot** | Writes to `.github/cram-task.md` — include once in `copilot-instructions.md` |
+
+For non-Claude tools, cram automatically prepends a compact architecture summary so the model has repo orientation even without recursive file loading.
+
+---
+
+## Running tests
+
+```bash
+pip install pytest
+pytest
+```
+
+57 passing tests, no API key required. All model calls are mocked.
+
+---
+
+## License
+
+MIT

cram_ai-0.1.0/README.md

@@ -0,0 +1,190 @@
+# cram-ai
+
+> Slash AI coding token costs by injecting only what the model needs — nothing more.
+
+AI coding tools auto-index your entire repo at session start. That indexing generates **cache writes** — the most expensive token type (3–4× the cost of reads). cram-ai replaces auto-indexing with a small set of curated files that give the model exactly what it needs: repo structure, key decisions, and focused excerpts of only the files relevant to your current task.
+
+---
+
+## Benchmarks
+
+### cram-ai itself (31 source files, Python CLI tool)
+
+| | Tokens | Sonnet cost/session | Opus cost/session |
+|---|---|---|---|
+| **Without cram** — full repo auto-indexed | 49,683 | $0.186 | $0.932 |
+| **Without cram** — orientation set only¹ | 19,687 | $0.074 | $0.369 |
+| **With cram** — ARCHITECTURE + SYMBOLS + task context | 1,898 | $0.007 | $0.036 |
+
+**96% token reduction. $0.18 saved per session. $18 over 100 sessions (Sonnet).**
+
+---
+
+### pallets/flask (118 source files, Python web framework)
+
+| | Tokens | Sonnet cost/session | Opus cost/session |
+|---|---|---|---|
+| **Without cram** — full repo auto-indexed | 171,641 | $0.644 | $3.22 |
+| **Without cram** — orientation set only¹ | 60,863 | $0.228 | $1.14 |
+| **With cram** — ARCHITECTURE + SYMBOLS + task context | 5,929 | $0.022 | $0.111 |
+
+**96.5% token reduction. $0.62 saved per session. $62 over 100 sessions (Sonnet).**
+
+---
+
+### hoppscotch/hoppscotch (2,151 source files, TypeScript monorepo)
+
+| | Tokens | Sonnet cost/session |
+|---|---|---|
+| **Without cram** — full repo auto-indexed | 418,697 | $1.57 |
+| **With cram** | 7,239 | $0.027 |
+
+**98.3% reduction. $154 saved over 100 sessions (Sonnet).**
+
+---
+
+> ¹ *Orientation set = file tree + README + pyproject.toml/package.json + 5 largest source files. A realistic estimate for tools that don't index everything.*  
+> Pricing: Claude Sonnet 4.6 cache write $3.75/M, Opus 4.8 $18.75/M. Savings scale with team size and session frequency.
+
+---
+
+## How it works
+
+AI agents spend most tokens on **orientation** — finding relevant files, understanding structure, reading configs. cram-ai replaces that with a curated map the model reads instead of building itself.
+
+```
+your-repo/
+└── .cram-ai-context/
+    ├── ARCHITECTURE.md   ← repo structure, tech stack, key files (auto-generated by Haiku)
+    ├── DECISIONS.md      ← architectural decisions you want the AI to respect
+    ├── SYMBOLS.md        ← public function/class index across all source files (auto-generated)
+    └── CURRENT_TASK.md   ← per-session: task + focused excerpts of relevant files
+```
+
+**`SYMBOLS.md`** is the key accuracy improvement. Rather than asking a model to guess which files matter based on filenames alone, cram maps every source file to its public identifiers (`api/routes.py: handle_rate_limit, check_throttle, apply_backoff`). The model uses that map to select files *and* identify the exact functions to excerpt — so "fix the rate limiter" finds `check_throttle` even if the words don't match.
+
+`cram task "..."` runs before every session:
+
+1. **`[1/4]`** Loads `SYMBOLS.md` — 455 identifiers across 65 files, zero LLM calls
+2. **`[2/4]`** Sends architecture + symbol index to Haiku → model returns `path | RelevantFunc, OtherClass`
+3. **`[3/4]`** Extracts identifier-focused excerpts — only the lines that contain those functions, plus context window
+4. **`[4/4]`** Writes to your tool's instruction file, warns if below cache minimum for your model
+
+All stages stream live to the popup so you see exactly what's happening.
+
+---
+
+## Quick start
+
+```bash
+pip install cram-ai
+
+cd your-repo
+cram init                              # one-time setup — scans repo, generates docs, indexes symbols
+cram task "add login validation"       # run before every session
+# → context pre-loaded into your AI tool
+cram sync                              # run after every commit (or fires automatically via git hook)
+```
+
+**First command to context ready: under 60 seconds.**
+
+---
+
+## CLI commands
+
+| Command | When to run | What it does |
+|---|---|---|
+| `cram init` | Once per repo | Scans structure, generates `ARCHITECTURE.md` + `SYMBOLS.md` via Haiku |
+| `cram task "..."` | Before every session | Identifies relevant files by symbol, inlines focused excerpts |
+| `cram continue` | Mid-session before committing | Extends grace period — prevents context reset on mid-task commits |
+| `cram sync` | After every commit | Updates `ARCHITECTURE.md` + `SYMBOLS.md` from git diff |
+| `cram decide "..."` | When making arch choices | Appends a dated decision entry to `DECISIONS.md` |
+| `cram status` | Anytime | Shows `.cram-ai-context/` files and freshness |
+
+---
+
+## Provider support
+
+The tool is model-agnostic. Set `AICONTEXT_MODEL` to any provider:
+
+```bash
+# Claude CLI (default — works inside Claude Code with no API key)
+cram init
+
+# Anthropic SDK
+export ANTHROPIC_API_KEY=sk-...
+export AICONTEXT_MODEL=anthropic/claude-haiku-4-5-20251001
+cram init
+
+# OpenAI
+export OPENAI_API_KEY=sk-...
+export AICONTEXT_MODEL=openai/gpt-4o-mini
+cram init
+
+# Google Gemini
+export GEMINI_API_KEY=...
+export AICONTEXT_MODEL=gemini/gemini-2.0-flash
+cram init
+
+# Local (Ollama — free, no key needed)
+export AICONTEXT_MODEL=ollama/mistral
+cram init
+```
+
+Also supports: AWS Bedrock, GCP Vertex AI, Azure OpenAI, custom LiteLLM proxies — auto-discovered from env/credentials.
+
+---
+
+## Session discipline
+
+The context files handle orientation. These rules handle the rest:
+
+1. **Run `cram task "..."` before every session** — never let the model hunt for files itself.
+2. **Hard session boundary** — end the session the moment a feature works. New code = growing context = rising cost.
+3. **Mid-task commit?** Run `cram continue` first to extend the grace period.
+4. **Run `cram sync` after every commit** — keeps `ARCHITECTURE.md` and `SYMBOLS.md` accurate.
+5. **Architectural decision?** Run `cram decide "use Redis for sessions"` — keeps `DECISIONS.md` current without opening the file.
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `AICONTEXT_MODEL` | auto-detected | Model for context tasks — bare alias or `provider/model` |
+| `ANTHROPIC_API_KEY` | — | Anthropic API key (optional inside Claude Code) |
+| `AICONTEXT_MAX_FILES` | `5` | Max files inlined per task |
+| `AICONTEXT_MAX_LINES` | `300` | Max lines per ARCHITECTURE.md |
+| `AICONTEXT_MAX_EXCERPT_LINES` | `80` | Max lines excerpted per file in `CURRENT_TASK.md` |
+| `CRAM_TASK_GRACE_SECONDS` | `600` | Seconds after `cram task` before a commit resets context |
+
+---
+
+## Works with any AI coding tool
+
+| Tool | How context loads |
+|---|---|
+| **Claude Code** | Reads `.cram-ai-context/` recursively — all files auto-loaded |
+| **Cursor** | Writes to `.cursor/rules/cram-task.md` — auto-loaded by Cursor |
+| **Windsurf** | Writes to `.windsurf/rules/cram-task.md` — auto-loaded |
+| **Codex** | Writes to `.cram-ai-context/AGENTS.md` — auto-loaded |
+| **GitHub Copilot** | Writes to `.github/cram-task.md` — include once in `copilot-instructions.md` |
+
+For non-Claude tools, cram automatically prepends a compact architecture summary so the model has repo orientation even without recursive file loading.
+
+---
+
+## Running tests
+
+```bash
+pip install pytest
+pytest
+```
+
+57 passing tests, no API key required. All model calls are mocked.
+
+---
+
+## License
+
+MIT

cram_ai-0.1.0/cram/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

cram_ai-0.1.0/cram/__main__.py

@@ -0,0 +1,2 @@
+from cram.cli import main
+main()

cram_ai-0.1.0/cram/add_context.py

@@ -0,0 +1,143 @@
+"""cram add — append extra files to the current session context."""
+
+from __future__ import annotations
+import os
+import re
+import sys
+
+CONTEXT_DIR = '.cram-ai-context'
+
+
+def _read_task_text(content: str) -> str:
+    m = re.search(r'## Task\n(.+?)(?=\n##|\Z)', content, re.DOTALL)
+    return m.group(1).strip() if m else ''
+
+
+def _task_keywords(task_text: str) -> list[str]:
+    stop = {
+        'add', 'fix', 'the', 'a', 'an', 'to', 'in', 'for', 'of', 'and', 'or',
+        'with', 'from', 'that', 'this', 'it', 'is', 'on', 'at', 'by', 'be',
+        'update', 'make', 'create', 'change', 'use', 'get', 'set', 'run', 'into',
+        'new', 'old', 'all', 'not', 'its', 'has',
+    }
+    words = re.findall(r'[A-Za-z][A-Za-z0-9_]*', task_text)
+    return [w for w in words if len(w) > 2 and w.lower() not in stop]
+
+
+def _replace_section(content: str, resolved: str, ext: str, excerpt: str) -> str:
+    pattern = r'\n### ' + re.escape(resolved) + r'\n```[^\n]*\n.*?\n```'
+    replacement = f'\n### {resolved}\n```{ext}\n{excerpt}\n```'
+    result, n = re.subn(pattern, replacement, content, flags=re.DOTALL)
+    return result if n else content
+
+
+def add_files(
+    file_specs: list[str],
+    replace: bool = False,
+    target: str | None = None,
+) -> bool:
+    from cram.find_context import _extract_excerpt, _resolve_path
+    from cram.utils import find_git_root as _find_git_root
+    from cram import targets as _targets
+
+    task_path = os.path.join(CONTEXT_DIR, 'CURRENT_TASK.md')
+    if not os.path.exists(task_path):
+        print('Error: no active session. Run `cram task "..."` first.', file=sys.stderr)
+        return False
+
+    with open(task_path) as f:
+        current = f.read()
+
+    keywords = _task_keywords(_read_task_text(current))
+    existing = set(re.findall(r'^### (.+)$', current, re.MULTILINE))
+
+    changed = False
+
+    for spec in file_specs:
+        # Support "path/file.py | Func1, Func2" for explicit identifier targeting
+        if '|' in spec:
+            path_part, id_part = spec.split('|', 1)
+            fpath = path_part.strip()
+            ids   = [i.strip() for i in id_part.split(',') if i.strip()]
+        else:
+            fpath = spec.strip()
+            ids   = keywords  # use current task's keywords as focus hints
+
+        resolved = _resolve_path(fpath)
+
+        if not os.path.exists(resolved):
+            print(f'  ✗  {fpath}  — not found')
+            continue
+
+        if resolved in existing and not replace:
+            print(f'  !  {resolved}  — already in context (use --replace to update)')
+            continue
+
+        ext     = os.path.splitext(resolved)[1].lstrip('.')
+        excerpt = _extract_excerpt(resolved, ids)
+        tok     = len(excerpt) // 4
+
+        if resolved in existing:
+            current = _replace_section(current, resolved, ext, excerpt)
+            print(f'  ↺  {resolved}  ~{tok:,} tokens  (updated)')
+        else:
+            current += f'\n### {resolved}\n```{ext}\n{excerpt}\n```\n'
+            print(f'  +  {resolved}  ~{tok:,} tokens')
+
+        changed = True
+
+    if not changed:
+        return False
+
+    with open(task_path, 'w') as f:
+        f.write(current)
+
+    total = len(current) // 4
+    print(f'\n  Total context: ~{total:,} tokens')
+
+    root = _find_git_root(os.getcwd())
+    eff_target = target if target is not None else _targets.load_default_target(root)
+    if eff_target:
+        arch_path = os.path.join(CONTEXT_DIR, 'ARCHITECTURE.md')
+        arch = open(arch_path).read() if os.path.exists(arch_path) else ''
+        if eff_target == 'all':
+            for p in _targets.write_to_all_detected(root, current, arch):
+                print(f'  → {os.path.relpath(p)}')
+        else:
+            path = _targets.write_to_target(root, eff_target, current, arch)
+            print(f'  → {os.path.relpath(path)}')
+
+    return True
+
+
+def main() -> None:
+    import argparse
+    from cram.utils import find_git_root
+    from cram import targets as _targets
+
+    parser = argparse.ArgumentParser(
+        prog='cram add',
+        description='Append files to the current session context',
+    )
+    parser.add_argument(
+        'files', nargs='+',
+        help='Files to add. Quote "path | Func1, Func2" to focus on specific identifiers.',
+    )
+    parser.add_argument('--replace', action='store_true',
+                        help='Replace the excerpt if the file is already in context')
+    parser.add_argument('--target',
+                        choices=[*_targets.TARGET_FILES, 'all'],
+                        default=None, metavar='TARGET')
+    parser.add_argument('--path', default=None, metavar='REPO_PATH')
+    args = parser.parse_args()
+
+    start = os.path.abspath(args.path) if args.path else os.getcwd()
+    root  = find_git_root(start)
+
+    if not os.path.isdir(os.path.join(root, CONTEXT_DIR)):
+        print(f'Error: {CONTEXT_DIR}/ not found in {root}.', file=sys.stderr)
+        sys.exit(1)
+
+    os.chdir(root)
+    ok = add_files(args.files, replace=args.replace, target=args.target)
+    sys.exit(0 if ok else 1)

cram_ai-0.1.0/cram/autostart.py

@@ -0,0 +1,115 @@
+"""Install or remove a macOS LaunchAgent that starts cram-menu at login."""
+
+from __future__ import annotations
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+_LABEL    = 'ai.cram.menu'
+_PLIST    = Path.home() / 'Library' / 'LaunchAgents' / f'{_LABEL}.plist'
+
+
+def _cram_menu_bin() -> str:
+    """Return the absolute path to the cram-menu binary."""
+    # Prefer the binary in the same venv as this interpreter
+    candidate = Path(sys.executable).parent / 'cram-menu'
+    if candidate.exists():
+        return str(candidate)
+    found = shutil.which('cram-menu')
+    if found:
+        return found
+    raise RuntimeError(
+        "cram-menu binary not found. "
+        "Install with: pip install 'cram-ai[tray]'"
+    )
+
+
+def install(repo_path: str | None = None) -> None:
+    from cram.utils import find_git_root
+    repo = find_git_root(repo_path or os.getcwd())
+
+    binary = _cram_menu_bin()
+
+    plist = f"""\
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>             <string>{_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>{binary}</string>
+        <string>{repo}</string>
+    </array>
+    <key>RunAtLoad</key>         <true/>
+    <key>KeepAlive</key>         <false/>
+    <key>StandardOutPath</key>   <string>{Path.home()}/.config/cram-ai/cram-menu.log</string>
+    <key>StandardErrorPath</key> <string>{Path.home()}/.config/cram-ai/cram-menu.log</string>
+</dict>
+</plist>
+"""
+    Path.home().joinpath('.config', 'cram-ai').mkdir(parents=True, exist_ok=True)
+    _PLIST.parent.mkdir(parents=True, exist_ok=True)
+    _PLIST.write_text(plist)
+
+    # Load immediately (also activates on next login)
+    subprocess.run(['launchctl', 'load', str(_PLIST)], check=False)
+
+    print(f"cram-menu will now start automatically at login.")
+    print(f"Repo: {repo}")
+    print(f"Plist: {_PLIST}")
+    print(f"\nTo stop: cram autostart off")
+
+
+def uninstall() -> None:
+    if _PLIST.exists():
+        subprocess.run(['launchctl', 'unload', str(_PLIST)], check=False)
+        _PLIST.unlink()
+        print(f"Removed {_PLIST}")
+        print("cram-menu will no longer start at login.")
+    else:
+        print("No autostart entry found.")
+
+
+def status() -> None:
+    if _PLIST.exists():
+        result = subprocess.run(
+            ['launchctl', 'list', _LABEL],
+            capture_output=True, text=True,
+        )
+        running = result.returncode == 0
+        print(f"Autostart: installed ({'running' if running else 'not currently running'})")
+        print(f"Plist:     {_PLIST}")
+    else:
+        print("Autostart: not installed")
+
+
+def main() -> None:
+    if sys.platform != 'darwin':
+        print(
+            "cram autostart is currently macOS-only.\n"
+            "Windows: add cram-menu to the Startup folder.\n"
+            "Linux:   add to ~/.config/autostart/ or your WM's autostart.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    action = sys.argv[1] if len(sys.argv) > 1 else 'on'
+    path   = sys.argv[2] if len(sys.argv) > 2 else None
+
+    if action in ('on', 'install', 'enable'):
+        install(path)
+    elif action in ('off', 'uninstall', 'disable'):
+        uninstall()
+    elif action in ('status',):
+        status()
+    else:
+        print(f"Usage: cram autostart [on|off|status] [repo_path]")
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()