cam/README.md

# CAM — Cursor Agents Manager

**Version:** 0.1.0  
**Status:** in development  
**License:** [MIT](LICENSE)

CAM exports and imports [Cursor](https://cursor.com) agent conversation transcripts so you can version them in a project repository and move context between workstations.

Repository: <https://git.p7net.ru/tools/cam.git>

## Why

Cursor stores agent history locally under `~/.cursor/projects/<workspace-slug>/agent-transcripts/`. That data does not travel with your git project. CAM:

1. **Export** — copy transcripts into `docs/cursor_agents/` (or another folder) as JSONL + Markdown + index
2. **Commit** — push the archive with your project
3. **Import** (optional) — restore `.jsonl` files into Cursor on another machine
4. **Continue** — `@docs/cursor_agents/markdown/w1-11--topic.md` (readable context code files)

## Context codes (0.1.0)

| Feature | Description |
|---------|-------------|
| Auto codes | `w1-1`, `w2-110` from `workstation.index` + sequence |
| Manual codes | `cam code set w1-11 w1.git.001` |
| Readable files | `w1-11--topic-slug.md` for Cursor `@` picker |
| Stable export | Re-export overwrites the same file for a code |
| Selective sync | `--context w1-11` or `--mask 'w1-*'` on export/import |

Registry: `docs/cursor_agents/registry.yaml`. See **[USAGE.md](USAGE.md)**.

## Requirements

- Python 3.10+
- PyYAML

```bash
pip install -r requirements.txt
```

## Quick start

See **[USAGE.md](USAGE.md)** for the full step-by-step workflow (setup, export before leaving a workstation, import on a new machine).

### 1. Clone CAM into your project

```bash
git clone https://git.p7net.ru/tools/cam.git tools/cam
cd tools/cam
pip install -r requirements.txt
```

### 2. Create a workstation config

Each machine needs its own YAML file (not committed to the public CAM repo):

```bash
cp config/workstations/macos.example.yml config/workstations/local.yml
# edit project.root and other paths
```

Or copy a project-specific example if your project provides one (e.g. `nt-041.example.yml`).

Config search order (first existing file wins):

1. `--config` argument
2. `$CAM_CONFIG` environment variable
3. `config/workstations/<hostname>.yml`
4. `config/workstations/local.yml`
5. `config/config.yml`

### 3. Export

```bash
python cam.py -c config/workstations/local.yml export
```

### 4. Commit archive (in your project repo)

```bash
git add docs/cursor_agents/
git commit -m "Export Cursor agent history"
```

### 5. Import on another workstation (optional)

Close Cursor first, then:

```bash
python cam.py -c config/workstations/local.yml import --dry-run   # preview
python cam.py -c config/workstations/local.yml import
```

Re-open Cursor. Chat history may appear in the sidebar depending on Cursor version (undocumented behaviour).

**Recommended:** use the Markdown archive and `@docs/cursor_agents/INDEX.md` in a new agent chat instead of relying on UI restore.

## Commands

| Command | Description |
|---------|-------------|
| `paths` | Show resolved paths (project, transcripts, export dir) |
| `export` | Export Cursor transcripts to project archive |
| `import` | Copy archive `raw/` back to Cursor transcripts folder |
| `list` | List sessions in the export archive |

```bash
python cam.py --version
python cam.py -c config/workstations/local.yml paths
python cam.py -c config/workstations/local.yml export
python cam.py -c config/workstations/local.yml import --dry-run
python cam.py -c config/workstations/local.yml list
```

## Configuration

See [`config/config.example.yml`](config/config.example.yml).

| Key | Description |
|-----|-------------|
| `workstation.id` | Short ID stored in `manifest.json` (no secrets) |
| `workstation.label` | Human-readable workstation name |
| `project.root` | Absolute path to project root opened in Cursor |
| `project.name` | Display name |
| `cursor.transcripts_dir` | Override transcripts path (optional) |
| `cursor.home` | Override `~/.cursor` (optional) |
| `export.output_dir` | Archive directory relative to `project.root` |
| `export.index_language` | `en` or `ru` for generated Markdown |
| `import.overwrite_existing` | Replace existing Cursor transcript files |

**Security:** do not put passwords, tokens, or private hostnames into configs committed to the open CAM repository. Keep real workstation configs local (`*.yml` is gitignored; only `*.example.yml` templates are tracked).

## Archive layout

```
docs/cursor_agents/
├── INDEX.md
├── manifest.json
├── raw/
│   ├── <session-id>.jsonl
│   └── <parent-id>/subagents/<subagent-id>.jsonl
└── markdown/
    ├── <session-id>.md
    └── subagents/<subagent-id>.md
```

## Cursor project slug

If `cursor.transcripts_dir` is omitted, CAM derives:

```
~/.cursor/projects/<slug>/agent-transcripts/
```

where `<slug>` is built from the absolute `project.root` path (slashes → dashes, drive letter lowercased on Windows). Example:

| Project root | Cursor slug |
|--------------|-------------|
| `/Users/you/projects/my-app` | `Users-you-projects-my-app` |
| `D:/work/my-app` | `d-work-my-app` |

Use `python cam.py paths` to verify the resolved path on your machine.

## Integration with consumer projects

Consumer projects (e.g. `crm3-migration`) typically:

1. Clone CAM into `tools/cam/` (separate git repo)
2. Keep a project-specific `config/workstations/<host>.example.yml` template in the consumer repo or local docs
3. Store exports in `docs/cursor_agents/`

## Development

```bash
python cam.py paths -c config/config.example.yml   # fails until project.root exists
```

## Changelog

See [CHANGELOG.md](CHANGELOG.md).