Установка и init

Требования

• Claude Code или Cursor. floppy — плагин. Это не отдельная программа.
• bash, git и git-репозиторий. Каждая команда находит свои пути от корня репозитория. Вне репозитория каждая команда останавливается с ошибкой. Она не угадывает.
• macOS или Linux. CI гоняет тесты на обеих системах. Джоб macOS использует /bin/bash версии 3.2.57. Все скрипты обязаны работать с этой версией.
• Больше ничего. Скриптам не нужна ни одна другая программа. Сеть они используют только для команд git, которые вы можете прочитать в исходниках.

Для Windows используйте WSL. WSL для этих скриптов — линуксовый shell. Ни один тест не использует нативный Windows-shell.

Установка

Claude Code

claude plugin marketplace add spscream/ai-floppy
claude plugin install floppy@floppy

То же самое можно сделать внутри сессии. Используйте /plugin marketplace add spscream/ai-floppy, затем /plugin install floppy@floppy.

Имя floppy встречается во второй команде дважды. Так называется маркетплейс. Плагин внутри маркетплейса называется так же.

Cursor, из репозитория

1. Откройте Dashboard → Plugins → Add Marketplace → Import from Repo.
2. Введите spscream/ai-floppy.
3. Откройте Customize в боковой панели.
4. Найдите floppy и установите его.

Cursor должен иметь доступ к репозиторию на чтение. Если репозиторий приватный, войдите в Cursor под учётной записью, у которой такой доступ есть.

Cursor, из локальной копии

Используйте этот способ во время разработки плагина. Он же годится, чтобы попробовать плагин без маркетплейса.

mkdir -p ~/.cursor/plugins/local
ln -s /path/to/ai-floppy ~/.cursor/plugins/local/floppy

Затем запустите Cursor заново. Cursor читает .cursor-plugin/plugin.json и каталог skills/ из этого расположения.

Во время разработки можно также указать AI_FLOPPY_HOME на вашу локальную копию.

После установки подготовьте репозиторий скиллом init. См. ниже.

Cursor и несколько проектов сразу

В Cursor может быть открыто несколько проектов. Скилл выполняет свои shell-команды в одном из них. Проект скилл не выбирает.

Каждая процедура печатает репозиторий первой строкой вывода (repo: /path/to/it). Читайте эту строку первой. Читайте её до того, как wrap выполнит свой шаг commit, потому что этот шаг индексирует, коммитит и пушит файлы.

Две устаревшие копии, не дающие сообщения об ошибке

1. Кэш плагина

claude plugin update сравнивает номера версий. Если номер версии тот же, команда не копирует ни одного файла. После чего сообщает «already at the latest version».

Результат — установленная копия возрастом в несколько дней. Измерено 2026-08-25: в кэшированной копии лежал пустой каталог scripts/.

Чтобы это исправить, сделайте одно из двух:

• Увеличьте номер версии в .claude-plugin/plugin.json.
• Удалите плагин и установите его заново.

Копия кэша, в которой нет ни одного файла scripts/*.sh, — это сломанная установка. До 0.26.0 копия в вашем репозитории искала плагин и отказывалась работать с таким каталогом, давая внятное сообщение. Вызов по пути, который называет харнесс, ничего заранее не проверяет, поэтому ошибка будет «No such file or directory» на <plugin>/scripts/run. Ответ тот же: установите плагин заново.

2. Как выполняется команда

С версии 0.26.0 ваш репозиторий не хранит раннер. Команды живут в плагине и вызываются по пути:

bash <plugin>/scripts/run status

<plugin> — это каталог плагина. Агенту его сообщают: загружая скилл floppy, харнесс печатает над текстом скилла его базовый каталог — Base directory for this skill: <plugin>/skills/workstatus. Каталог плагина — на два уровня выше. Замерено в Claude Code 2026-09-22, на этом плагине и ещё на одном.

Диспетчер определяет свой каталог из собственного пути, поэтому вызову не нужны ни переменная, ни файл в вашем репозитории.

Репозиторий, заведённый до 0.26.0, продолжает работать. Плагин по-прежнему везёт shim/run, и .floppy/run, положенный старым init, всё так же находит плагин и выполняет команду. Просто ничто в плагине его больше не зовёт. Чтобы убрать файл:

git rm .floppy/run

Тем же коммитом поправьте AGENTS.md, если он называет .floppy/run точкой входа. Следующий init печатает напоминание, когда видит такую строку.

Осторожно: плагин старше копии — это полная остановка. У плагина до 0.14.0 нет диспетчера, поэтому против него не выполнится ни одна команда. Сообщение говорит об этом и называет каталог плагина, который был использован.

init

Выполните init один раз в каждом репозитории.

init задаёт два вопроса:

1. Каталог памяти. По умолчанию .agent-memory.
2. Язык заметок памяти.

Затем init делает всё перечисленное:

• пишет .floppy/config. Это единственный файл, который туда кладёт init; позже heat пишет там же .floppy/heat.log и закрывает его в .git/info/exclude, а не в вашем .gitignore. И лог, и правило, которое его прячет, локальны для машины, и в этом весь смысл: первый выпуск heat дописывал в .gitignore, поэтому первый же вызов на каждой машине оставлял .gitignore изменённым — а сторож wrap отказывается коммитить .gitignore, из-за чего каждый следующий wrap читался как «won’t commit: .gitignore». Своё правило вы, конечно, вправе закоммитить: тогда heat видит, что лог уже игнорируется, и не пишет ничего. Кода плагин в .floppy/ не кладёт — единственный исполняемый файл, который там бывает, это workstatus-project.sh, и он ваш: вам его писать и вам решать, коммитить ли его, чтобы он работал на всех машинах (см. скилл workstatus).
• создаёт индекс памяти MEMORY.md — в <memory_dir> этого репозитория, если память живёт здесь, и в scope этого проекта в хранилище, если .floppy/config хранилище называет. С 0.27.0 во втором случае в рабочей копии ничего с таким именем не создаётся.
• создаёт файл состояния docs/statuses/NOW.md.
• добавляет приватную область памяти в .gitignore. Этот путь становится симлинком в приватный репозиторий памяти, и репозиторий с кодом не должен его нести. Имя — memory_private_dir, чтобы совпадать с тем, что создаёт workplace.
• добавляет указатель на agent-memory в ваш AGENTS.md.

init идемпотентен. Если репозиторий уже подготовлен, второй запуск ничего не меняет.