Official plugins and agent packages for Bakin.

---

What is Bakin Bits?

Bakin Bits is the home for first-party plugins and agent packages that extend Bakin, a personal AI runtime. Plugins live here so they can ship and update independently of the Bakin core binary — a fix to a plugin doesn't require a new core release, and contributors can land changes without coordinating with the runtime team.

Each package in this monorepo is installed by git subpath, not by publishing to a registry:

bakin plugins install github:markhayden/bakin-bits-official#plugins/<name>
bakin agents  install github:markhayden/bakin-bits-official#agents/<name>

The #subpath syntax tells Bakin to clone this repo, copy just the selected package directory into the local runtime, and discard everything else. You get one package, not the whole monorepo.

Public docs (in progress) — extending Bakin: https://makinbakin.com/docs/extending/overview/

Quickstart

Install the messaging plugin into a running Bakin runtime:

bakin plugins install github:markhayden/bakin-bits-official#plugins/messaging

During the SDK cutover, install this branch with a matching Bakin cutover build. A normal binary install provides the runtime SDK host modules for @makinbakin/sdk/*; you do not need a local Bakin checkout unless you are doing hot-reload or end-to-end development.

Pin to a released version with the @<ref> suffix:

bakin plugins install github:markhayden/bakin-bits-official#plugins/messaging@messaging-v0.0.1

Available packages

Plugins

Plugin	Status	Description
messaging	active	Content Plans, Deliverables, brainstorm sessions, task-backed prep, and publishing.
projects	active	Project specs, checklists, task links, and project MCP tools.
_template	scaffold	Starter plugin layout for new contributors.

Agents

Agent	Status	Description
patch	active	Developer agent package — git-isolation skill, dev-discipline lessons, workspace templates, avatar.
pixel	active	Image artist package — visual prompt lessons, image-generation workflow skills, workspace templates.
rolo	active	Video producer package — video/audio craft lessons and declared Runway/ElevenLabs runtime secrets.
jessica	active	Research package — source-hierarchy lessons and evidence-gathering workspace templates.

Capability packs

Skill-packs that give agents a new power. Each one ships the skill that teaches the agent to use it plus whatever the capability needs — a pinned binary, npm dependencies, a required key, or a prerequisite Bakin checks for but does not install. Readiness for every leg surfaces in Bakin's Health and Explore surfaces, so a half-configured pack says so instead of failing at turn time.

Pack	Needs	Description
web-search-brave	pinned bx binary + Brave API key	Web search, answers, and page extraction.
browser-tools	npm deps + Google Chrome	Drives real Chrome — render, screenshot, extract article text.
ocr	pinned ocrit binary (macOS)	Reads text out of images and scanned PDFs via Apple Vision.
transcribe	pinned binary + model (macOS arm64)	Local speech-to-text for audio and video.
youtube-transcript	npm deps	Pulls the caption transcript of a YouTube video.
office-docs	npm deps	Reads and writes real Word (.docx) and Excel (.xlsx) files.
github	gh on PATH, optional token	Issues, pull requests, CI runs, and diffs through the gh CLI.
google-workspace	gog on PATH (OAuth)	Gmail, Calendar, Drive, Contacts, Sheets, and Docs.
notion	Notion integration token	Search, read, and write a Notion workspace over its REST API.
skill-porter	nothing	Sharpens bakin skills map when auditing an installed skill's requirements.

A pack that declares a secret binds it to its own skills.<pack-id>.<ENV_VAR> slot — Bakin refuses to bind anything outside that namespace, so a pack can never siphon a credential stored for another integration. packs/pack-contract.test.ts enforces this along with the rest of the pack contract.

Publishing a release (Whiskit)

Plugin dist/ is not committed — it is build output. To ship a plugin version so users can install it with no toolchain, bump plugins/<id>/bakin-plugin.json and push a matching <id>-v<semver> tag:

git tag -a messaging-v0.2.0 -m "Add brainstorm export; fix plan ordering"
git push origin messaging-v0.2.0

CI validates the version, builds the plugin, assembles a prebuilt artifact + checksum, carries the catalog forward, and creates a GitHub release (notes = your tag message). Install then downloads + verifies the artifact — nothing builds on the user's machine. Full process, versioning rules, and troubleshooting: RELEASE.md.

Agent packages don't need a release. bakin agents install github:…#agents/<name> installs from source (the cloned subpath) — agent packages ship content, not built dist/, so they have no artifact build or publish step. Land changes on main and users get them on their next install.

Local development

Clone alongside your Bakin checkout so paths line up, then link a plugin into a running runtime via hot-reload:

git clone git@github.com:markhayden/bakin-bits-official.git
cd bakin-bits-official
bun install

# In your bakin checkout:
BAKIN_DEV_HOTRELOAD=1 bakin start

# Back in this repo:
bakin plugins link ./plugins/_template

Before opening a PR, run the same gates CI runs:

bun run typecheck && bun run test && bun run lint

Installed-SDK browser conformance

bun run ui:conformance:coverage validates enrollment for every official plugin. _template, Terminal, Projects, and Messaging all run browser fixtures in CI; none is exempt as migration-pending.

To run those fixtures against an assembled real SDK (not the workspace test stub):

BAKIN_SDK_PACKAGE_DIR=/absolute/path/to/assembled-sdk bun run ui:conformance

The runner packs that SDK and installs each plugin in a temporary consumer. Every package runs the canonical test:ui (bakin-plugin-test-ui). Messaging also runs test:ui:collections for Calendar, Brainstorm, and workspace pieces. Reports, including partial failures, are copied to test-results/plugin-ui-conformance/<plugin>/; Messaging's additional reports live in its calendar/, brainstorm/, and workspace/ subdirectories.

The enrollment's installed-package mode additionally runs package-local typechecks and unit tests for the template and Terminal. Projects and Messaging use workspace-checks: their unit tests depend on the root DOM preload and SDK stubs, so the separate CI Checks job runs their full workspace typecheck and tests with coverage. Only these redundant isolated unit/type commands differ; both modes always execute the real installed-SDK browser fixtures.

CI pins the compatible Bakin SDK source to an immutable commit in .github/workflows/ci.yml. Update that pin intentionally with the matching host SDK implementation and canonical stylesheet; do not substitute a moving branch. Release the compatible host first, then publish the plugin consumers.

Plugin architecture notes

Official plugins should stay on the public SDK surface: @makinbakin/sdk, @makinbakin/sdk/types, @makinbakin/sdk/hooks, @makinbakin/sdk/ui, @makinbakin/sdk/patterns, and @makinbakin/sdk/utils. (The legacy @makinbakin/sdk/components barrel was removed in the storybook refit.) Do not import Bakin host internals or a specific runtime adapter from plugin source. Runtime work goes through ctx.runtime; UI primitives and brainstorm helpers come from the SDK. The runtime provides these SDK modules when plugins are installed from git subpaths, so plugin packages should keep @makinbakin/sdk as an external peer instead of vendoring it.

Page-level filter bars use PageControls variant="filters" from @makinbakin/sdk/patterns, including single-facet and status-only filters. The host kit owns one leading icon and suppresses duplicate icons in nested AgentFilter controls. Leave command and view-only bars on the default variant; do not add plugin-local filter icons. This treatment requires a Bakin host/SDK that includes the shared filter-mode change; release that host support before publishing these consumer updates. The local SDK test stub checks composition, not the host kit's visual behavior.

For durable agent chat surfaces, use stable adapter-neutral thread IDs via brainstormThreadId(scope, entityId, agentId). Store plugin-owned messages and tool activity for UI hydration, but let the runtime adapter maintain conversation continuity for repeated agentId + threadId calls.

For server-side diagnostics and lifecycle messages, use ctx.log from the plugin context. It emits through Bakin's plugin-scoped structured logger and keeps reload, activation, and shutdown output in the normal log channels. Reserve ctx.activity.log for user-visible activity feed entries, and avoid console.* in plugin server code except as a compatibility fallback.

For plugin-owned recurring jobs, register a hook and create a cron command using the bakin:<pluginId>:<action> convention. Do not use cron for task-backed workflow timing. Messaging Plans use explicit activation and scheduled task records (availableAt) so dispatch remains the single wakeup path for content prep.

Repository layout

bakin-bits-official/
├── catalog.json  # storefront index consumed by Bakin's Explore plugin
├── plugins/      # installable plugin packages (one dir per plugin)
├── agents/       # installable agent packages
├── packs/        # capability / skill packs (one dir per pack)
├── assets/       # shared brand assets (logo, etc.)
├── test/         # shared test setup (DOM globals)
├── test-sdk/     # mock @makinbakin/sdk used during local tests
└── types/        # shared ambient TypeScript types

catalog.json — the storefront index

Bakin's Explore plugin fetches catalog.json from this repo's main branch (user-triggered "Refresh catalog"). It's schema v2 (defined in Bakin at src/core/curated-catalog/schema.ts): one entry per published package with kind, category, useCases, iconUrl (agent avatars), and screenshots. Descriptions here are plain-English storefront copy and may differ from the technical manifest descriptions. test/catalog-contract.test.ts keeps the catalog honest — every source/iconUrl/screenshot must exist in this repo and every published package must be listed. When you add or remove a package, update catalog.json in the same PR.

Contributing

New plugins and improvements are welcome. Start from plugins/_template, follow the hot-reload contract, and open a PR against main. The full contributor flow — manifest rules, hot-reload constraints, review focus areas, and release tagging — is in CONTRIBUTING.md.

Security

Found a security issue? Please report it privately per SECURITY.md, not as a public issue.

Code of conduct

Participation in this project is governed by our Code of Conduct.

License

MIT — see LICENSE. Plugin and agent-package authors retain copyright on their contributed work; the MIT license applies to the repository scaffold and official packages authored by the Bakin core team.