π A presentation about an agent, made by that agentПрезентация об агенте, сделанная самим агентом
A metacognitive extension suite for the pi coding agent. It rides pi's session loop and adds enforcement, memory, reasoning, and self-improvement, then verifies its own work before calling anything done.Набор метакогнитивных расширений для кодинг-агента pi. Он работает поверх цикла сессий pi и добавляет контроль, память, рассуждения и самоулучшение, а затем проверяет собственную работу, прежде чем объявить её готовой.
ScrollПрокрутите
02 The harnessСреда
pi is a minimal terminal coding agent: a session loop and a handful of built-in tools, designed so that everything else arrives as an extension. Braid is one of those extensions, and a large one.pi — минимальный терминальный кодинг-агент: цикл сессии и несколько встроенных инструментов, устроенный так, что всё остальное приходит расширениями. Braid — одно из таких расширений, и немаленькое.
read, write, edit, and bash sit at the center; grep, find, ls, and PowerShell round out the working set. tool_search returns deferred tools to the active list when they are needed.read, write, edit и bash — в центре; grep, find, ls и PowerShell дополняют рабочий набор. tool_search возвращает отложенные инструменты в активный список, когда они нужны.
Every turn is a node in a JSON Lines (JSONL) session file. Branch, fork, resume, and compact in place, without losing the trail that led there.Каждый шаг — узел в файле сессии JSON Lines (JSONL). Ветвление, форки, возобновление и сжатие на месте — тропа, которая привела сюда, не теряется.
An interactive terminal user interface (TUI), a one-shot --print, machine-readable JSON, or Remote Procedure Call (RPC) over standard input and output. A Software Development Kit (SDK) embeds the same loop in your own programs.Интерактивный терминальный интерфейс (TUI), одноразовый --print, машиночитаемый JSON или RPC (Remote Procedure Call) поверх стандартного ввода-вывода. SDK (Software Development Kit) встраивает тот же цикл в ваши программы.
Extensions are TypeScript modules, skills are Markdown procedures, and prompts and themes are plain files. Bundles ship as pi packages.Расширения — TypeScript-модули, навыки — Markdown-процедуры, промпты и темы — простые файлы. Собираются в pi-пакеты.
Tool inventory, pi's native ones included: packages/core/TOOLS.md.Каталог инструментов, включая нативные: packages/core/TOOLS.md.
03 PhilosophyФилософия
pi's core says no on purpose: each no is a door an extension can walk through, and the answer is allowed to move. One of the doors below has already opened.Ядро pi говорит «нет» намеренно: каждое «нет» — дверь, в которую может войти расширение, и ответу позволено меняться. Одна из дверей ниже уже открылась.
The positions kept from the deck's earlier generations, checked against today's pi: one flipped, the rest hold.Позиции из прежних поколений презентации, сверенные с сегодняшним pi: одна перевернулась, остальные в силе.
04 The suiteНабор
Braid is a monorepo of pi packages. The core carries the metacognitive layer; the satellites are optional: a skill library, extra tools, providers, a human channel.Braid — монорепозиторий pi-пакетов. Ядро несёт метакогнитивный слой; спутники опциональны: библиотека навыков, дополнительные инструменты, провайдеры, человеческий канал.
05 The differenceРазница
Bare pi is a good agent with a short memory and no second opinion. Each workspace in the suite closes one of those gaps.Голый pi — хороший агент с короткой памятью и без второго мнения. Каждый воркспейс набора закрывает один из этих пробелов.
None of this is pi's job: the harness stays small and the suite carries the metacognition. That division is the point, and it has a price: a longer system prompt, more moving parts to keep working, and an API that will move before it settles.Ничто из этого не входит в задачи pi: среда остаётся маленькой, а метакогницию берёт на себя набор. В этом разделении и смысл, и у него есть цена: более длинный системный промпт, больше деталей, которые надо держать в рабочем состоянии, и API, который будет меняться, прежде чем устоится.
06 ArchitectureАрхитектура
Extensions register tools, listen for session events, and shape the system prompt. Nothing is forked and nothing is monkey-patched: the suite is a set of modules loaded into a session.Расширения регистрируют инструменты, слушают события сессии и формируют системный промпт. Ничего не форкается и не патчится в обход: весь набор — это модули, загружаемые в сессию.
Braid registers its tools alongside pi's native ones. The full catalog lives in a single file, TOOLS.md, with each tool's enablement tier written next to it.Braid регистрирует свои инструменты рядом с нативными у pi. Полный каталог живёт в одном файле TOOLS.md, а рядом с каждым инструментом указан уровень его включения.
Each enabled tool contributes a one-line guideline to the system prompt. A lockstep test keeps those lines exactly equal to the catalog; change one side alone and the build fails.Каждый включённый инструмент добавляет в системный промпт одну строку-директиву. Lockstep-тест удерживает эти строки в точном соответствии с каталогом: изменишь одну сторону — сборка падает.
Every module is always-on, default-on, or opt-in. Always-on modules cannot be disabled; opt-in ones stay dark until a setting asks for them. The manifest, not the docs, is the list.Каждый модуль — always-on, default-on или opt-in. Always-on модули нельзя отключить; opt-in остаются тёмными, пока настройка их не включит. Список задаёт манифест, а не документация.
Feedback arrives as short injected messages that steer the next turn, never as a rewrite of the prompt under a running session.Обратная связь приходит короткими инъекциями для следующего шага, а не переписыванием промпта под работающей сессией.
07 InjectionИнъекция
A whisper is a short message injected into a live session. The agent sees it on its next turn; the terminal shows it; the transcript keeps it. Delivery is by class: “live” reaches the running loop, “park” is held for the end-of-turn flush, and only a genuinely critical whisper starts a new turn.Шёпот — короткое сообщение, инжектируемое в живую сессию. Агент видит его на следующем шаге; терминал показывает; транскрипт сохраняет. Доставка — по классу: «live» доходит до работающего цикла, «park» откладывается до конца шага, и только по-настоящему критичный шёпот может начать новый шаг.
The turn a whisper enters has a shape:Шаг, в который входит шёпот, имеет форму:
08 SignalsСигналы
A whisper earns attention only if it is rare and attributed. Each family speaks on its own cadence, and every line says who is talking.Шёпот заслуживает внимания, только если он редок и подписан. У каждого семейства своя частота, и в каждой строке сказано, кто говорит.
Delivery class is the control. An advisory whisper rides the running turn or parks until it ends; only a genuinely critical one may start a new turn. Without that split, observation feeds itself: compaction invites a turn, a turn spends context, context invites compaction.Класс доставки и есть управление. Совещательный шёпот едет в текущем шаге или ждёт его конца; начать новый шаг может только по-настоящему критичный. Без этого разделения наблюдение кормит само себя: сжатие вызывает шаг, шаг тратит контекст, контекст вызывает сжатие.
09 CalibrationКалибровка
The enforcement extension is a belief-policy engine with an unglamorous job: notice when the agent is drifting, agreeing too easily, or declaring victory early, and say so.Расширение контроля — это движок убеждений и политик с негламурной работой: замечать, когда агент уплывает, слишком легко соглашается или объявляет победу раньше времени, и говорить об этом.
Three levels: L1 signals surface through the prompt builder, L2 bundles session-level sub-signals, and L3 marks the critical ones: validation failures and orphan chains. Chosen by policy rather than mood.Три уровня: сигналы L1 всплывают через сборщик промпта, L2 объединяет подсигналы уровня сессии, а L3 отмечает критичные: провалы валидации и осиротевшие цепочки. Выбираются политикой, а не настроением.
The classifier scores validation before correction after the reply is sent; the whisper steers the next turn, not the last one.Классификатор оценивает одобрение прежде исправления уже после отправки ответа; шёпот правит следующий шаг, а не прошлый.
Dedicated check and reset tools measure how far the current turn has wandered from the request that opened it.Специальные инструменты проверки и сброса измеряют, насколько текущий шаг отклонился от открывшего его запроса.
A reasoning-quality detector watches for instability in the agent's own conclusions and nudges verification when confidence outruns evidence.Детектор качества рассуждений следит за нестабильностью собственных выводов агента и подталкивает к верификации, когда уверенность опережает доказательства.
When a task completes, a reflector reads the turn for principles and procedures worth keeping, so a session leaves more behind than its transcript.По завершении задачи рефлектор читает шаг в поисках принципов и процедур, которые стоит сохранить: сессия оставляет больше, чем транскрипт.
10 MemoryПамять
A flat log remembers what happened. Braid keeps three stores with different shapes and search semantics, plus working state that survives compaction.Плоский лог помнит, что произошло. Braid держит три хранилища разных форм с разной семантикой поиска, плюс рабочее состояние, переживающее сжатие.
Durable goals, plans, and decisions, resumable after compaction or a restart.Долговечные цели, планы и решения, переживающие сжатие и перезапуск.
Search across past sessions, so yesterday's reasoning is still reachable.Поиск по прошлым сессиям: рассуждения вчерашнего дня остаются доступными.
Watches context pressure and proposes archiving or compaction before a limit is hit.Следит за давлением контекста и предлагает архивацию или сжатие до достижения лимита.
Capture, diff, and restore files; a return point before risky edits.Захват, diff и восстановление файлов; точка возврата перед рискованными правками.
All three stores are cross-searchable through memory action=recall_search; the stores on disk are the only source of truth, and the tools read them directly.Все три хранилища доступны для кросс-поиска через memory action=recall_search; единственный источник правды — хранилища на диске, и инструменты читают их напрямую.
11 The worker poolПул воркеров
Large work does not fit one context. Braid delegates it: the orchestrator plans and decomposes, workers run in their own terminal panes and git worktrees, and results come back as artifacts, not prose.Большая работа не помещается в один контекст. Braid делегирует её: оркестратор планирует и декомпозирует, воркеры работают в терминальных панелях и git-ворктри, а результаты возвращаются артефактами, не прозой.
A worker must name its output file and its gate exit codes; a close whose file count sits below the tree refuses the merge.Воркер обязан назвать выходной файл и коды выхода гейтов; если в закрытии файлов меньше, чем в дереве, слияния нет.
This deck is a worker artifact: built in an isolated worktree, every claim traced to a file, verified before it was called done.Эта презентация — артефакт воркера: собрана в изолированном ворктри, каждое утверждение прослежено до файла, и она проверена до того, как её назвали готовой.
Built the way the worker pool buildsСобрано так, как собирает пул воркеров
12 DisciplineДисциплина
Braid's cognitive tools make premature confidence expensive: think before a non-trivial move, hypothesize when a fix fails, verify before done, finalize only with the checks green.Когнитивные инструменты Braid делают преждевременную уверенность дорогой: think перед нетривиальным действием, hypothesize когда исправление не сработало, verify до завершения, finalize только с зелёными проверками.
A fix lives where the invariant lives: shared layers know mechanisms, never one project's names, paths, or policy.Исправление живёт там, где живёт инвариант: общие слои знают механизмы, но никогда — имена, пути или политику одного проекта.
Placement discipline, enforced by a tree scanДисциплина размещения, подкреплённая сканированием дерева
13 The long loopДлинный цикл
Beyond the turn, there is a slower loop: measure what got used, reflect on what happened, and turn failures into procedures.За пределами шага есть более медленный цикл: измерять, что было использовано, рефлексировать о случившемся и превращать провалы в процедуры.
skill-usage counts what was suggested, loaded, claimed, and actually read. It is the instrument that keeps the skill library honest about what earns its place.skill-usage считает, что было предложено, загружено, заявлено использованным и действительно прочитано. Это инструмент, который не даёт библиотеке навыков обманывать себя насчёт того, что оправдывает своё место.
meta-improvement creates and revises skills, runs self-improving experiments, and measures whether they helped.meta-improvement создаёт и пересматривает навыки, запускает самоулучшающиеся эксперименты и измеряет, помогли ли они.
probe-evaluation designs A/B probes with pre-registered rubrics and decision rules, so a null result is informative rather than embarrassing.probe-evaluation проектирует A/B-пробы с заранее зарегистрированными рубриками и правилами решений, чтобы нулевой результат был информативным, а не неловким.
Heuristic evolution, offline consolidation, and Standard Operating Procedure (SOP) extraction run off the back of completed work.Эволюция эвристик, офлайн-консолидация и извлечение стандартных операционных процедур (SOP) работают по итогам завершённой работы.
Failures feed this loop passively: the evolver collects failure signatures, mines them into weakness clusters, and whispers back a summary with the actionable ones counted. It reports; the agent decides what to change.Провалы питают этот цикл пассивно: evolver собирает сигнатуры провалов, сводит их в кластеры слабых мест и возвращает шёпотом сводку с числом действенных. Он сообщает; что менять — решает агент.
14 SourcesИсточники
No count, version, or date appears on these pages, because each of those is a line a reader would have to edit later. Every class of claim has one file that decides it, and the file is always current.Ни одного числа, версии или даты на этих страницах нет: каждое такое значение — строка, которую читателю придётся править. У каждого класса утверждений есть один файл, который решает, и этот файл всегда актуален.
A page that carries a figure needs an editor every time the repository moves. A page that carries the path only needs a reader.Странице с цифрой нужен редактор каждый раз, когда двигается репозиторий. Странице с путём нужен только читатель.
15 The libraryБиблиотека
Skills are Markdown procedures, not capabilities. They are grouped here by the job they do, not by the package they ship in, because that is how the agent finds them: by description, for the task in front of it.Навыки — это Markdown-процедуры, а не возможности. Здесь они собраны по работе, которую делают, а не по пакету, в котором лежат: именно так агент их и находит — по описанию, под задачу.
The tombstone is left out: code-search is merged into code-refactoring. Each skill carries a verdict (KEEP, IMPROVE, UNVALIDATED, MOVE), and the record keeps the ones that did not pass.Надгробие не показано: code-search слит в code-refactoring. У каждого навыка есть вердикт (KEEP, IMPROVE, UNVALIDATED, MOVE), и запись хранит и те, что не прошли.
16 The channelКанал
Telegram is the human interface: the agent sends reports and receives instructions from a phone, without a terminal in sight.Telegram — это человеческий интерфейс: агент отправляет отчёты и получает инструкции с телефона, без терминала на горизонте.
telegram_send pushes a concise update or a rich HTML or Markdown report, split to fit the message limit.telegram_send отправляет краткий апдейт или развёрнутый отчёт в HTML или Markdown, нарезанный под лимит сообщения.
telegram_inbox and a background poller ingest replies from whitelisted chats, with deduplication and persisted offsets.telegram_inbox и фоновый poller принимают ответы из белых списков чатов, с дедупликацией и сохранёнными смещениями.
The voice-replies skill synthesizes speech in Russian, English, or Hebrew, converts it to Ogg/Opus, and sends a voice note.Навык voice-replies синтезирует речь на русском, английском или иврите, конвертирует в Ogg/Opus и отправляет голосовое сообщение.
An inline keyboard pauses or resumes the work; a live-update message tracks progress in place and closes on Done.Inline-клавиатура ставит работу на паузу или возобновляет; живое сообщение отслеживает прогресс на месте и закрывается на Done.
17 Under the floorПод полом
The suite also maintains the ground it stands on: liveness, errors, health, and the tunnel underneath.Набор обслуживает и собственную почву: живость, ошибки, здоровье и туннель внизу.
A liveness and stall state machine watches turn progress, provider feedback, and tunnel liveness. When the session stalls, it wakes with a whisper and, optionally, a one-line Telegram signal.Машина состояний живости и зависаний следит за прогрессом шагов, откликом провайдера и живостью туннеля. Когда сессия застревает, она пробуждается шёпотом и, опционально, однострочным сигналом в Telegram.
Auto-recovery checks for degradation on each turn and steers the agent to re-plan before errors compound; health maintenance adds checkpoints, degradation detection, and rollback on request.Авто-восстановление проверяет деградацию на каждом шаге и направляет агента к перепланированию, пока ошибки не накопились; health-maintenance добавляет чекпоинты, детекцию деградации и откат по запросу.
The error tool (list, get, stats, clear) keeps a searchable trail when something breaks mid-session.Инструмент error (list, get, stats, clear) ведёт доступный для поиска след, когда что-то ломается посреди сессии.
A contrib network monitor (packages/contrib/network-monitor/) probes the macOS tunnel beneath the session and restores it through the client's own mechanism, without root.Сетевой монитор из contrib (packages/contrib/network-monitor/) проверяет macOS-туннель под сессией и восстанавливает его через собственный механизм клиента, без root.
18 In practiceНа практике
This deck is its own test case: one dispatch, an isolated worktree, every claim traced to a file, gates before done. The worker pool page describes the machinery; this is what it produced.Эта презентация — собственный тест-кейс: одно задание, изолированный ворктри, каждое утверждение прослежено до файла, гейты до «готово». Раздел про пул воркеров описывает механику; это — то, что она произвела.
Inputs: the harness's own docs and changelog, the repository at its current head, the root manifest, and this file.Входы: документация и чейнджлог самой среды, репозиторий на текущем head, корневой манифест и этот файл.
19 InstallУстановка
pi has to exist first; then Braid is one package install, recorded in pi's own settings. A checkout is for working on Braid, not for using it.Сначала — pi. Затем Braid — это одна установка пакета, и pi записывает её в свои настройки. Клон — чтобы работать над Braid, а не пользоваться им.
# pi, the harness# pi, среда $ npm install -g --ignore-scripts @earendil-works/pi-coding-agent # braid, then the add-ons you want# braid, затем нужные надстройки $ pi install npm:pi-braid $ pi install npm:pi-braid-skills # first run: connect a provider# первый запуск: подключите провайдера $ pi # then /login inside the session# затем /login внутри сессии
From a checkout: register core and skills in ~/.pi/agent/settings.json; the root manifest declares no pi resources, so point at the workspaces:Из клона: зарегистрируйте core и skills в ~/.pi/agent/settings.json; корневой манифест не объявляет pi-ресурсы, указывайте на воркспейсы:
{
"packages": [
"file:~/pi-braid/packages/core",
"file:~/pi-braid/packages/skills"
]
}
Then start pi. Braid loads with the session, and the prompt lists the bundled skills. Add contrib, providers, or telegram the same way.Затем запустите pi. Braid загружается вместе с сессией, а промпт перечисляет встроенные навыки. contrib, providers или telegram добавляются так же.
The engine floor is the engines field in the root package.json. The README carries the status: early-stage software.Порог движка — поле engines в корневом package.json. Статус записан в README: софт ранней стадии.
20 EndКонец
Every claim here came out of the pi-braid repository rather than out of a session: tools from the catalog, modules from the manifest, skills from their own directories. When the repository moves, these pages stay true, because they carry paths instead of figures.Каждое утверждение здесь взято из репозитория pi-braid, а не из сессии: инструменты — из каталога, модули — из манифеста, навыки — из их каталогов. Когда репозиторий двигается, эти страницы остаются верными, потому что несут пути, а не цифры.
Braid is early-stage software, as its README says: expect the API surface to move. What is already settled is the discipline around it. Claims get evidence, changes get a home, and done is something you prove.Braid — софт ранней стадии, как и написано в его README: ждите изменений API. Уже устоялась дисциплина вокруг него. Утверждения получают доказательства, изменения — дом, а «готово» — то, что нужно доказать.
This page is not a manual: the manual is the repository. Navigate with the arrow keys, Page Up and Page Down, or Home and End. π & Braid.Эта страница — не руководство: руководство — это репозиторий. Навигация: стрелки, Page Up и Page Down, Home и End. π & Braid.