Kraddies
Named Workers that live between sessions, with a painted look, a compass, keepsakes, routines and a history of their own.
A Kraddie is a Worker with an identity that lives between sessions. It has a name you give it, a design you paint, a harness and model, and a repository it works in. It owns automations, its routines, and each of their runs works as a Worker session without a lead, reporting through the attention queue.
Kraddies belong to you, not to an environment: they are kept as files in the config folder and answer the same from every environment.
Open the Kraddies view
The top bar switches between the views Sessions, Notes, Automations, Kraddies and, on a code host you are signed in to, Review. The command palette also has Toggle Kraddies view and Hatch a Kraddie….
The view lists every Kraddie as a card. From a card you can visit its page, wake it up now, rename it or change its agent and home, paint it in the studio, save it as a .kraddie file, or say goodbye to it. Import… brings one in from a file.
Hatch a Kraddie
Open the form
Press Hatch a Kraddie in the Kraddies view, or run Hatch a Kraddie… from the command palette.
Name it
There is no default name: the form asks "What should we call it?". Need an idea? shows four names from a short list, leaving out those already taken.
Pick its agent and model
The agent must be a harness that can run as a Worker chat. The model is a model id, or empty for the agent's own pick.
Give it a home
The home is the repository it works in, taken from an open group of a git repository. Without one, the form asks you to open such a group first.
Naming rules
| Rule | Message when broken |
|---|---|
| Not empty | A Kraddie needs a name |
| At most 40 characters | A Kraddie's name has at most 40 characters |
| At least one letter or digit | A Kraddie's name needs a letter or a digit |
| Unique | Another Kraddie already answers to that name |
The name is shown as you wrote it. Its id, used in file names and by the krad CLI, is a lowercase slug of the name: Owl Watch becomes owl-watch. Commands accept either the name, in any case, or the id. Renaming a Kraddie renames its files too.
The Kraddie page
A Kraddie's page shows a stage with its animated look and mood, and five parts picked from a sliding switch:
| Part | What it holds |
|---|---|
| At a glance | The Trail, Day so far, On the horizon, Fresh from today and Logbook cards |
| Compass | What it should always keep in mind |
| Keepsakes | Short notes it carries from run to run |
| Chats and memory | Its chats, what they left behind and whose memory it reads; see Kraddie chats and memory |
| Tuning | Agent, reach, sessions and rounds |
The stage has buttons to rename it, open the studio and run its manual routine now. A Kraddie that is switched off is resting: its routines wait until you wake it up.
Moods
A Kraddie's mood follows the state of its current run or chat:
| Mood | When | Default motion |
|---|---|---|
| Idle | Napping between jobs | Breathe |
| Working | Busy at work | Bounce |
| Waiting | Needs a word from you | Sway |
| Done | Wrapped up | Hop |
| Error | Tripped over something: a run failed or was interrupted | Shake |
The studio
The Kraddie studio is the sheet where you paint a Kraddie. Open it from a card, the page's Studio button or Tuning › Look.
- Canvas. 24 by 24 pixels.
- Layers. Up to eight, each with a name of up to 24 characters, which you add, remove, show or hide.
- Faces. Paint on picks a layer or the face of one mood, so every mood gets its own expression.
- Tools. Brush, Eraser, Fill, Line, Rectangle and Ellipse.
- Palette. Up to 16 colours; add a colour or recolour the selected slot.
- Animation. Each mood has its own: Still, Breathe, Bounce, Sway, Shake or Hop.
- Body style. Start again from a Kraddie style: Kraken, Blob, Bot or Ghost.
- Undo and Redo. Up to 64 steps. Save design keeps the result; Cancel leaves the design as it was.
Compass
The compass is a Markdown document of standing instructions that rides along with every run and every Kraddie chat. It is kept as compass.md in the Kraddie's folder, up to 20,000 characters. A new Kraddie starts with a short template; while the compass is still that template, nothing is added to its runs.
Keepsakes
Keepsakes are the short notes a Kraddie carries between runs. Each is one line of up to 300 characters, and a Kraddie keeps up to 200; the page shows how many are kept.
- Add, edit and remove them in the Keepsakes part of its page.
- The Kraddie adds one itself with
krad kraddie remember <name> <text>, a hint every run receives. krad kraddie memory <name>prints them.
krad kraddie remember owl "CI uses runner 7"
krad kraddie memory owlOnly you change what a Kraddie remembers. A remember sent from a chat is refused; it works from your own terminal and in the app.
At a glance
| Card | What it shows |
|---|---|
| Trail | Six months of footprints, one square a day |
| Day so far | Counted since midnight: routines fired, sessions, lines and merged pull or merge requests |
| On the horizon | The next planned runs, and rounds once things go quiet |
| Fresh from today | What finished since midnight |
| Logbook | Every run, newest first, with what woke it and how it ended |
The trail
The trail is a heat map of the last six months, one square a day, coloured in five steps from quiet to busy. Pick what it counts: Runs, Lines (lines changed), Tokens or Cost. The app keeps 200 days of activity per Kraddie.
Run history
Each automation keeps its last 50 runs. A run records when it started, what woke it (a schedule, a run missed while the app was closed, an app or code host event, Run now, the krad CLI or a check-in), its outcome and the session it opened.
| Outcome | Meaning |
|---|---|
| Starting, Working | The run is under way |
| Needs you | It waits for you in its session |
| Finished | It ended its turn |
| Failed | It could not start or stopped with an error, shown as the reason |
| Skipped: already running | The same automation was still running |
| Skipped: too many runs at once | Three automation runs were already running |
| Interrupted when the app closed | The app quit while it ran |
Tuning
| Section | Settings |
|---|---|
| Look | Open the studio |
| Brain | Agent and model, Thinking effort and Permissions, each with Default |
| Reach | Repositories it may read besides its own home: Lend it this group adds the selected group's repository, Take it back removes one |
| Its sessions | List them in the sidebar, or Tuck them under its row in the sidebar's Kraddies list; Model for its sessions, which defaults to the same as its brain |
| Rounds | Make rounds on its own, and After a quiet spell of 15m, 30m, 1h or 2h |
| Fresh start | Start over clears its run history; its compass, keepsakes and routines stay put |
Rounds
Rounds are an optional, read-only look over its work after a quiet spell. Rounds are off by default; once on, the default quiet spell is 30 minutes. A check-in runs in plan mode, under a brief that tells it not to edit files, run commands that change anything, commit or open pull requests. It reads its recent runs, the sessions it left open, your notes and the attention inbox, and suggests in a few lines what would be worth doing next. When it has nothing to suggest, it stays quiet.
Rounds wait while the Kraddie is already running, during quiet hours, when spending is over its budget and when every run slot is taken.
Working folder
A Kraddie's home is its working folder. Its automations run there, and its Kraddie chats open there. In Chats and memory › Working folder, Use the open group sets it to the selected group, and Let each chat pick clears it, so each chat opens in the group you are in.
Export and import
Export
On the Kraddie's card, choose Save it as a .kraddie file and pick where. The file holds its name, design, harness, model, settings and automations.
Import
In the Kraddies view, choose Import… and pick the file. The Kraddie and its automations are added with an empty run history. A file whose Kraddie has the name of one you already have is refused.
What stays behind on export: its home, the repositories it was lent, the Kraddies it reads, the sidebar group each automation opens in, and its compass, keepsakes, digests, activity and run history. A file written by a newer app version is refused with the format it uses.
Older .kradpet files still load. A file of the first format, before automations, becomes a Kraddie with one automation that holds its old instructions and triggers, plus a manual trigger.
Files on disk
Kraddies live in the kraddies folder of the config folder:
kraddies/
owl.kraddie name, design, harness, model, home, settings
owl.automations.json its automations
owl.1.runs.json run history of automation 1
owl/
compass.md its compass
memory.json its keepsakes
activity.json the days behind its trail
digests.json its chat digestsMigrating the old folder
The feature was once called by another name, and its folder was pets. When the app starts, it moves that folder's contents into kraddies, renames .kradpet files to .kraddie and renames each soul.md to compass.md. A soul.md that still holds the old default text is removed instead. Files already present in kraddies are never overwritten, and the old folder is removed once it is empty.
krad pet still runs krad kraddie, from the same former name.
Saying goodbye
Deleting a Kraddie asks first: its automations and their run history, its keepsakes, its chat digests and its profile are deleted for good. Chats it already had stay open.