intentic example extension
The reference intentic extension: one contribution of every kind the extension API
offers, in as little code as each one takes. It is meant to be read start to finish in a sitting, and cloned as
the starting point for a real extension.
It is also the thing that proves the publishing path works. Everything here was built with npm-published packages
only — no monorepo, no private registry, no build service — and installed into a real sandbox from a commit sha.
What it does
The agent leaves short notes with a CLI; the owner reads them in a rail tile that updates the moment one lands.
intentic-example add "the flaky test only fails with a cold cache"
↓ writes .intentic/example-notes.json
↓ the daemon's file watcher matches contributes.files
↓ invalidates the `example-notes` query key
the Example tile refreshes — no polling, nothing subscribed
That loop is the smallest thing that touches both halves of an extension: the agent's side (a tool on PATH, a
skill telling it when to reach for it) and the owner's side (a view, a badge, a setting).
What each file is for
| Path |
Contribution |
Why it's interesting |
intentic-extension.json |
all of them |
The approval surface. The install dialog renders exactly this, and the host refuses anything the file didn't declare. |
src/extension.ts |
activate() |
Registers the view and the command, and starts the badge. Everything it registers is disposed through context.subscriptions. |
src/ExampleView.vue |
views |
The rail view. Read the comment at the top before styling anything of your own, or drawing a loading state: the list remembers its own shape (v-skeleton-source) and <SkeletonSnapshot> draws it back while the notes load. |
src/useNotes.ts |
files |
The query key whose first part is what contributes.files invalidates — the entire wiring for live updates. |
src/badge.ts |
views[].badge |
Module state on its own timer, and the two reasons it cannot be the view's query or the file push. |
bin/intentic-example |
bin |
Plain ESM, no build step: the daemon puts this directory on the agent's PATH and the file itself is the approved code. |
plugin/ |
agent |
A Claude Code plugin directory, handed to the Agent SDK as-is. The skill is how the agent learns the CLI exists. |
test/activate.test.mjs |
— |
Runs the built bundle against a host stub that enforces the manifest. Catches code/manifest drift, which is the failure that actually happens. |
Build, test, install
npm install
npm run typecheck # vue-tsc over src/
npm test # node --test against dist/ — build first
npm run build # → dist/extension.js, one file, 6 kB
git add -f dist/extension.js && git commit -m "release 1.0.0" && git push
git rev-parse HEAD # this sha is what you install
Then in the app: Capabilities → Add → Extension, paste the repo URL and that sha. There is no packaging step
and no upload — the daemon clones the sha you name and runs what is in it, which is why dist/ is committed and
why .gitignore deliberately does not list it.
Reload the app to load the UI; the agent-side contributions (bin, agent) apply from the next turn.
Two rules that are not preferences
The bundle must be one file with the host's packages external. The loader fetches it with an auth header and
imports it from a blob: URL, so a relative chunk import has no base to resolve against, and a second copy of
vue or @tanstack/vue-query would fork reactivity and the query cache. vite.config.ts has both settings with
the reasoning inline.
Styling is not Tailwind. The app's Tailwind build scans its own sources; it cannot scan a bundle it does not
build, so a utility class in a third-party view resolves only if the app happens to use it somewhere else —
three-quarters of a design system, at random. What is reliably available is what the design system ships as
authored CSS: the .ui-* classes (.ui-page, .ui-card, .ui-card-dashed, .ui-field, .ui-code), the
.skeleton class every loading placeholder is painted with, and the role tokens behind them (--color-card,
--color-content, --color-muted, --color-line, --color-canvas), which flip between light and dark on their
own. This view uses only those, and recolors with the shell for free.
Note also that vite's library build emits an SFC style block as a separate CSS asset, and nothing fetches it.
Style inline, or inject a sheet from activate().
The UI kit is the host's
@intentic/extension-ui is the component kit first-party views render with. The npm package carries its types and
a bridge, not the components: the host publishes its own instances at runtime through the import map, so the kit is
marked external in vite.config.ts like vue, and what renders is always the shell's own. This view takes one
thing from it, the loading placeholder (SkeletonSnapshot, vSkeletonSource), and keeps the rest to plain markup,
which shows how little a view needs; a view of your own may use as much of the kit as it likes.
One thing that is missing, honestly
@intentic/sandbox-contract cannot be installed as of this writing: its published tarball depends on
@intentic/registry@0.0.0, which was never published. It carries the daemon's wire schemas, so once it
installs, WorkspaceFileSchema.parse(...) replaces the hand-rolled type guard in src/notes.ts.
Getting listed
Add the topic intentic-extension to the repository. A nightly job on the
registry finds it, checks the manifest parses, resolves the latest commit
and opens the listing pull request for you. That is the whole submission process — there is nowhere to sign up,
and the listing is a pointer to this repo at a sha, not a copy of it.
MIT.
Key files