SOBA Agent - CLI coding agent with memory, MCP, and cozy TUI

Формат JSONL, продолжение сессий, rewind, ветвление и навигация по дереву.

Сессии SOBA — это JSONL-деревья, которые хранят полную историю работы с агентом: сообщения, результаты инструментов, ветвления и контекстные капсулы. Сессии можно продолжать, перематывать и ветвить — как в Git.

1. Формат сессий

1.1. JSONL-дерево

Сессия — это файл в формате JSONL (JSON Lines), где каждая строка — отдельный JSON-объект. Каждая нода в дереве представляет один turn (ход) — полный цикл «запрос пользователя → ответ агента → результат».

{"type":"meta","sessionId":"abc123","created":"2024-01-15T10:00:00Z","model":"deepseek/deepseek-v4-flash"}
{"type":"user","turnId":"t1","parentTurnId":null,"content":"Fix TypeScript errors","timestamp":"2024-01-15T10:00:01Z"}
{"type":"assistant","turnId":"t1","content":"I'll analyze the TypeScript errors...","toolCalls":[{"name":"read","args":{"path":"src/parser.ts"}}],"timestamp":"2024-01-15T10:00:05Z"}
{"type":"tool_result","turnId":"t1","toolName":"read","result":"...file content...","timestamp":"2024-01-15T10:00:06Z"}
{"type":"assistant","turnId":"t1","content":"Found 3 errors in parser.ts","timestamp":"2024-01-15T10:00:10Z"}
{"type":"user","turnId":"t2","parentTurnId":"t1","content":"Now add tests","timestamp":"2024-01-15T10:01:00Z"}

1.2. Древовидная структура

Каждый turnId имеет parentTurnId, что позволяет создавать ветки:

t1 (Fix TS errors)
├── t2 (Add tests)           ← основная ветка
│   ├── t3 (Add docs)
│   └── t4 (Refactor)
└── t2b (Add error handling) ← альтернативная ветка (rewind от t1)
    └── t3b (Add logging)

1.3. Типы записей в JSONL

`type`	Описание
`meta`	Метаданные сессии (создание, модель)
`user`	Сообщение пользователя или начало нового хода
`assistant`	Ответ агента (текст + tool calls)
`tool_result`	Результат выполнения инструмента
`capsule`	Контекстная капсула (результат compaction)
`checkpoint`	Milestone checkpoint
`status`	Статусная информация (info, error, warning)
`loop_decision`	Запись debug-режима о решениях loop'а

2. Создание и продолжение

2.1. Новая сессия

Сессия создаётся автоматически при первом запросе:

# One-shot — создаётся новая сессия
soba "Fix all errors"

# Интерактивный — создаётся новая сессия
soba
> Hello, what can you do?

ID сессии генерируется автоматически (UUID v4, сокращённый до 12 символов).

2.2. Продолжение сессии

# Продолжить последнюю сессию
soba -c

# Интерактивный выбор из последних 50 сессий
soba -r

# Продолжить конкретную сессию
soba -s abc123

# Продолжить one-shot'ом
soba -s abc123 "Continue working on the parser"

2.3. Внутри TUI

# Информация о текущей
/session

3. Ветвление и Rewind

Как и в Git, можно откатиться на любой предыдущий ход и создать ветку.

3.1. Rewind (откат)

# Откат к конкретному ходу
/session rewind t3

# После этого новая цепочка ходов создаст ветку:
t1 → t2 → t3          ← оригинальная ветка (сохранена)
       ↘ t3b → t4b   ← новая ветка (активная)

3.2. Просмотр дерева сессии

# Посмотреть информацию о сессии
/session

3.3. Сравнение веток

Ветки можно сравнить, попросив агента прочитать и сравнить соответствующие turn'ы в сессии.

4. Навигация по дереву

4.1. Просмотр дерева

/session info --tree

# Вывод:
# t1 [10:00] Fix TS errors (2 children)
# ├── t2 [10:01] Add tests
# │   ├── t3 [10:05] Add docs
# │   └── t4 [10:10] Refactor ★ (active)
# └── t2b [10:03] Add error handling
#     └── t3b [10:07] Add logging

4.2. Контекст ветки

При переключении между ветками контекст восстанавливается до точки ветвления. Все капсулы, созданные в конкретной ветке, остаются с ней.

5. Просмотр и управление

5.1. Список сессий

Список сессий доступен через селектор при запуске с флагом -r:

# Интерактивный выбор сессии
soba -r

5.2. Информация о сессии

/session

# Вывод:
# Session ID:     abc123
# Turns:          8
# Model:          deepseek/deepseek-v4-flash
# Tokens used:    28,450
# Capsules:       2

6. Экспорт

Для экспорта сессии используйте инструменты агента — попросите его прочитать файл сессии и сохранить в нужном формате.

7. Без сессий (no-session mode)

Режим без сохранения истории:

# Интерактивный без сессии
soba --no-session
> Hello

# Всё работает как обычно, но история не сохраняется на диск.
# После выхода сессия теряется безвозвратно.

Когда использовать:

Тестирование промптов
Одноразовые задачи
Конфиденциальные запросы

8. Хранение

8.1. Расположение

По умолчанию: ~/.soba/sessions/<session-id>.jsonl

Изменить путь можно в конфиге:

{
  "sessionDir": "/custom/path/to/sessions"
}

# Удалить сессии старше 30 дней
find ~/.soba/sessions -name "*.jsonl" -mtime +30 -delete

Сессии