This release is a pre-release and may not be stable for production use.
hey-dave
A terminal coding-agent harness that runs D.A.V.E. (Digital Assistant for
Various Endeavors) natively — not as a plugin inside someone else's harness.
D.A.V.E. is an independent implementation derived from the legacy skill bundle
in thesawdawg/agent-skills at commit ca9118c; see
src/hey_dave/dave/NOTICE for attribution.
D.A.V.E. is a personal assistant persona — opinionated, occasionally witty, not a productivity product. The banner shown at startup says so on purpose: unstable, opinionated, and sometimes unhelpful. Not a productivity tool.
An animated, watch-only tour lives in
docs/walkthrough/
(open index.html from a checkout in a browser). Nine goal paths, from setup
to delegation, each with scripted terminal scenes and a strip showing what the
harness does underneath.
Core redesign in progress
D.A.V.E. keeps your work as Tasks: persistent checklists with one level of children, audited memory (where you stopped, the next action, decisions, blockers), counted time, Projects, Goals and Promises (spec 11, spec 12). You can be interrupted by an outage, capture it as a sidequest, switch, and come back to the same checklist and memory — in the previous conversation or a fresh one backed by Task memory.
dave init (or dave vault init) creates a fresh vault. An older schema-1
vault is never converted or changed: hey-dave refuses it and asks you to choose
an empty folder with DAVE_VAULT=<dir> or `dave config set dave.vault_path
Install
Python 3.14+ required, on Linux, macOS or WSL: the vault uses file locks, so on
native Windows dave says so and stops. hey-dave is in alpha: releases are
pre-releases, so installers need to be told to take one.
# uv tool (recommended)
uv tool install --prerelease=allow hey-dave
# or pip into any environment
pip install --pre hey-dave
# or from a checkout
uv tool install .
# Docker (includes SearXNG and Ollama profiles)
docker compose -f docker/compose.yaml run --rm dave --version
Upgrading from dave-harness. This project used to be called
dave-harness. Remove the old tool (uv tool uninstall dave-harness) and
install hey-dave; the command is still dave. On its first start, dave
moves your folders to the new name: ~/.config/dave-harness,
~/.local/share/dave-harness (sessions and the vault) and
~/.local/state/dave-harness become …/hey-dave, and a project's
.dave-harness/ becomes .hey-dave/ when you open it. Each move is
printed. Folders not yet moved keep working, and DAVE_HARNESS_CONFIG is
still read when HEY_DAVE_CONFIG is not set. Hook commands now see
HEY_DAVE=1 instead of DAVE_HARNESS=1.
First run
dave init # nine-step guided setup: models, permissions, tracker, vault
dave init --vibe # a model, then D.A.V.E. from three plain-language answers
dave doctor # environment + config health checks (--json for machines)
dave # the TUI
dave --resume # the TUI, starting with a list of sessions to pick up
dave run "summarise this repo" # headless
The wizard guides you through setup. Each step opens with a progress rail
(── ●●◉○○○ 3/6 vault ───) and a short card that says what the
step is for and what to pick. Every answer says what it leads to, and typing
? at any question explains it in more detail.
The first step asks where D.A.V.E.'s model will run. It looks for a Codex
sign-in (~/.codex/auth.json), and for Ollama and LM Studio running on this
machine, then lists what it found next to Ollama on another computer and any
OpenAI-compatible API (OpenAI, OpenRouter, vLLM…). Found servers show how many
models they have, and Ollama models without tool support are marked. For an
API key it asks for the name of the environment variable, not the key, and
says whether that variable is set. Then you pick a permissions preset
(cautious or developer), a tracker backend and a search backend, and the
wizard initialises the D.A.V.E. vault. Every question is a numbered list:
Enter takes the default, a number picks, and open questions end with "type
your own…". Everything is shown as a diff and written only after
confirmation.
dave init --vibe (or /init vibe in the TUI, once a profile works) sets up
D.A.V.E. from three answers instead of the permission, tracker, search and
persona steps. Its first four steps (models, profiles, vault, theme) need no
model, and it will not move past the first until one is set up:
- What is this D.A.V.E.'s purpose?
- What is D.A.V.E. explicitly denied?
- What should I know about you? (optional)
The model may ask up to two short follow-ups per answer, then proposes settings. Examples:
- "ask before any git commit" becomes the rule
permissions.ask: bash(git commit*). - "keep everything in this directory" becomes
permissions.confine: "project". File writes outside the project are denied, and shell commands that name outside paths ask. - Anything no rule can express is saved as an advisory restriction. The model is told about it, but nothing enforces it.
dave init --vibe also asks for a theme. The same theme colours the TUI and
the interview itself, and telling the interview about contrast or colour
needs can propose one. Both wizards are in colour: step headings, questions,
option numbers and the default each have their own. NO_COLOR turns terminal
colour off.
You tick what to keep. Suggested allow rules start unticked, and the harness refuses broad allow rules and any change to providers, secrets or existing deny rules. Nothing is written until you approve, and the interview is not saved.
Using the TUI
| Key | Does |
|---|---|
| Enter / Shift+Enter or Ctrl+J | send / new line (many terminals cannot tell Shift+Enter from Enter and send it; Ctrl+J always works); during a turn Enter queues the message (up to 3, tui.limits.queue) and it is sent when the turn ends |
| Up (first line) / Down (last line) | step through sent-message history; with messages queued and the input empty, Up pulls the last one back to edit and Esc drops it |
/ |
open the command list — Up/Down/PageUp/PageDown move, Tab completes, Enter runs, Esc closes |
/command |
after a command and a space, the list shows what it takes next (/config lists theme, music, vault…; <placeholders> show as hints) — Tab completes the word, Enter completes a word you typed or picked and otherwise runs the line |
@ |
open the file list — Tab or Enter completes the path (a folder opens its entries), Esc closes |
! |
run a shell command yourself: ! git status shows its output in the chat; !! make test also sends the output with your next message |
| PageUp / PageDown | scroll the transcript (the input box always keeps focus) |
| shift+tab | toggle plan mode (between turns) |
| ctrl+p | command palette |
| ctrl+b | show or hide the sidebar; under 110 columns, open or close it as a drawer (Esc closes it too) |
| ctrl+t | pending tracker proposals |
| ctrl+o | the activity list: every tool call, injected command text and event in full (on a [pasted …] placeholder: expand it) |
| ctrl+c | with text selected: copy it. Otherwise cancel the turn (queued messages pause: Enter on an empty input sends the next); while idle, clears a paused queue first, and twice quits |
| right-click | with text selected: copy it; otherwise paste |
| ctrl+v / alt+v | paste text / paste an image from the clipboard |
The indicator beside the input shows what is running (thinking, the current
tool, waiting for you, subagents) and for how long.
Shell commands. Start a message with ! to run it in your shell
instead of sending it: ! echo "Hello" shows Hello and [exit 0 · 0.0s]
in the chat. It runs in the session's folder with your environment, and
D.A.V.E. never sees it. Use !! to share the output: !! pytest -x runs
it and attaches the output to your next message ("why does this fail?").
Permission rules don't apply, since you typed it, and the model can never
run a ! command. Each command starts fresh (cd does not carry over),
ctrl+c stops it, and during a turn it waits in the queue. Over Telegram !
is refused.
Screen sizes. The TUI is fully usable from 80×24 and fits the space it has:
- From 110 columns: the sidebar sits beside the chat: 32 columns, or about a quarter of a wide screen (up to 56).
- Below 110 columns: the chat gets the whole width.
ctrl+bopens the sidebar as a drawer over the chat, and Esc closes it. The header shows what the sidebar would, on one line: the selected Task and its minutes, checklist progress, running subagents. The activity indicator moves to one row under the input. - The input box is one line tall until you type more; it grows up to 8 lines (4 on a short screen).
- The header and status bars drop their least important fields rather
than being cut off;
ctx %and the error count always show. - Every picker and card (
/model,/theme,/resume,/music config,/vault config, permission and plan cards…) fits the screen, with its keys in view. - Permission cards show the change. An
editorwritecard shows a colored diff against the file on disk (+/−counts, line numbers), and says so when the edit would fail. Long diffs show their first lines;eexpands the rest.
Make it yours. The top-level tui section of the config changes the
layout and keys, and applies as soon as it is saved:
"tui": {
"sidebar": { "sections": ["today", "tasks", "activity"], "position": "left", "shown": true },
"header": ["name", "mode", "ctx", "usage", "profile"], // fields, in order
"status": ["tokens", "music"], // the error count always shows
"keys": { "sidebar": "ctrl+s", "permission.allow_once": "y" },
"layout": { "sidebar_inline_from": 120, "composer_lines": 12 },
"skin": { "placeholder": "Ask D.A.V.E.", "sections": { "goals": "Aims" } },
"skins": { "matrix": { "rain": false } },
"banner": false
}
sidebar: which sections show, in what order, on which side, and whether it starts open. The D.A.V.E. panel sections (dave,goals,today,coming_due,long_term,promises,general,proposals,subagents) scroll together as one panel. The oldnowstill loads and shows nothing.headerandstatus: which fields the bars show.keys: any key in the list above, and every card's letters./keyslists what can be changed. Esc, Enter, ctrl+c and the arrows stay fixed, and a key that would type into the input or clash on a screen is refused. The hints on each card show the key you chose.layout: the sizes above: where the sidebar goes inline, how wide it is, how tall the input grows.skin(every theme) andskins.<theme>(one theme): the words and glyphs a theme uses: the header name, sidebar headings, activity tags, spinner, placeholder, rain, andtune, the built-in music it plays.chat: how the transcript draws your messages, the model's replies and command output: a preset (classic,bubbles,boxed,compact,spacious,minimal) and options over it per role (frame, colours, alignment, width, padding, gap, a name label)./config chat bubblesswitches and saves it;/config chat user align leftchanges one option. Colours follow the theme and text stays readable.themes: your own themes (below).banner:falseturns the startup banner off.
The chat holds only the conversation. Tool calls, the text a slash command
injects for the model, and harness events (compaction, warnings, subagent
reports) are listed under Activity at the bottom of the sidebar, in time
order, each tagged with its type — TOOL, CTX (injected context) or EVT
— in its own colour. Click a line, or press ctrl+o, to see it in full.
There, c copies the entry to your clipboard, and s saves it to a file
under ~/.local/state/hey-dave/exports/.
Copy and paste.
- Copy. Drag over any text (the chat, Activity, the input box, an open card) to select it, then press ctrl+c or right-click. A toast says what was copied and how. With nothing selected, ctrl+c still cancels or quits. shift+drag makes your terminal's own selection instead, for its own ctrl+shift+c.
/copycopies without the mouse, word for word as it was said:/copy: D.A.V.E.'s last reply, as markdown;/copy 2: the reply before it;/copy code: the last code block of the last reply, without the fences (/copy code 2is the one before);/copy all: the whole conversation.
- How it reaches the clipboard. Copying uses
clip.exeunder WSL,pbcopyon macOS,wl-copyorxclip/xselon Linux, and otherwise the terminal (OSC 52, which some terminals ignore).harness.clipboard: nativeorosc52forces one way. - Paste with ctrl+v, or right-click with nothing selected. A long
paste (over 20 lines or 2,000 characters,
harness.paste) shows as[pasted #1 · 240 lines]:- the model still gets all of it, after your words;
- Backspace deletes the placeholder whole;
- ctrl+o on it puts the text back in the box.
- Images. alt+v pastes the image on your clipboard (a screenshot,
say) as
[image #1]. It is sent as an image with your message and saved under~/.local/state/hey-dave/pastes/. That file is deleted once no saved session uses it.
@ puts files and folders into the context. Type @src/app.py (or
@"notes/big plan.md" for a path with spaces) anywhere in a message:
- A file is sent to the model with its contents, after your words.
- A folder is sent as a list of the files in it. In a git repository,
files your
.gitignoreexcludes are left out. - An image (
.png,.jpg,.gif,.webp, up to 5 MB, 4 per message) is sent as an image, and so is one D.A.V.E. opens withread. - Typing
@namelists matches from the folder you're in and from anywhere in the project, skipping what.gitignoreexcludes. You can still type the full path to an ignored file to attach it.
The chat keeps what you typed. Each attachment is a CTX » @path row in
Activity. Some things are refused, with a warning in Activity:
- a path your
permissions.denyrules block; - other binary files, and
.bmpimages; - files over 4 MB.
A file longer than 100,000 characters is cut off, and the model is told
where, so it can read the rest. dave run "explain @src/app.py" works the
same way. It also works in the arguments of commands from files (D.A.V.E.,
skill and your own commands): /mycheck @src/app.py attaches the file
after the command's text. A command can turn that off with mentions: false in its frontmatter. Built-in commands like /title take @ as
plain text.
Slash commands:
-
/helplists the common commands by category;/help alllists every one, and/help <word>searches (/help clockfinds/time)./<command> --help(or/help <command>) shows a command's details, subcommands and examples without running it. Typing/offers the common commands first. -
A command missing a required argument shows its usage instead of running.
-
/clearstarts a new, empty session and keeps the old one in/resume. It keeps your Task or General work, the model and the mode, and drops session-only permission grants and the queue./clear deletealso deletes the old session after you confirm; a conversation your vault archives is never erased, so that form refuses it. Not while a turn runs. -
/session refocus [title](or/refocus) branches into a new session that starts from a short brief of this one, for a tangent that should not pollute the current work. The model writes the brief and adds the files touched and the Task checklist; you edit it in a card (ctrl+sstarts,esccancels with nothing changed). The current session stays saved, so/resumegoes back to it. Not while a turn runs. -
/docsopens the documentation in your browser: the specs and architecture notes as searchable pages, the interactive diagrams and the animated walkthrough. It runs a small server on127.0.0.1only (the address is also written to the chat, for a terminal that cannot open a browser)./docs diagramsand/docs walkthroughopen those,/docs <words>opens a search, and/docs stopends the server, which also stops when you quit. The stage plans and reviews are not included. An install from PyPI carries the docs; a checkout serves its owndocs/. -
/resumepicks up a saved session. It lists this project's sessions, most recently active first. Each row has the title, when you last used it and how many messages it holds, plus the first line of your last message and of the last reply. Under the list, a preview shows the highlighted session's last few messages. Type to filter by title, text or id; Tab switches to every project; Enter resumes; Esc stays where you are.dave --resumestarts the TUI with the same list,/resume <id>anddave --resume <id>go straight to one, anddave --continuetakes the latest./sessionsprints the same details for the last ten. -
/configgathers the setup commands:/config theme,chat,music,vault,remote,plugins,mcp,permissionsandskills, each with the arguments it always had (for example/config vault sync;chatis new, seetui.chatabove). The old names still work but are no longer listed;/dave,/init,/keysand/errorsstay as they are. Bare/configlists the areas, and what a remote chat may run is unchanged. -
/sessiongathers the session commands:/session list,title,compact,export,copyandrewind(for example/session copy code)./sessions,/title,/compact,/export,/copyand/rewindstill work but are no longer listed.listandcopyrun during a turn, as before;export,copyandrewindstay in the terminal. -
/modelopens a picker of profiles and every provider's models;/model <profile> [model],/model <model>and/model <provider>/<model>switch directly. The choice is kept with the session. -
/rewindundoes D.A.V.E.'s file changes, turn by turn, even without git. Pick a turn to put the files it (and later turns) changed back as they were before it:aalso cuts the conversation back to that message, and puts the message back in the input box;ccuts only the conversation.
Files you changed since D.A.V.E. wrote them are shown as conflicts and need a second yes. Changes made by shell commands are not recorded, so turns where bash ran say so. A rewind can itself be rewound. Settings live under
harness.checkpoints. -
/init vibeconfigures D.A.V.E. from three answers (see First run). -
/themeopens a theme picker that previews as you move;/theme <name>switches directly. Both saveharness.theme. Each theme shows its WCAG contrast rating (AAA or AA). Every theme is tuned for readability: all text, including placeholders and muted text, reaches at least AA on every background it sits on, with muted text at 6:1 or better. The dark classics are adjusted the same way and keep their colours wherever they already passed. The themes come in five groups, plus your own:-
D.A.V.E.:
dave-dark(the default) anddave-light. -
Accessible:
dave-high-contrastanddave-high-contrast-light(AAA), anddave-colorblindanddave-colorblind-light(Okabe–Ito colour-blind-safe colours, AA). -
Dark classics: Dracula, Nord, Gruvbox, Tokyo Night, Catppuccin Mocha, One Dark, Monokai, Solarized Dark and Rosé Pine.
-
Immersive:
matrix,dndandlotr. These restyle the whole TUI, not just its colours:matrixis The Matrix: green phosphor on black, digital rain down the left edge, square frames,// OPERATOR-style headings,EXEC/LOAD/SYSactivity tags and a katakana spinner.dndis Dungeons & Dragons: torchlit parchment and gold, double frames, headings such as "The Party" and "Adventure Log" in Fraktur,CAST/LORE/OMENtags and a dice spinner.lotris The Lord of the Rings: gold on the green-black of a Shire night, round frames like hobbit doors, slow glowing runes down the left edge, headings such as "The Fellowship" and "The Red Book",DEED/TOME/SIGNtags, a rune spinner, and background music.
-
Avengers:
iron-man,captain-america,thorandhulk. Immersive like the three above, and each plays its own music:iron-man: the armour's cherry red and gold, frames with a lit title bar like a heads-up display, hex telemetry down the left edge, headings such as "J.A.R.V.I.S." and "Iron Legion",FIRE/SCAN/PINGtags, and a hard-rock riff.captain-america: the shield's navy, white and red, heavy-rimmed frames, star headings such as "Command" and "Field Log",OPS/INTL/COMMtags, and a brass march.thor: storm blue, gold and red, heavy iron frames, lightning and runes down the left edge, headings such as "The All-Father",BOLT/RUNE/HORNtags, and a thunder saga with horns and a choir.hulk: gamma green and purple, solid slab frames, headings that shout ("SMASH LIST", "RAGE LOG"),HIT/LOOK/ROARtags, a rage-meter spinner, and a rampage that breaks into a lonely piano.
A terminal app can't change your font. These themes use Unicode letterforms instead (Fraktur, half-width katakana, runes), which need a font that has them or your terminal's fallback. Windows Terminal and most Linux terminals have one. With
TEXTUAL_ANIMATIONS=nonethe rain holds still. -
Yours: themes you define under
tui.themesin the config. Each starts from a built-in theme (base) and takes its frames, words, music and banner quotes, with any colours and skin parts you set on top:"tui": { "themes": { "ocean": { "base": "matrix", // unset: dave-dark "description": "deep sea blues", // shown by /theme "colours": { "primary": "#4aa3ff", "background": "#001018", "muted": "#7fa0b8" }, "skin": { "app_name": "~ dave ~", "tune": "thor" } }, "nord": { "colours": { "accent": "#ffcc00" } } // your version of Nord } }The colour roles are
primary,secondary,accent,success,warning,error,foreground,background,surface,panel,mutedandborder, as#rrggbb. Your themes are made readable like the rest: a colour that falls under AA is lightened or darkened just enough, and/themeshows the rating. They are listed under Yours, and a theme named after a built-in replaces it. A change applies at once, even to the theme on screen;/davecan make it for you.
-
-
/musicplays music while you work.-
/music configis the easiest way to set it up. It opens a screen where you pick a source and fill in its settings. It checks what works as you type: the player, the folder's tracks, and the Spotify sign-in and open devices. Nothing plays while you set up. Enter saves, and ctrl+l signs in to Spotify. -
Or use
/music source …to pick what plays. The choice is saved: -
tune(the default): the theme's own music, forlotrand the four Avengers. It starts with the theme, changes when you switch to another of them, and stops when you switch to a theme without music. Each piece is original (none is a film's score), synthesised once and cached: a folk air forlotr, a rock riff, a march, a thunder saga and a rampage for the Avengers. Setharness.music.fileto play your own audio file instead, in any of those themes. -
local <folder>: your own.mp3(or.flac,.ogg,.m4a, …) files, in any theme, as a playlist. For example,/music source local ~/Music/focus. -
spotify: your Spotify account. The harness controls Spotify wherever it's open (the desktop app, your phone, a speaker), and the music plays there. You need Premium and your own client ID:- Create an app at https://developer.spotify.com/dashboard. Tick
Web API, and add the redirect URI
http://127.0.0.1:8898/callback. - Run
/music login <client-id>and sign in in the browser. - If the page after sign-in doesn't load, paste its address:
/music login <address>.
The tokens stay in the state directory (0600), and
/music logoutdeletes them./music play <link>plays a Spotify playlist, album or track link. - Create an app at https://developer.spotify.com/dashboard. Tick
Web API, and add the redirect URI
-
youtube(saved asmedia): the system media keys. They control YouTube in a browser or the YouTube Music app, or any other player that has the media session: Windows' under WSL, orplayerctlon Linux. You start what plays in that player; the harness only plays, pauses and skips.
-
-
Controls:
/musicsays what's playing, where, and at what volume.on,off,play,pause,resume,next,prev,volume <0-100>,shuffle on|offandrepeat off|all|onework where the source allows.- F7/F8/F9 are previous, play/pause and next.
- The status bar shows the current track, for example
♪ 02 Second (2/12).
-
The harness's own player (for
tuneandlocal) is the first one it finds:ffplay(from ffmpeg),mpv,pw-play,paplay,afplayoraplay.- Choose one with
harness.music.player, and set the volume with/music volume(harness.music.volume, default 40). - On WSL,
ffplayworks through WSLg's sound server. - It never starts loud. Before starting on its own, it reads your system
volume (Windows' volume on WSL, PipeWire, PulseAudio or ALSA on Linux,
or macOS's). If system × music volume would be over 25%, it holds and
asks: lower the volume, or
/music onto play anyway. That confirms it for the rest of the session.
- Choose one with
-
DAVE_NO_AUDIO=1keeps the harness silent: no player, no media keys, no Spotify calls.harness.music.player: "none"silences the harness's player only. -
/copycopies a reply, a code block or the conversation (see Copy and paste above). -
/errorslists what went wrong this session (see When something goes wrong below). -
/statussummarises the session: profile, context (and images in it), the selected Task, subagents, waiting reports and proposals, and remote state. -
/remoteconnects the open session to a chat app (see Remote). -
/vaultshows vault sync;/vault configsets it up;/vault sync,/vault login [client_secret….json|client-id],/vault logout [--forget-client](see Sync across devices below). -
D.A.V.E. commands:
/task,/return,/general,/sidequest,/goal,/promise,/time,/memory,/notice,/brief,/check,/delegate,/project,/intake,/review,/standup,/supervise./focusand/parkare aliases of/task startand/sidequest, and/unfocusedof/general; aliases still work but are not listed in/helpor completion (turning a command off incommands.disabledturns its aliases off too, and a grouped form such as/session exportfollows its old nameexport). The retired/mission,/itemand/prioritiessay what replaced them.
dave run "/<command> --help" prints the same help headless.
Permission cards
When D.A.V.E. needs your yes, the card shows the call and how long an answer can last:
| Key | Does |
|---|---|
a |
allow this call |
s / p / g |
allow this session / for this project / everywhere: every project, every open and future session |
d |
deny: d again denies this call; s / p / g deny for that long; Esc goes back |
n |
deny and tell the model why |
b |
widen what s/p/g save: the exact call, its prefix (bash(git status*), a folder, mcp(redmine:*)), or the whole tool (bash(*)). The card shows the rule |
| Esc | deny this call |
Project answers go to .hey-dave/config.json, everywhere answers to
~/.config/hey-dave/config.json, as permissions.allow or
permissions.deny. A file path saved everywhere is absolute. A project's
rules add to the global ones and never hide them. Every open session picks
up a saved rule on its next call. /permissions lists the rules by scope
and /permissions remove <rule> takes one out; /permissions reset-session drops this session's. Over /remote answers are for this
call only, unless you raise remote.permission_ceiling (see Remote).
Plan mode
Plan first, then change things. /plan add a --json flag to dave doctor (or shift+tab, then type) puts the session in plan mode:
- D.A.V.E. can read, search and run look-only commands:
git status,git log,git diff,git show,ls,cat,head,tail,wc,rg,grepandfind. Change the list withpermissions.plan_bash. Every other command, every write and edit, and redirection are denied, whatever your allow rules say. So arefind -delete/-execand D.A.V.E. state writes. A listed command still needs your usual allow rule or a yes on its card. - The header says
mode: planand the input box takes the theme's warning colour. - It ends with a plan card:
aapproves: plan mode ends and D.A.V.E. implements the plan in a new turn, so/rewindcan undo it as one step;malso saves the numbered steps as the selected Task's checklist, ready for/supervise, after an exact review (shown only when a work Task is selected);kkeeps planning, with your feedback;dor Esc discards the plan and stays in plan mode.
/plan or shift+tab toggles plan mode, and /plan on|off sets it. (/mode
groups /plan, /chat and /general as /mode plan, /mode chat and
/mode general; bare /mode shows the plan and chat-only state, and the old
names still work.) The mode
is saved with the session. Over /remote the card has Approve and Discard
buttons, and any message is feedback. dave run --plan "<task>" prints the
plan and stops (--json emits plan_proposed).
General work and sidequests
/general offers previous General conversations or a new one. Each new
conversation has separate memory and time; restoring one reuses its subject.
General uses normal configured repository permissions. The repository startup
picker offers a Task, a new Task, or continuing General once per conversation.
/unfocused is a discoverability alias for General; /unfocused off opens return.
/general promote [id] reviews title, description, classification, dates and
Project links before turning the conversation into a standalone Task. Its ID,
memory, context settings, conversation history and interval IDs are retained;
its prior time moves out of General and counts once on the promoted Task.
/sidequest [title] offers Save and Save and switch. Project links suggest
standalone work; an explicit root suggests a child or a selected child's sibling.
The modal lets you review every shared Task attribute, multiple Project links,
and the one-level parent. --project <id>, --parent <id> and --switch supply
editable suggestions. Save keeps the current conversation and timer. A failed
switch retains the capture and restores the old selection and manual pause.
/sidequest <title> --switch --carry also writes a brief of the conversation
you leave, lets you edit it, and starts the new Task's session from it (cancel
the brief and the Task is still captured, and you stay put).
/return uses the standard checklist, memory and time recap, with previous
conversation or a fresh conversation backed by memory. Missing checkouts offer
an explicit local attachment or memory-only work. Memory-only conversations
exclude filesystem, shell and delegation tools regardless of context edits or
session grants. Switching to another checkout asks before loading its settings
and discards previous project-relative conversation grants.
Headless callers can use dave general history, dave general show <id>,
dave general promote <id> --yes, dave sidequest, and
dave run --task <id> --memory-only <prompt>. Promotion previews without --yes.
Task list
On work of three or more steps D.A.V.E. keeps a short checklist with
todo_write. It shows in the sidebar's Tasks section, between the
D.A.V.E. panel and Activity: ☐ to do, ◐ in progress, ☑ done, and a
count in the heading (Tasks 2/5). With a work Task selected it is that
Task's persistent checklist (stable child IDs, kept across sessions);
without one it belongs to this session only. It hides while empty, works in
plan mode, and is switched off under /supervise, where the reviewed
checklist is the plan.
Notifications
When you're in another window, the terminal tells you that D.A.V.E.:
- finished a turn that took 15 s or more (
harness.notify_after); - is waiting on a permission card or a plan card;
- has a subagent report ready.
Nothing fires while the dave window has focus, unless you set
harness.notify_when_focused: true.
-
harness.notify: "bell"(the default) rings the terminal bell. Windows Terminal flashes the tab or plays its bell sound, depending on your profile's bell setting. -
"desktop"shows an OS notification with a short text such asturn finished (42s). It never includes tool output.dave doctorshows the route it picked for your terminal:Terminal Route Windows Terminal under WSL a Windows toast (via powershell.exe)Windows Terminal with compatibility.allowOSC777onset harness.notify_via: "osc777"iTerm2, Apple Terminal, ConEmu OSC 9 WezTerm, Ghostty, Warp, GNOME Terminal and other VTE terminals OSC 777 kitty, foot OSC 99 anything else the bell Inside tmux, add
set -g allow-passthrough on. -
"off"turns notifications off./remotehas its own list (remote.notify).
When something goes wrong
A failure shows as a card in the chat, never as a silent freeze or a crash:
✗ Internal error while showing a tool result — KeyError: 'path'
kept: the turn is still running; nothing lost
next: /errors copy 1 to report it
- The status bar counts errors, and
/errorslists them./errors 1shows the newest in full, and/errors copy 1copies a bug report with secrets removed. - The full traceback is in the log.
/errors logprints where the log, crash reports and stall logs are. - Nothing typed is lost. A reply that was streaming when the app closed comes back on resume, marked as interrupted. Your unsent message and queued messages come back too, with the queue paused.
- If the app ever does close on an error, it says so in the terminal. It
prints the command to resume your session (
dave --resume <id>) and the path of a crash report with secrets removed. The next start also notes that the last run did not close cleanly. - When quitting seems stuck, press ctrl+c again. When the whole app
seems stuck, run
dave debug stacksin another terminal. It prints what every part of the app is doing, even while it is frozen, and doesn't stop it. dave doctoralso checks where sessions are saved: whether the folder is writable, whether there is disk space, and whether it is on a slow filesystem (WSL's/mnt/c, network drives). It also lists runs that did not close cleanly and recent crash reports.- A subagent that has been silent for 5 minutes shows
idleon its sidebar card. If the disk fills up, the session is kept in memory and saved once there is room again. - A frozen screen is noticed. If the app stops responding for 2 s, what
it was doing is written to a file. After 30 s, the bell rings once and
the terminal title says
not responding. When it recovers, a card says how long it was frozen and where. When the model is silent, the indicator sayswaiting for <model> · 35s, thenno response for 60s · ctrl+c cancels. - ctrl+c always stops a turn, even when the model has gone silent. After about 1.5 s the turn is cut off, and the text so far is kept.
- When a provider fails and the request is retried, the indicator says so
(
retrying 2/3 after network error). Setharness.turn_stall_secondsto stop a model that has gone silent and retry once.
Remote
/remote connects the open TUI session to Telegram, so you can follow it,
approve single actions and talk to D.A.V.E. from your phone. Nothing polls or
leaves the machine until you configure a channel and run /remote on. The
bridge stops when the TUI closes, unless you hand the session to the
background with /background.
Setup:
- In Telegram, message @BotFather, send
/newbot, and copy the token. - Export it:
export DAVE_TELEGRAM_TOKEN=<token>(the config only names the variable,remote.telegram.bot_token_env). dave config set remote.channel telegram, then startdave.- In the TUI,
/remote pairshows a 6-digit code. Send/pair <code>to your bot in a private chat within 5 minutes. Your Telegram user ID is stored inremote.telegram.allowed_user_id. /remote testsends a test message.dave doctorchecks the token and the pairing.
In the chat:
- Plain text is a prompt, and
/command argsruns a slash command. During a turn the phone is toldbusy: the terminal's message queue is terminal only. /cancelstops the running turn./helplists the commands allowed remotely, grouped;/help alland/help <word>work too.- Permission cards arrive with Allow once / Deny / Deny + reason. Whichever of the terminal or the chat answers first wins.
By default remote answers last one call: Allow once and Deny. Set
remote.permission_ceiling to session, project or global and a card adds
More… (how long, which rule, Allow or Deny) up to that ceiling; a deny at any scope
is always allowed, a rule for the whole tool needs project or wider, and Allow
writes on a delegate card needs session or wider. remote.step_up: pin makes each
such allow wait for a four-digit PIN shown in your terminal (or by dave daemon pin).
Raising the ceiling lets whoever controls the paired account add rules that last,
including a bash rule, which is code execution on this machine; the default stays
once, dave doctor warns when it is not, and a rule added this way is marked
(remote) in /permissions, noted when you next open the session, and removable only
in the terminal. /quit, /resume, /export and a few other commands reply
"terminal only". Only the paired user in a private chat is heard; everything
else is dropped silently.
Telegram bot chats are not end-to-end encrypted. With remote.share: "summary" (the default), only these are sent:
- replies;
- the commands you are asked to approve;
- paths, diffstats and tool outcomes.
"full" also sends tool output and diffs as files. remote.notify picks the
notifications: turn_finished, permission, report_ready, error and
drift. remote.autostart: true starts the bridge with the TUI. Details are
in docs/spec/10-remote-channels.md.
Background sessions
/background hands the open session to a process of its own, so the agent
keeps working and keeps listening on remote after you close the
terminal. Come back later with dave attach.
/background hand over now (a turn in flight is stopped, as with ctrl+c,
and the background session carries on with a note about it)
/background wait hand over when the turn, its subagents and the queue are done
dave background list what is running, what finished, and what it last said
dave background logs -f follow one without interrupting it
dave attach [id] stop it and resume the session here (--wait lets it finish first)
dave background stop <id>
What goes with the session: the model, mode and permissions it had, the
messages you had queued, and the remote bridge if it was on. Nobody is at the
keyboard there, so an approval card goes to your phone when remote is paired
and waits background.ask_seconds (15 minutes) before it is denied; with
remote off it is denied at once and the model is told why. The session ends
when its work is done (remote off), or after background.idle_hours of just
listening, or when you stop it. With nothing to run and remote off,
/background says so instead of starting an idle process. While a session is
in the background, /resume and dave --resume refuse it and point to
dave attach. Linux, macOS and WSL. Details:
docs/spec/07-sessions-tui.md.
The daemon
A background session that crashes stays crashed, and nothing starts after a
reboot. dave daemon is one optional process that watches them:
dave daemon start run it as a process of its own (no terminal)
dave daemon status its sessions, restarts and what it did lately (--json)
dave daemon stop stop it; the sessions keep running (--hosts also stops them)
dave daemon restart stop and start; --hosts also renews each session onto this version
dave daemon logs -f follow its log
dave daemon retry <id> start a session it gave up on again
dave daemon run run in the foreground (what a service unit calls)
dave daemon install write a systemd user unit or launchd agent (--enable also turns it on)
dave daemon uninstall turn it off and remove the file install wrote
A session whose process dies is started again with a note saying what was lost,
after 2 s, 4 s, 8 s…; more than daemon.restart_max (3) restarts in
daemon.restart_window_minutes (10) and it stops trying (gave_up). When the
daemon starts it takes over every running background session and, with
daemon.autoresume: live, starts the ones that were live a reboot ago (updated
within background.keep_days). With a daemon running /background hands the
session to it; daemon.autostart starts the daemon for you. A daemon-run
session does not expire when idle unless daemon.idle_hours says so. Nothing
starts the daemon but you.
With a daemon running it owns the Telegram bot: one poller for every session, so
several background sessions can be reached at once. dave daemon pair pairs your chat
(or /remote pair in a terminal), and from the chat /sessions lists the sessions,
/switch <n> chooses who hears you (the others arrive prefixed [title], and their
approval cards stay answerable), /new <task-id|folder> [prompt] starts one,
/stop stops one and /daemon shows the daemon. /new is limited to Projects the
vault knows and the daemon.roots you list. Start the daemon before turning remote on in
a terminal (a terminal already polling the bot stops the daemon's channel; dave daemon channel restart tries again). Linux, macOS and WSL (spec 14).
Telegram updates are acknowledged after durable acceptance and deduplicated by update
id. A queued prompt survives a host restart; unfinished deliveries retain their original
session even if you switch sessions in the chat. remote.limits.delivery_attempts
(default 3) bounds unanswered attempts. Rejected or interrupted deliveries get an honest
chat report; a failed report leaves the update pending, and held input retries.
Telegram retains updates for at most 24 hours. If a resumed poll no longer returns an unfinished update,
the saved destination gets an uncertainty report naming the session.
To have the daemon come back after a reboot or a logout, install it as a user service:
dave daemon install --enable # systemd on Linux, launchd on macOS
loginctl enable-linger $USER # Linux: start at boot, not only at login
install writes the unit (or plist) and, without --enable, only prints the command that
turns it on. The file carries # managed by hey-dave; a file without that line is never
overwritten or removed, and dave daemon uninstall removes only one that has it. The service
runs the same Python that installed it, restarts on failure, and gets DAVE_VAULT, your
config path override, the XDG folders and PATH from the shell you ran install in. The bot
token is not written: the unit names its variable (remote.telegram.bot_token_env) and reads
~/.config/hey-dave/daemon.env (mode 0600) if you create it, or you can run systemctl --user import-environment DAVE_TELEGRAM_TOKEN (launchctl setenv on macOS). Sessions outlive the
daemon (stopping or restarting it leaves them running), and when the machine comes back the
daemon starts again every session that was live (daemon.autoresume). Under WSL without
systemd, or in a container, install says so; use dave daemon start there. dave doctor
reports whether the service is installed and enabled.
The API
Scripts, dashboards and other front ends can reach the daemon's sessions over HTTP. It is
off by default (daemon.api.enabled), listens on 127.0.0.1:7421 only (plain HTTP, no
TLS, nothing leaves the machine unless you tunnel it) and needs a bearer token. Tokens are
made in the terminal, never over the API: the secret is printed once and only its hash is
kept.
dave daemon token new dashboard --scope read,prompt,approve # prints the secret once
dave daemon token list # ids, scopes, ceilings, last use
dave daemon token revoke dashboard # works on its next request
A token carries scopes: read (list, snapshot, events, cards), prompt (messages, commands,
cancel), approve (answer a card), manage (start and stop sessions) and full (ask for
whole events, tool output and diffs, instead of the summary chat shows). Card answers are
bound by the token's --ceiling (once unless you say more) and by remote.permission_ceiling,
whichever is lower, so the API can do no more than the paired chat can. Every call that
changes anything is written into the session as an api_input event. Requests with an
Origin header, a Host other than 127.0.0.1:<port> or localhost:<port>, no token or a
revoked one are refused; bodies over daemon.api.max_body_kib (256) get 413, more than
daemon.api.requests_per_second (30) from one token 429, and at most daemon.api.max_streams
(8) event streams are open at once. Any process running as you can use it, as it can the
control sockets; treat a token like a key.
export TOKEN=dvt_... # from `dave daemon token new`; $SESSION is an id from the list below
curl -s http://127.0.0.1:7421/v1/health
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:7421/v1/daemon
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:7421/v1/sessions
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:7421/v1/sessions/$SESSION
curl -s -H "Authorization: Bearer $TOKEN" -d '{"text": "run the tests"}' http://127.0.0.1:7421/v1/sessions/$SESSION/messages
curl -s -H "Authorization: Bearer $TOKEN" -d '{"name": "status"}' http://127.0.0.1:7421/v1/sessions/$SESSION/commands
curl -s -H "Authorization: Bearer $TOKEN" -X POST http://127.0.0.1:7421/v1/sessions/$SESSION/cancel
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:7421/v1/sessions/$SESSION/cards
curl -s -H "Authorization: Bearer $TOKEN" -d '{"action": "allow", "scope": "once"}' http://127.0.0.1:7421/v1/sessions/$SESSION/cards/$NONCE
curl -N -H "Authorization: Bearer $TOKEN" "http://127.0.0.1:7421/v1/sessions/$SESSION/events?after=0"
curl -s -H "Authorization: Bearer $TOKEN" -d '{"folder": "~/code/hey-dave", "prompt": "fix the build"}' http://127.0.0.1:7421/v1/sessions
curl -s -H "Authorization: Bearer $TOKEN" -X DELETE http://127.0.0.1:7421/v1/sessions/$SESSION
Events are server-sent events: id: is the sequence number, so a client that reconnects
with Last-Event-ID (or ?after=N) is sent exactly what it missed, or one resync event
with a snapshot when the session's ring (daemon.api.replay_events, 500) no longer reaches
back. Errors are {"error": {"code", "message"}}. The routes and what each needs are in
spec 14.
Configuration
One JSON file: ~/.config/hey-dave/config.json (project overrides in
.hey-dave/config.json; ${ENV_VAR} references for secrets — never
literal keys). Manage it with dave config get|set|validate. Details:
docs/spec/01-config.md.
{
"providers": { "codex": { "type": "codex" } },
"profiles": { "main": { "provider": "codex", "model": "gpt-5-codex" } },
"harness": { "default_profile": "main" },
"roles": { "scout": "main" }, // roster role → profile routing
"permissions": { "allow": ["bash(git status*)"] },
"mcpServers": { "redmine": { "command": "…" } },
"tracker": { "backend": "local" }
}
Provider kinds: codex (Codex CLI auth), openai_compat, ollama,
scripted (tests). Every kind lists its models from the server: codex
asks the ChatGPT backend for your account's models, as the Codex CLI does.
Limits and timeouts
The sizes, counts and waits the harness used to fix are settings, each next to the feature it tunes, with the old value as the default:
harness.tools: the longestbashtimeout, thereadsize cap,globand search caps, the task list's length, a hook's timeout;harness.shell(!and!!),harness.mentions(@),harness.context(compaction,AGENTS.md),harness.housekeeping(backups, crash reports,dave doctor's disk and crash checks);tui.limits: the queue, the activity log, the busy line's "waiting", the notification gap, the sidebar refresh,/resume's preview;remote.limits: messages a minute, the pairing window and attempts;- per provider
max_attempts(and Ollama'scapability_ttl_hours, Codex'srefresh_early_seconds),plugins.web_fetch.max_redirects.
Each has a hard range, so no value switches a guard off, and raising a
remote rate or pairing limit through /dave is flagged as widening
access. /dave reads them all (harness_guide limits lists every one).
Set up from the chat: /dave
/dave <request> asks D.A.V.E. to work on the harness itself, without
leaving the TUI. For example:
/dave help me add my Ollama box as a provider;/dave route the critic role to the local model;/dave why is web search failing?
It enters harness mode (mode: harness in the header), and your replies
continue it until /dave off.
- What it can do. In this mode D.A.V.E. can only read the config (with secrets hidden), read built-in setup guides, run read-only checks, and propose changes. It has no file, shell or web tools.
- What it can see. Every section of the config and what each holds,
whether set or not, with each key's type; every key id you can remap;
each helper role as packaged; every command you can turn off. It can
also read D.A.V.E.'s own settings in the vault (your name, hours,
review day, which helpers are on…) and which of D.A.V.E.'s texts are
your versions, but it can't change those here: it tells you how
(
/dave offand ask,/init vibe, ordave prompts copy). - The card. Every change comes as a card: tick the items you want and
press Enter;
fsends feedback and Esc rejects.- Anything that widens access starts unticked and needs you to type
allow: an allow rule, a removed deny rule, turningconfineoff. - New MCP servers and skill folders (which run commands) and new provider hosts are flagged with a ⚠.
- Anything that widens access starts unticked and needs you to type
- API keys are never written into the config. D.A.V.E. uses an
api_key_envname, and the card lets you paste the key for this session only; export it in your shell profile to keep it. - After you apply, the files are backed up to
~/.local/state/hey-dave/config-backups/, and the change reloads at once. Plugins, MCP servers and skills load at the next start. Checks then run (the new provider's model list, for instance), and D.A.V.E. fixes what failed. /dave undoputs the files back. See docs/spec/02-providers.md.
Images go to every provider. Ollama is asked whether the model has vision;
for the others, set "images": false on a profile whose model can't take
them. The model then gets a short note instead of the image. Sessions keep
the image's path and hash, not its bytes, so an image moved or edited later
is sent as a note, not a different picture.
External agents (Claude, Devin)
D.A.V.E. can hand a charge to an external coding agent over
ACP — Claude Code through the
claude-agent-acp adapter, or Devin through devin acp — instead of a
harness subagent. They are workers, not model connections: they never
answer D.A.V.E.'s own turns, and they run with your own sign-in. There
is no credential field; the harness never logs in for them, and the agent
process gets your environment unchanged (a key the harness resolved for a
profile is not forwarded — if your shell exports ANTHROPIC_API_KEY,
Claude's worker bills that key, not your plan; the card and dave doctor
say which).
Setup:
- Claude Code:
claudeinstalled and signed in, then the adapter —dave plugins install @agentclientprotocol/claude-agent-acp --latest-stable(into the harness's npm prefix; needs Node ≥ 22). - Devin: the
devinCLI installed and signed in (Pro, Max or Teams);devin acpis Cognition's own ACP entry point.agents.providers.devin.cloud: truerunsdevin acp --cloud. - Check:
dave doctorgives each enabled provider anagent:<id>line — the binary (PATH, then the npm prefix), version, Node floor, aninitializehandshake and the sign-in method. It never opens a session, signs in, or installs anything. Bare/agentin the TUI lists the same, plus the external workers running.
Use:
/agent claude fix the login redirectdispatches a charge (theimplementerrole, or--role critic). The dispatch card always comes first — provider, role, model, local or cloud, the billing method, and a warning when the provider can act outside the harness — because it spends your agent's own quota; no allow rule skips it. One charge per provider at a time (agents.providers.<id>.max_concurrent); more queue.- D.A.V.E. can dispatch too:
delegate(agent="claude")for one charge, oragents.routesto route a role ("agents": {"routes": {"implementer": "claude"}}).agent="local"forces the harness worker.quartermasterandscribealways stay local — their work is the vault's own tools. - Reports come back like any subagent's and list the files changed.
/agent stop [id]cancels a running worker;delegate(resume="<id>")sends a follow-up charge (a live worker is reused; after a restart the stored ACP session is reloaded — nothing respawns on its own). - Headless:
dave run "/agent claude <charge>".--approve agentpre-approves only the dispatch card — the agent's own file and terminal asks still deny, so unattended runs stay read-only unless you also pass--approve allow.
What the harness enforces for an external charge:
- Its file writes, reads and terminals go through your permission rules
and cards. "Allow always" stays a harness grant — the agent keeps
asking. ACP-mediated writes are checkpointed, so
/rewindundoes them.git push, the vault,.hey-dave/and the agents' credential stores (~/.claude/.credentials.json,~/.config/devin/) are hard-denied, reads included. - Only safe modes are ever selected (
defaultfor Claude,askfor Devin;planfor read-only roles) — bypass modes are refused, and an agent-initiated switch to one is put back. - Claude is a bypass provider: its SDK edits files and runs commands
itself, so only its permission requests reach the harness — and allow
rules in your own
~/.claude/settings.jsoncan approve its actions without a card. The dispatch card warns, and the report lists what changed outside the harness's sight (a git diff), marked as not covered by/rewind.planmode is the stricter lever.
Policy links (checked 2026-09-26 — they change, so dave doctor prints
the date too):
- Claude Code: legal and compliance, Agent SDK overview, use the Agent SDK with your Claude plan.
- Devin: ACP docs, Platform Terms of Service, Acceptable Use Policy.
Other ACP agents can be added by config alone
(agents.providers.<id>.command). Details: spec 03 External agents.
Extending
- Skills — markdown
SKILL.mdunderskills.roots(default~/.config/hey-dave/skills,~/.agents/skills,./.hey-dave/skills); slash commands and hooks too.dave skills list. Command files can declareusage,helpandexamplesfrontmatter so--helpand argument checks work for them. docs/spec/04. - Bundled skill: archify — ask D.A.V.E. for an architecture, workflow,
sequence, dataflow or state diagram and it writes a validated, interactive
HTML page (pan, zoom, search, light and dark, exports). It ships with the
harness and needs Node.js 18+ on
PATH; without it the skill is hidden anddave doctorsays so. Your ownarchifyin a skills root replaces it;skills.disabled: ["archify"]turns it off. MIT, from tt-a1i/archify, pinned to the harness release with no update check. - Plugins — Python entry points (
hey_dave.plugins) or built-ins;dave plugins list. docs/spec/05-plugins.md. - MCP — paste a Claude-Desktop
mcpServersblock unchanged; tools appear asmcp__<server>__<tool>. docs/spec/05. - Trackers —
local(file-backed) orredmine_mcp(Redmine over MCP); outward writes are always proposed and approved individually (/trackerpanel).dave tracker list. docs/spec/05. - Web search —
searxngorbravebackends;dave search "query". - Web pages —
web_fetchreads a page as markdown: the main content, with headings, code and links, minus menus, footers and scripts.- Each new host asks first (
GET <url>on the card). Allow a host for good withnetwork(web_fetch:docs.python.org), or every host withnetwork(web_fetch:*). - Internal addresses (localhost,
10.x,192.168.x, cloud metadata) are refused, even after a redirect. Setplugins.web_fetch.allow_private: truefor intranet docs. - Page text is marked untrusted, and D.A.V.E. is told never to follow instructions in it.
- Only HTML, text, markdown, CSV and JSON are read; PDFs and images are
refused. Limits are under
plugins.web_fetch(20 s, 2 MB, 20,000 characters). It works in plan mode. Turn it off withplugins.disabled: ["web_fetch"].
- Each new host asks first (
Using your Claude Code plugins
hey-dave can read Claude Code plugin directories — nothing runs until you enable one, and foreign code never runs inside the harness's own process.
dave plugins listshows what was detected:plugins.sourcesentries always, plus~/.claude/plugins/marketplace installs and this project's own.claude-plugin/(setplugins.detect: falseto scan only named entries). Each source starts asavailable.dave plugins enable claude:<name>enables it (disabletakes it back), or add{"format": "claude", "path": "…", "enabled": true}toplugins.sourcesyourself./pluginsshows the same list in the TUI.- What then works: the plugin's skills, slash commands (
/<plugin>:<name>), hooks (SessionStart,PreToolUse,PostToolUse,Stop) and MCP servers (mcp__<plugin>-<server>__<tool>). Anything the format has that the harness cannot run — unknown hook events, LSP servers, output styles, themes — is listed asnot run/unsupported, never an error. - Hooks can only tighten:
denyrefuses the call,askforces the approval card, andallowis ignored — the permission gate decides. - Agents become
delegateroles named<plugin>:<name>that start read-only — no shell, no writes — until you bound them withdave.roster.<plugin>:<name>. dave plugins install <pkg>@<ver>(or--latest-stable, which takes the newest release at least 7 days old) installs an MCP server's npm package into the harness's own prefix, with install scripts off by default — nothing is ever installed automatically.
Using your Pi extensions
Pi extensions are TypeScript — hey-dave hosts them in
a small vendored Node shim, one process per extension, so nothing foreign
runs inside the harness itself. Needs Node 22+ on PATH (or installed into
the npm prefix).
dave plugins listfinds~/.pi/agent/extensions/, this project's.pi/extensions/,~/.pi/agent/skills/,.pi/skills/, andmcpServersin~/.pi/agent/settings.json. Without Node 22+ an extension showsunavailable: needs node ≥22.dave plugins enable pi:<name>loads the extension once to check it — that's the moment its code first runs — and refuses extensions that register no tool.- What then works: the extension's tools, arriving as
mcp__pi_<ext>__<tool>under the normal MCP permission kind (plan mode blocks them); skills roots andsettings.jsonMCP servers import aspi:skills/pi:project-skills/pi:mcp. - What is listed but never run: everything else the extension registered —
events (
on:<event>, includingtool_call), commands, shortcuts, flags, providers, renderers, messages, session entries andctx.ui. The shim records them asunsupportedrather than emulating them. - A missing dependency shows
cannot find module '<x>'; when the extension ships apackage.json,dave plugins install --from pi:<name>runsnpm installin its directory (scripts off by default).
D.A.V.E. state
The vault lives at $DAVE_VAULT, else dave.vault_path, else
~/.local/share/hey-dave/vault/: readable JSON/Markdown records for Tasks,
Projects, Goals, Promises, memory and portable conversations, changed only
through audited transactions by hey_dave.dave.state. Inspect it without
starting a session:
dave task list dave brief dave review dave goal list
dave promise list dave memory audit dave time dave vault check
Tasks are classified Day (scheduled for a date), Coming Due or Long
Term, each in an order you set (/task reorder, dave queue); D.A.V.E.
suggests but never reorders, reclassifies or reschedules on its own. Goals
count completed linked work once; Promises record who, what and when, and
completing a Task only suggests marking one Kept. Natural-pause notices
(/notice, /check) compare what you are doing with your queues.
D.A.V.E.'s own settings live in the vault's config.json and are set with
dave config set dave.vault.<key> <value> (or /init vibe, or by asking
D.A.V.E.). Each one takes effect:
user.timezone(an IANA name such asEurope/Berlin) decides what "today" is for Day scheduling, overdue Tasks, reviews and Promise dates; empty uses the machine's zone.user.name,user.role,user.address_as,user.work_hours(09:00-17:00) andkanban.boards(your intake board names) are in D.A.V.E.'s prompt;personality.wit/pushbackset its voice.time.idle_timeout_minutes(5) ends a timed interval at your last activity;memory.portable_conversationsdecides whether new transcripts sync, andtranscript.segment_kib(256) /transcript.segment_records(500) decide when a transcript's open segment is sealed and a new one starts.memory.digest(auto/off),memory.digest_model,memory.digest_input_tokens(8000),memory.digest_output_tokens(1000) andmemory.digest_timeout_seconds(30) control the memory digest;context.recap_tokens(2000) bounds a Task recap.projects.source_max_paths/source_max_bytesbound Project source snapshots.
Make D.A.V.E. your own
Its words. Every prompt D.A.V.E. runs on (persona.md and the six
references), the ten role contracts and its slash commands can be replaced
or added to from the vault, so your versions sync with it:
dave prompts list # every file, and whether yours replaces or adds to it
dave prompts copy persona # puts persona.md in <vault>/harness/prompts/ to edit
dave prompts copy roles/critic --append # starts roles/critic.append.md: added after the packaged text
dave prompts show roles/critic # the text in use
<name>.md replaces the packaged file; <name>.append.md is added after it,
so upgrades to the packaged text still reach you. A new file in
harness/commands/ adds a command. D.A.V.E. can't edit these files: the
vault is off limits to its write tools.
Its helpers' limits. Each role's tools, shell commands, write paths and
dave_* actions can be replaced in the config:
"dave": { "roster": {
"critic": { "bash_allow": ["git diff*", "uv run pytest*"] },
"scout": { "tools": ["read", "glob", "grep"] }
} }
A role never gets delegate, makes commitments (Promises) or changes the
config, whatever this says. When D.A.V.E. proposes one of these changes,
it shows as widens access, unticked.
Its commands. "commands": {"disabled": ["standup", "music"]} turns
slash commands off: they disappear from the list and /help, and typing
one says it is off. /help, /quit, /keys, /dave, /errors and
/init always stay. "common": ["task", "goal"] replaces the short list
bare /help (and completion's first rows) shows; it never changes what
runs.
Sync across devices (Google Drive or a synced folder)
One D.A.V.E. on every machine: the vault stays a local folder that works
offline, and the harness shares it as complete, checksummed transactions,
either through a folder in your Google Drive or through any folder your own
tool already syncs. Edits to different fields merge; the same field changed
on two devices keeps your local version and both originals for review
(/vault conflict, dave vault resolve). A repeated or interrupted sync
never duplicates Tasks or time, and timers, checkout paths and sign-ins stay
on each device. A new device joins from an empty folder.
Google Drive. On each device, /vault login (or dave vault login):
the harness ships its own Google client, so there is nothing to register. It
turns sync on and opens the browser; then /vault sync (it also syncs on its
own from then on). The harness asks only for drive.file: it sees the files
it created, nothing else in your Drive. Tokens stay in the state directory
(0600), never in the config or the vault. /vault and the setup screen
(/vault config) say when a sign-in expired, or when Google says it will;
renewing is another /vault login.
Your own Google client (a fork, a policy that blocks the shipped client,
or your own quota): in Google Cloud
enable the Google Drive API, set up the OAuth consent screen and
publish it (while it says Testing, Google signs you out every 7 days),
create an OAuth client ID of type Desktop app and Download JSON.
Then /vault login ~/Downloads/client_secret_….json (or dave vault login --client-file …, or /vault config, whose screen has these steps, ctrl+o to
open the console, and ctrl+l to sign in). The client stays on the device
(0600, never the config); /vault logout --forget-client deletes it. Use the
same client on every device.
A synced folder, no sign-in. Point the harness at a directory that Google Drive for desktop, Syncthing, Dropbox or a share keeps in step:
dave config set dave.sync.backend folder
dave config set dave.sync.path "~/Google Drive/dave-vault"
dave vault sync
or fill the folder field in /vault config. Writes are atomic, so the tool
never uploads half a file; the path must not be the vault itself.
In the TUI it syncs at start, shortly after D.A.V.E. writes, every 5 minutes
and at exit (dave.sync.auto, interval_minutes, push_delay_seconds).
/vault shows where it stands, and dave vault sync --dry-run shows what
would move. Two machines with the same hostname need DAVE_DEVICE set on one
of them. Deletions don't sync: remove a file on every device. See
docs/spec/06-dave-state.md Sync.
Docker
docker compose -f docker/compose.yaml run --rm dave # TUI
docker compose -f docker/compose.yaml --profile search up -d # SearXNG
docker compose -f docker/compose.yaml --profile ollama up -d # Ollama
Volumes: ~/.config/hey-dave → /config (create it first — Docker makes
missing bind sources root-owned), named dave-data → /data (the vault lives
here), dave-state → /state, the directory you run compose from (or
$PROJECT_DIR) → /work, and ~/.codex read-write (Codex token refresh
writes back to the mounted file).
SearXNG needs a secret in the environment and refuses to start without one:
export SEARXNG_SECRET=$(python3 -c "import secrets; print(secrets.token_hex(32))")
docker compose -f docker/compose.yaml --profile search up -d
dave config set plugins.web_search.searxng.base_url http://searxng:8080 # inside compose
From the dave container SearXNG is http://searxng:8080 — localhost
there is the harness container itself.
A host Ollama is reachable as http://host.docker.internal:11434; dave discover inside Docker only scans the compose network. Non-interactive
provisioning: dave init --non-interactive --from config.json.
See docs/spec/08-packaging-deploy.md.
Development
bash scripts/validate.sh # frozen sync, quality gate, clean installed-wheel smoke
Releases publish themselves: bump the version in pyproject.toml and
src/hey_dave/__init__.py, commit, then push a tag such as v0.1.0a2.
GitHub Actions runs the full gate, checks the tag matches the version, and
publishes to PyPI through trusted publishing. See
spec 08
for the one-time PyPI and GitHub setup.
bash scripts/bundle-docs.sh copies docs/ (without plan/, reviews/ and
ideas/) into the package for /docs; scripts/check-wheel.sh and the
publish workflow run it before building, and the copy is git-ignored.
Tests use temporary personal-state paths and block external sockets by default. MCP and Spotify callback integrations are explicitly marked for loopback TCP. See the dependency policy for update boundaries and CI validation for the shared gate.
Normative specs and the staged plan live under docs/ — see
docs/README.md.
Interactive diagrams of the design (the system map, a turn, the permission
gate, delegation, persistence and the stage roadmap) are in
docs/diagrams/; bash scripts/diagrams.sh
re-renders them from their JSON sources.
To try features by hand, user-test-docs/setup.sh builds a throwaway demo
project in ~/dave-demo (a small calculator with a planted bug, test
images, and files that exercise @ limits).
user-test-docs/CHECKLIST.md lists the manual
checks, each with what you should see.
Resuming a session from another project asks before loading that project's
settings, skills and plugins. Headless resume requires starting in the saved
project. Changes to dave.vault_path take effect after restarting D.A.V.E.
--continue resumes this project's most recently active saved session.
Session listing reflects renamed titles and profile/model changes. An interrupted
final session write can be recovered; its damaged bytes are preserved in a
private .corrupt sidecar before the next write. Corruption in the middle
produces a file-and-line error while other sessions remain discoverable.
Streaming replies use batched Markdown rendering. Recursive searches skip
what your .gitignore ignores (or, without ripgrep and git, folders like
node_modules and .venv). They are cancellable and bounded: at most
10,000 files are searched, output stops at 1 MiB, and a content search has
60 seconds. A search that reaches a limit still returns what it found, with
a note to narrow the path or pattern. Deny rules hold for every file a
search opens. Allowing a search once covers the files it finds; files an
ask rule covers share one extra prompt. The session picker searches the newest
50 sessions per scope and reuses unchanged summaries between openings.
License
hey-dave is free for noncommercial use under the PolyForm Noncommercial License 1.0.0: personal projects, study, research, hobby use, and use by charities, schools, public research and government bodies. Using it for a commercial purpose, including work for a company, needs a separate license from the author. The bundled Archify skill and the Pi shim's inlined dependencies keep their own licenses (MIT, ISC, BSD-3-Clause, OFL-1.1); their texts ship with the package.
Schema-2 Task sessions use one timer owner per device. /time shows the total,
direct and child time, unresolved device overlaps, and provisional active time.
/time pause lasts until /time resume; five minutes without meaningful activity
pauses at the last activity and excludes the idle gap. Model/tool execution keeps
counting, while permission waits can idle. Crashes close at durable evidence
(heartbeats at most ten seconds apart). /time adjust <interval-id> records a
reasoned correction on the same interval; exported time creates a compensation
proposal. /time resolve <task-id> <slice-id> <node-id> reviews ambiguous
allocation before export. These controls require a fresh schema-2 vault.
Portable Task memory and conversations
Schema-2 Task/child memory captures observed requests and labels model-reported
progress as unverified, kept as worklog records (/memory shows only the five
sections and the five newest entries, and a Task recap is cut to
context.recap_tokens, 2,000 by default). At a switch, a timer pause, the end of a
session and before a compaction D.A.V.E. also makes one visible call (updating memory…) that updates Where stopped, Next action, Decisions and Blockers
from the work since the last one: every entry cites messages, tool results or
worklog entries that must exist, is labelled observed or reported, and never
rewrites a line you wrote or edited (a disagreement is added beside it as
suggested). A call that fails or hangs never holds up the switch, pause or exit;
it is retried at the next pause within the same complete request budget and model
context cap. Oversized fixed input is pending: too large and waits for memory,
checklist/recap or settings to change. Only a successful cited tool result is
observed; failed or unfinished calls remain reported. Each entry's stable sources
and tool outcomes are saved on its revision and shown in /memory audit and
/memory show, including an explicit reason when a source is unavailable. Turn it off with memory.digest = off, pick the
model with memory.digest_model (provider/model), and skip it for one headless
run with dave run --no-digest. Captures carry stable entry IDs and source evidence;
failed saves retain the transcript and last good memory, report pending status,
and retry without duplicate entries. /memory [subject-id] opens literal
Markdown; /memory edit <subject-id>, /memory audit [subject-id], and
/memory show <revision-id> expose authored text and exact before/after changes.
/memory revert <revision-id> previews a memory-only correction and asks before
saving. (/context memory … is the same command, for example
/context memory audit user; /memory still works but is no longer listed.) Unrelated later entries survive; overlapping changes require review.
CLI equivalents are dave memory view/edit/audit/show/revert --help; edit accepts
--file, while revert previews until explicitly repeated with --yes.
If you edit a memory file (memory.md) in an editor, the next time D.A.V.E. opens
it keeps your edit as a revision you can see in /memory audit and revert. A
structured file (task.json, project.json, …) edited by hand is held back
instead, on its own: everything else carries on, the vault serves the last saved
version, and dave vault status names the file with the two ways out, dave vault adopt <path> (keep your version, after checking it is valid) and dave vault restore <path> (put the saved one back). Editing those files by hand is
still not a supported way to work.
The vault never deletes history, but it keeps the working set small. Past
history.checkpoint_transactions (2000) loose transactions or
history.checkpoint_mib (64) MiB of them, and only while you are idle, the
transactions are copied byte for byte into a compressed pack under
history/packs/, read back and compared, and a checkpoint records what every
file hashed to. Opening the vault then replays only what came after.
dave vault checkpoint does it now, dave vault status shows loose
transactions, packs and the checkpoint in use, and dave vault check reads every
pack back. Sync uploads the packs and checkpoints once; a copy that lost
history/packs/ fetches them back on its next sync, and without them it still
opens but cannot show or restore the packed history.
Portable conversations default on (memory.portable_conversations in vault
config). The choice is fixed for each new conversation; switching it off keeps
existing archives and always retains Task memory. Copies of actual allowed image
inputs use relative content hashes. Missing, changed, denied, and oversized
attachments are labeled. Copied vaults restore text, tool results, images and
compaction summaries without executing old tools or copying permission grants.
Transcripts are stored as append-only segments, so a long conversation adds only
what you said to the vault's history and to sync, not the whole transcript each
time; a vault that holds segments names them in vault.json, and an older build
refuses it rather than misreading it. If two devices continue the same
conversation offline, both tails are kept and opening it says so.
dave sessions import <session-id> --task <task-id> explicitly imports a local
conversation; import counts no historical active time.
Register Git Projects with dave project add, including worktrees. Use dave project attach <project-id> <directory> for an explicitly moved checkout,
dave project sources <project-id> to inspect provenance, dave project refresh <project-id> to refresh, and dave project source-register <project-id> <path>
for additional documentation. README/AGENTS snapshots remain versioned; authored
Project memory stays separate. Source scans default to 5,000 eligible paths and
2 MiB inspected content (projects.source_max_paths / source_max_bytes),
respect exclusions/read rules, and label missing or truncated sources.
Effective context and scoped references
Schema-2 requests and previews share a source catalog: exact system text, actual tool schemas, hashes, controlling policy scope, unavailable sources and budget truncation. Global → selected Task/child → session overrides apply independently to source inclusion and prose. Memory and documents default to summary plus reference with a 2,000-token summary budget; explicit full selections that cannot fit produce actionable guidance. Excluded tools cannot dispatch, and child roles retain their own limits.
dave_ref retrieves included subject memory, linked Project sources or packaged
guidance by scoped reference ID. It returns bounded content with provenance and
freshness; denied cached documents stay denied. Activation reloads actual allowed
bodies after resume or compaction. Editing injected text is separate from editing
authored memory. Setup and interactive source review are the next redesign stage.
Review and edit context
Both dave init and dave init --vibe offer a source checklist before saving.
Vibe first interprets your answers; Back lets you revise the proposed settings
and refresh the preview. Portable conversations are on by default and can be
turned off while keeping portable memory. Cancel leaves installed settings alone.
With a schema-2 vault, /context opens the same checklist during work.
(/status errors shows the session's faults, like /errors.) Space
toggles a source; Include chooses its mode, Details shows all text and provenance,
and Edit text changes added prose. Apply reviews the diff. Scope defaults to
session; choose Task or global to keep broader defaults. Memory saves the
authored source separately. Permissions remain enforced independently.
dave context show global --text
dave context set global prompt.dave off
dave context edit global prompt.dave --file ./instructions.md
dave context reset global prompt.dave
Use --task T… for Task policy and --session <id> for an existing session.
A new conversation starts without old chat text; disabling a source does not
erase earlier messages.
Linked outcomes and reviewed work
Schema-2 vaults keep Goals and Promises separate from Tasks. /goal and
/promise list records or open reviewed attribute/link forms. Goal progress
counts linked work once when both a Task and its child are linked. A completed
Task leaves its Goal and Promise statuses unchanged. Promise due-date changes
require a reason; model-proposed outcome writes always show their exact review.
dave goal new "Launch app" --task T-<uuid>
dave goal show G-<uuid>
dave promise new Alex 2026-10-10 "Send release notes" --task T-<uuid>
dave queue show day --on 2026-10-01
dave review --days 7 --json
dave standup 1
Replace the placeholder IDs with actual record IDs. /task reorder reviews a
complete classification order. Date views do not reschedule or reclassify work.
The sidebar shows Today, Coming Due, Long Term, Goals, Promises and General
history alongside worker reports and the selected Task's time/checklist.
Work notices appear at a pause above the composer. Choose Continue, Switch,
Snooze or Dismiss with the buttons or /notice. /notice snooze 45 edits the
default thirty-minute delay. Dismiss applies to that category in the current
conversation, including resume on this device. Notices stay hidden while a turn
streams; due flags remain visible in queues.
Saving an approved plan to a selected Task reviews its description and steps
and preserves existing child IDs and statuses. /supervise <task-id> uses the
reviewed checklist and Task-scoped report verdicts. Background workers retain
their assigned Task and have no separate human timer. Explicitly waiting for
delegates counts on the selected session's clock; permission waits allow idle
pause, and manual pause remains in force.
For tracker time, pause the Task timer, then propose with task_id and an
explicit tracker ref; omit hours to derive durable unexported counted time.
Every outward apply still requires approval. Denied or expired drafts release
their reservation. An uncertain response keeps time reserved for reconciliation
so a retry cannot log the same interval again.
Task controls without the TUI
dave task new accepts --class, --on, --due, repeatable --project,
and --parent for a one-level child. Omitted child choices copy the parent's
defaults; later parent edits leave child data intact. Each command has --help.
dave task new "Add push notifications" --class coming_due --due 2026-11-01
dave task new "Test delivery" --parent T-<uuid>
dave task review T-<uuid> --yes
dave task status T-<uuid> completed --yes
dave task move T-<child-uuid> T-<parent-uuid> --yes
dave time show T-<uuid>
dave time exports
Use actual IDs from dave task list. Parent completion requires review and
finished children. Completed work suggests reviewing its linked open Promises;
marking one Kept remains a separate decision. dave task plan <id> --file plan.json
previews JSON with description and items (text, status, optional existing
child id and blocked_reason); --yes saves prose and checklist together.
archive retains data and warns about active children; restore retains status.
move and promote retain node identity, memory, sessions and time history.
/focus selects work through standard resume choices, /park opens
sidequest review, /brief reads current facts, and /check inspects the
work notice. Mission, item and priorities commands give replacement guidance.
/standup uses Task review facts and deliberate follow-ups.
If a tracker wrote time but its response was uncertain, verify the entry ID in
the tracker, then use dave time reconcile <export-id> <entry-id> to preview and
repeat with --yes to save it. /time reconcile offers the same review in the
TUI. Reconciliation records evidence without sending another tracker write.
dave time adjust <interval-id> <minutes> <reason> --yes saves an unexported
correction; already-exported time retains a compensating proposal visible in
time exports. tracker(action="ledger") also reads these records. Draft each
replacement with tracker(action="propose_correction", correction_id="TC-…", export_id="E-…"); the ordinary proposal panel shows the exact entry and old/new
hours for approval. Local time changes only after every affected entry has a
confirmed replacement. Denial/expiry releases an unstarted draft; uncertain
writes stay reserved across restart.
For an uncertain replacement, verify its amount in the tracker and use
dave time reconcile TC-<uuid>/E-<uuid> <entry-id> (preview, then --yes), or
/time reconcile in the TUI. dave time cancel TC-<uuid> --yes or /time cancel
can cancel an intent before any replacement begins. Added time beyond the
original exported ranges remains unexported for a separate reviewed proposal.
Local tracker replacements append an audit event referencing the original entry.
Redmine requires an explicit tracker.redmine_mcp.tools.time_replace mapping;
it receives time_entry_id and hours, and a structured entry identity confirms
success. Backends without replacement support leave the intent available for
review.
Board intake in Task mode
/intake sprint-board opens a source editor. Capture preserves the original
text without creating work. /intake propose <id> lets you add/edit/remove
proposed Tasks through the standard forms, including classification, dates,
Projects and references. Save keeps the proposal; /intake apply <id> reviews
it before creating the Tasks together. New Tasks append to your manual queues.
An existing Task association leaves its fields intact; duplicate references
require an explicit match.
For headless intake, capture with dave intake sprint-board < board.txt, inspect
with dave intake list or show <id>, then save a JSON item array with
dave intake propose <id> --file items.json. For example:
[{"title": "Add push notifications", "classification": "coming_due", "due_on": "2026-11-01"}]
dave intake apply <id> previews; repeat with --yes after review. Use actual
capture IDs from intake list. Capture and accepted associations stay in the
vault with their original input and audit history.
Task-mode Project tools now support assigned Project knowledge for delegated
workers. dave project show accepts an ID or slug; link/unlink associate a
Project with an existing Task ID or unique tracker ref. of returns all linked
Projects, and resolve respects nested repositories. status active|archived
controls visibility while Task status tracks work. Project links never choose
cwd or expand permissions. Model registration and source refresh respect the
current read rules; every model mutation requires review.
Headless supervision and remote Task controls
dave task sessions <id> prints the standard recap and valid new/resume
arguments. Run dave run --task <id> --supervise "Continue the reviewed plan"
to supervise an eligible root with an accepted initial checklist. Supervision
only grants report verdict bookkeeping for that root; parent completion,
commitments and outward writes keep their own approvals. dave run --resume <session-id> "/supervise off" leaves that mode. Use dave task assignments [task-id] to inspect charges/reports and dave task verdict <assignment-id> trust|partial|rerun|discard --summary "Evidence" to record your judgment.
Host slash controls give headless CLI guidance and are never sent as model work.
From a paired remote chat, /task list, /task show <id>, /task sessions <id>
and /return inspect work. /task start <id> displays the recap and both
conversation choices. Explicit new, memory, or resume [session-id]
returns display an exact review with /task confirm <token>. Tokens expire
in two minutes, apply once, and refuse stale work or a changed conversation.
Same-workspace returns keep the bridge connected and preserve existing session
denials. Cross-workspace returns, restored broader grants, supervision setup
and attribute/checklist/grant modals require the terminal. /supervise off
remains remote. /time show [id] and /time exports inspect time; pause/resume
can control only the open conversation's timer. Goal/Promise list/show work remotely.
Remote board intake uses /intake capture-text <source> <text> (a one-word
source name), /intake propose-json <id> <items-json>, /intake show <id>, and
/intake apply <id>. Acceptance displays original input, standard Task fields
and queue effects; /intake confirm <token> accepts that exact review.
Capture/propose create no Tasks. Task state cards include their exact change
under summary sharing; tracker and delegate cards retain Allow once and
restricted worker choices. No remote approval adds a lasting grant.
Task-mode dave dossier set/get [project-id-or-slug] edits/reads audited Project
memory; an omitted identity resolves the current checkout. dave project touch
refreshes bounded source facts, preserving authored memory. dave scan reports
local Git/Task associations without fetching (--all includes archived Projects).
dave project decline <path> suppresses repository offers on this device only.
Project add supports active/archive; legacy slug/cadence/goal choices are refused
with Task/Goal guidance rather than silently ignored.
The Stage 73 review guide provides a fresh-vault walkthrough. Task-vault sync, fresh schema-2 defaults, scenario coverage and package validation are implemented.
Remote reviews freeze all nonvolatile graph evidence. Ordinary elapsed/heartbeat updates on an open interval do not invalidate them; interval closure, allocation, correction, Task/memory/proposal edits and other graph changes still do. Acceptance checks that evidence under the writer lock and uses the current CAS generation, so clock progress does not weaken the atomic board acceptance guard.
Task-vault sync and conflict review
Vaults use immutable transaction bundles with optional Google Drive
sync. Existing OAuth setup and dave.sync settings are retained. dave vault sync
uploads content objects and history before publishing a checksummed commit;
receivers verify complete causal bundles and apply through the shared writer.
Interrupted transfers retry, and durable receipts prevent duplicate import.
Credentials, checkout mappings, caches and timing ownership stay on the device.
Local-only use still needs no sign-in or sync call.
Use dave vault sync --dry-run to preview without changing authority. An empty
local path can join an existing schema-2 Drive vault; choose it with DAVE_VAULT
and run sync before initializing another vault there. Independently initialized
vault identities are refused rather than combined. Full-vault copies retain
history and import receipts; checkout/source mappings must be set for the device.
Disjoint structured fields and nonoverlapping Markdown edits merge after graph validation. Competing fields, prose, tree changes and unsupported deletions leave local records intact and preserve both versions for review. Promotion relocates owned data; an old child path cannot silently return.
dave vault conflicts
dave vault conflict TX-<uuid>
dave vault resolve TX-<uuid> --take incoming
dave vault resolve TX-<uuid> --take incoming --yes
Resolution previews first; --yes accepts the displayed current replacement.
--take local retains current work and acknowledges the conflict. Original
evidence stays in history. In the terminal, /vault conflicts, /vault conflict <id> and /vault resolve <id> local|incoming share the service; resolution opens
a literal confirmation modal and refuses changed evidence. Task recaps identify
related unresolved conflicts. Sync commands retain terminal-only origin bounds.
Metadata
Release files for hey-dave 0.2.0a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hey_dave-0.2.0a1.tar.gz | 4.4 MB | With provenance | Details for hey_dave-0.2.0a1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hey_dave-0.2.0a1-py3-none-any.whl | Python 3 | none | any | Details for hey_dave-0.2.0a1-py3-none-any.whl |
Total release size: 9.0 MB
Release files / hey_dave-0.2.0a1.tar.gz
| Download URL | hey_dave-0.2.0a1.tar.gz |
|---|---|
| Size | 4.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
43bad03a6918a0974abae1034f9fc8e04a5faf986d0e14d34e8452e3a85e970f
|
|
BLAKE2b-256 checksum How to use checksums |
4e1d489d32a42decdd1b3e47791494c96b8f8436c30dbb57c2df0eea5131de1f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.
Transparency logRelease files / hey_dave-0.2.0a1-py3-none-any.whl
| Download URL | hey_dave-0.2.0a1-py3-none-any.whl |
|---|---|
| Size | 4.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
98a3da952a77567d33fef748ec9c1a844237b75b5b36aa0bf0648fb7fa8be53c
|
|
BLAKE2b-256 checksum How to use checksums |
1fbef478fab01533963357eeac97cf28f408d2c17f1040c15f0a17b2fec9f1b9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.
Transparency logSecurity for hey-dave 0.2.0a1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for hey_dave-0.2.0a1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.