Проекты

Проект — это место, где Istok хранит всё, что относится к одному репозиторию. Здесь вы узнаете, как репозиторий становится проектом, как Istok понимает, в каком проекте работает агент, и где лежат данные.

Регистрация репозитория

Istok работает только с репозиториями, которые вы зарегистрировали. Это делается один раз для каждого репозитория — обычно достаточно попросить агента:

Агент вызывает MCP-инструмент project_init, и тот регистрирует директорию, в которой запущен агент. Из терминала то же самое делает istok init. Если директория уже зарегистрирована, Istok вернёт существующий проект, а не создаст второй.

istok init заодно строит первый индекс кода. Проект, зарегистрированный через MCP, получает индекс, когда агенту впервые понадобится поиск по коду.

Что хранится в проекте

Всё, что записывает Istok, принадлежит проекту, а не разговору и не конкретному агенту:

• задачи, их зависимости, прогресс и комментарии;
• запуски с выполненными командами, проверками и артефактами;
• сохранённый контекст: правила проекта, решения, ограничения, заметки;
• знания проекта;
• индекс кода для поиска.

Состояние живёт в проекте, поэтому новая сессия или другой агент продолжают с того места, где остановился предыдущий. Подробнее — в разделе Задачи и запуски.

Как Istok находит текущий проект

Istok определяет проект по директории, в которой вы находитесь. Поэтому одной записи istok mcp в пользовательской конфигурации агента хватает для всех репозиториев: каждый процесс MCP-сервера смотрит на директорию, где его запустили, выбирает этот проект и работает с ним до завершения.

Команды CLI ведут себя так же и опираются на текущую директорию: istok task list внутри acme-api покажет задачи acme-api.

Вложенные проекты

Проект может лежать внутри другого проекта — например, приложение внутри монорепозитория:

~/work/platform            → проект "platform"
~/work/platform/apps/web   → проект "web"

Побеждает ближайший проект. Всё, что запущено в apps/web и глубже, относится к web; остальное внутри ~/work/platform — к platform. Два активных проекта не могут иметь одну и ту же директорию.

Где хранятся данные

Istok ничего не пишет в ваш репозиторий: ни файлов-маркеров, ни конфигурации, ни выгруженных заметок. Всё состояние хранится локально на вашей машине:

<data-home>/istok/
├── istok.db      проекты, задачи, запуски, контекст, знания (SQLite)
├── indexes/      индекс кода, по директории на проект
└── artifacts/    файлы, записанные запусками

В Linux <data-home> — это ${XDG_DATA_HOME:-$HOME/.local/share}, в macOS — $HOME/Library/Application Support. Аккаунта и облачного сервиса нет. Файл базы данных доступен для чтения только вам. Пути и способы их переопределить описаны в разделе Конфигурация.

Как посмотреть свои проекты

istok ui открывает локальный веб-интерфейс. В нём видны все проекты с числом задач, активными и зависшими запусками и последними событиями.

127.0.0.1:7700

В терминале то же самое показывают istok project list и istok project show. См. также руководство по веб-интерфейсу.

Перенос, переименование и удаление

• Перенесли репозиторий? Привяжите существующий проект к новому пути командой istok project rebind, а не регистрируйте новый. Задачи и история останутся на месте.
• Нужно другое имя? istok project rename.
• Удаление проекта скрывает его из списка активных и освобождает директорию, но сохраняет задачи, запуски и историю. Ваши файлы оно не трогает, а istok project restore возвращает проект обратно.

Все флаги — в справке по istok project.