Initial release v0.0.1 — Cursor Agents Manager.
Export/import Cursor agent transcripts between workstations. YAML per-workstation config, Markdown archive, MIT license. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -0,0 +1,166 @@
|
||||
# CAM — Cursor Agents Manager
|
||||
|
||||
**Version:** 0.0.1
|
||||
**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** — open `@docs/cursor_agents/INDEX.md` in a new Cursor chat for agent context
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.10+
|
||||
- PyYAML
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
### 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).
|
||||
Reference in New Issue
Block a user