AgentHandover

_{Created by Sandro Andric}

AgentHandover

Work once. Hand over forever.

Demo · Quickstart · Use Cases · What a Skill Looks Like · How It Works · Memory · Commonplace · What's New · Connect Your Agent · Install · Privacy · Contact

Demo

New demo · Original demo

Show it once. Hand it off forever.

AgentHandover watches how you work on your Mac, turns your workflows into reusable Skills, and lets agents like Claude Code, OpenClaw, Hermes, Codex, or any MCP-compatible tool execute them the way you do it.

Each Skill captures the what, the why, and the how — steps, strategy, decision logic, guardrails, and your writing voice — and says plainly what it doesn’t know yet. And they learn from use: agents report back after every run, runs that follow the steps confirm them, and a run that deviates where a decision was only a guess turns into a question for you.

You already know how to do your work. Now your agents can too.

New in 2.0: Memory and Commonplace. Everything AgentHandover sees on your screen also goes into a private memory on your Mac that you can search by describing it: “the invoice from Acme”, “that orange news site”. If you allow it, your agents can search it too.

Why this matters

Getting an AI agent to do real work today means writing prompts or hand-crafting skills — brittle, time-consuming, and stale the moment your process changes. Worse, those skills capture what you do, not how you decide.

AgentHandover flips it. Instead of telling the agent how you work, you just work. The system watches, infers the strategy behind your clicks, and produces Skills with the why built in — selection criteria, guardrails, decision branches, your voice. Because agents report back after every run, Skills get better the more they’re used.

Less time writing prompts. More time doing work that matters.

What you can automate

AgentHandover learns whatever you do repeatedly on your Mac. A few examples of the kinds of workflows it handles well:

• Research routines — Your way of scanning sources, extracting key facts, and composing a summary.
• Community engagement — Daily check-ins on Reddit, Discord, or forums with your selection rules and voice.
• Support triage — How you read a ticket, check the dashboard, pick a macro, and draft a reply.
• Data extraction — Pulling structured data from a dashboard, CRM, or spreadsheet the way you do it.
• Ops checklists — Deploys, releases, status updates — your actual sequence with the decisions you make.
• Personal skill library — Any repetitive workflow you don’t want to explain to an agent twice.

If it’s a workflow you’ve done three times and will do again, it belongs in a Skill.

Quickstart

1. Install. Download the latest .pkg from Releases and double-click. The onboarding app walks you through permissions, recommends models for your Mac’s memory, and downloads them.
2. Record a task. Click Record in the menu bar, name it (e.g. “Daily Reddit marketing”), perform it once, click Stop.
3. Answer up to 3 questions. AgentHandover asks about what the recording couldn’t show — “What starts this task?”, “When is it done?”, or a step it isn’t sure of.
4. Review and approve. Open the Skill in the menu bar app, check the steps/strategy/guardrails, click Approve for Agents.
5. Connect your agent. agenthandover connect claude-code (or codex / openclaw / hermes). One command.
6. Run it. In Claude Code, type /reddit-community-marketing (or just describe the task). The agent executes your workflow.

That’s the whole loop. Record once, hand off forever.

What a Skill Looks Like

Here’s an illustrative example of what a Skill looks like:

Reddit Community Marketing
Daily engagement workflow - 6 steps - 4 sessions learned

STRATEGY
Browse target subreddits for posts about marketing tools or growth
hacking. Engage with high-signal posts (10+ comments, posted within
48h, not promotional). Write authentic replies that acknowledge the
problem, share personal experience, and softly mention the product.

STEPS
1. Open Reddit and navigate to r/startups
2. Scan posts - skip promotional, skip < 10 comments
3. Open high-signal post and read top comments
4. Write reply: acknowledge -> experience -> mention product
5. Submit and verify not auto-removed
6. Repeat for r/marketing, r/growthacking (max 5/day)

SELECTION CRITERIA              GUARDRAILS
- Posts with 10+ comments       - Max 5 replies per day
- Not promotional or competitor - Never identical phrasing
- Posted within 48 hours        - Never reply to own posts
- Relevant to [product category]- Empathy-first tone always

VOICE & STYLE
Tone: casual | Sentences: short and punchy | Uses emoji
> Hey great point about the engagement metrics! We should
> def try that approach with the subreddit

~15 min daily - 9-10am                     Confidence: 89%

Skills follow the same format as Claude Code’s native skills – same frontmatter, same markdown structure – but go further. Hand-written skills say “do X then Y.” AgentHandover Skills include the strategy behind the steps, selection criteria, guardrails, your voice, and evidence from real observations: every step cites the frames it came from, and anything the recording didn’t settle is listed as an open question instead of guessed.

How It Works

Two ways to teach

Focus Recording – Click Record in the menu bar, name the task, perform it, click Stop. AgentHandover writes the Skill, checks every step against the recording, and asks up to 3 questions about what it still doesn’t know (what starts the task, when it’s done, a step it couldn’t confirm). The Skill is waiting as a draft a few minutes after you stop. Best for workflows you want to hand off right now.

Passive Discovery – Just work normally. AgentHandover groups your work into sessions, notices when the same task recurs, and drafts a Skill for the ones worth handing off (at most three new drafts a week). When you repeat a task you already have a Skill for, the session is recorded as another run of that Skill instead of a new one, and where you did it differently it becomes a branch. You don’t have to do anything.

You stay in control

Every Skill starts as a draft in your menu bar app. An agent sees it only when all four checks of the hand-off gate pass (ledger.handoff_gate, applied by the MCP server, every connector and every export):

An approved Skill that fails a check is listed by list_ready_skills as held back, with the reason. Nothing auto-promotes; the system only suggests.

Memory

New in 2.0. Find anything you saw on your Mac by describing it. Each screen AgentHandover keeps is embedded, the screenshot together with its app and window title, by Google’s EmbeddingGemma 2 running in Ollama on your Mac. Near-identical screens of the same window in a row become one moment, so a long day stays a short list.

• Search from the menu bar (Commonplace…, the Memory scope), from the CLI (agenthandover memory search "the Acme invoice"), or let your agents search it (below).
• What is kept. For each moment: a short redacted description (the screen’s annotation, or its screen text until one exists), the app and window title, the time and a search vector. The screenshot is deleted once it is embedded. A small thumbnail (about 480 px) is kept for 7 days to show in results, encrypted with a key in your Keychain that only the app and the capture daemon use. After that the description and vector remain, for a year by default.
• Never kept. What the privacy zones block: password managers, macOS password prompts, Keychain Access, banking, payroll and sign-in pages, and the apps, sites and hours you add to [privacy.zones].
• Forget and pause. Forget the last hour, today, one moment, one app or everything, from the menu, the Commonplace window or agenthandover memory forget. Forget deletes the screens, descriptions, vectors, thumbnails, search entries and that day’s summaries; your approved Skills stay. Pause Memory for an hour, until tomorrow or until you resume; Skills still learn from what you do.
• Agents. One switch, off by default: Let agents search my Memory (Memory Settings, or agenthandover memory agents on). Agents then find Memory through Commonplace (search_commonplace, or search_memory, over MCP; agenthandover search in a terminal): descriptions, apps, window titles and times, never images or file paths.
• Light. Embedding is a low-priority background job, about half a second a screen. It waits while macOS reports memory pressure or less than 2 GB is free, while a two-model tier is writing Skills, and after 600 screens in an hour; its model is unloaded a minute after the last screen.
• Needs Ollama 0.40 or later (EmbeddingGemma 2 runs on Ollama’s MLX runner) and embeddinggemma-2:440m (710 MB), which setup or the upgrade offer downloads.

How well it finds things. On the 16 GB test Mac (Ollama 0.40.3), 26 screens (20 public web pages in look-alike pairs and 6 app screens) and 52 questions, half about what a screen said and half about how it looked, run through Memory’s own writer and search: the right screen came first for 90% of the questions and was in the top five for all of them; for questions about the look, 88% first. Embedding the same screens’ title and screen text with nomic-embed-text, the model 0.5 searches with, found 75% first, and 65% of the questions about the look. One small set, so indicative. On real Safari windows captured by AgentHandover on the same Mac (16 pages, each opened from another app, so the window came up still showing the previous page), searched through the Memory window’s search afterwards: all 16 questions about what a page said found it first; 14 of 16 about how it looked found it first and 15 of 16 were in the top three.

Memory only. If you want Memory without Skills, choose Memory only in setup or in Memory Settings (or run agenthandover skills learn off). AgentHandover then keeps capturing and filling Memory, and runs no model but Memory’s: no screen descriptions, Skill drafts, questions or daily summaries, so nothing larger than the 710 MB embedding model is downloaded or loaded. Commonplace, pause, forget, privacy zones and agents’ Memory search work as usual; your existing Skills stay available to your agents. Descriptions are the screen’s own text, since nothing writes annotations. Switch back with Skills + Memory (agenthandover skills learn on); the menu then offers to download the Skill models.

Upgrading from 0.5, the app asks once: Add Memory (Skill search keeps nomic-embed-text), Upgrade everything (Skill search, task grouping and session linking move to EmbeddingGemma 2 too: your Skills are re-indexed in the background and switched over in one step when it is done, and search keeps working meanwhile), or Not now. New installs use EmbeddingGemma 2 for everything.

Commonplace

New in 2.0. Everything AgentHandover knows about your work, in one place your agents can search: Skills (the workflows it learned from you, and whether each may be handed off), Memory (what was on your screen, only when you let agents search it), daily summaries (what you worked on each day) and your profile (tools, working hours, writing style). All of it stays on your Mac.

• In the app. Commonplace… in the menu bar opens one search over your Memory, days and Skills, grouped by kind (what you saw first), with scope chips (All, Memory, Days, Skills). Before you type it lists the newest of each, newest first. Return opens a result: a moment in place, a Skill in Workflows, a day in the Daily Digest. Your own search always includes Memory; a line at the top says what agents can see and turns their Memory access on or off.
• Agents know it exists. The MCP server’s instructions describe Commonplace to every connected agent, and agenthandover connect adds a short Commonplace note where each agent reads its instructions (Claude Code’s /agenthandover-list, Codex’s AGENTS.md block, an agenthandover-commonplace Skill for Hermes, memory/apprentice/commonplace.md in the OpenClaw workspace; connect mcp prints it for any other agent).
• One search, grouped by kind. search_commonplace(query, kinds?, since?, until?, limit?) over MCP (an empty query lists the newest of each kind), agenthandover search "…" in a terminal (--kinds skills,memory,days,profile, --since, --until, -n, --json), or POST /commonplace/search on the REST API. Each kind is ranked by its own scorer and returned in its own group, so a Skill’s score is never weighed against a Memory moment’s. When an embedding model is busy or down, that kind falls back to matching the query’s words and says so.
• What agents get. Text: Skill titles, descriptions and hand-off status; Memory descriptions, apps, window titles and times; a day’s date, apps and an excerpt of its tasks; the profile. Never vectors, images, thumbnails or file paths. Memory answers only while Let agents search my Memory is on; otherwise its group says how you can turn it on. The switch applies to the next search, no restart.
• Things to try. In the app (Commonplace offers these too while nothing is kept yet): “the invoice from Acme”, “that page with the orange header” (by how it looked), “the error in the terminal”, “how I deploy to staging” (a Skill), “the day I spent in Figma” (a day). Ask your agent:
  • “Write my weekly update from what I actually did this week.”
  • “Find the pricing article I read yesterday and summarise it.” (needs Memory access)
  • “Pick up where I left off on the onboarding doc.” (needs Memory access)
  • “Before you ask me how I release, check my Skills.”
  • “Roast my week: where did my hours really go?”
• What it is not. A permission boundary against software that already runs as you. The switch governs what AgentHandover hands to agents (MCP, agenthandover search, the REST search); an agent that can run any command as you (Claude Code with shell access, for example) can do what you can, including agenthandover memory search, and the data lives in files under your home folder that any process with your file access can read, as with any app’s data. AgentHandover tells connected agents never to change its settings or read its files; it cannot enforce that against a process running as you.

The Knowledge Base

Everything AgentHandover learns lives in a local knowledge base on your machine. It’s not a flat list of files – it’s an active intelligence layer that gets smarter the more you work.

Knowledge ledger – Every Skill tracks what it knows: each slot (goal, steps, done criteria, trigger, decisions, verification, inputs, exceptions, guardrails, voice, context) is known, a hypothesis, or unknown, with pointers to the frames, answers or agent runs behind it. Questions come from the gaps (unknown or guessed slots, and steps the recording didn’t settle), within a budget of 5 a week (weekly_question_budget), and no model writes them.

Vector store – Every observation is embedded (nomic-embed-text, 768d) so the system finds similar workflows by meaning, deduplicates Skills that describe the same task differently, and links activity across sessions.

Voice profiles – Your writing style accumulates per workflow and strengthens over sessions. One reply is a guess. Twenty replies is a fingerprint the agent can match. Casual on Reddit, formal in client emails – the system knows the difference.

User profile – Aggregated across all workflows: your tools, working hours, communication patterns, and overall writing style. Agents read this to adapt to you.

Semantic search – Agents can search the knowledge base by meaning via the MCP server or REST API. “Find something about deploying” returns your staging deployment Skill even if it’s titled “Push to Prod.” When the embedding model is busy or down, search falls back to matching the query’s words in titles, descriptions, tags and steps.

Execution Feedback Loop

Most tools stop at “here’s a procedure, good luck.” AgentHandover closes the loop. When an agent executes a Skill, it reports back what happened – and the Skill learns from it.

How it works: Every Skill includes an execution protocol. The agent calls report_execution_start before beginning, report_step_result after each step, and report_execution_complete when done. Every run is kept, and:

• Completed – counts toward the Skill’s execution confidence (kept apart from how well the Skill is grounded in what you did) and confirms it is still current. After 3 runs that follow the steps as written, the steps count as known.
• Deviated – what the agent did instead is kept as an observed alternative for that step. A deviation where a decision was only a hypothesis makes that decision unknown again and asks you about it.
• Failed – recorded with the error as a drift signal on the Skill.

Agent runs never rewrite your steps on their own: the Skill changes through your answers and your review.

One-click agent pairing

The menu bar app detects installed agents (Claude Code, Cursor, Windsurf, Codex, OpenClaw) and connects them with one click: Claude Code through claude mcp add --scope user, Codex through codex mcp add, the others by adding the server to their MCP config file. The menu shows Connected only when the agent reports the server (for Claude Code claude mcp list, for Codex codex mcp list --json).

Connect Your Agent

Every connector hands over only the Skills that pass the hand-off gate, and tells the agent about Commonplace.

MCP Server (recommended)

One config line, any agent. Works with Claude Code, Cursor, Windsurf, and any MCP-compatible tool.

{
  "mcpServers": {
    "agenthandover": {
      "command": "agenthandover-mcp"
    }
  }
}

It exposes these tools and resources (generated from the server):

Claude Code

agenthandover connect claude-code

Installs every Skill that passes the hand-off gate as a Claude Code Skill (~/.claude/skills/<slug>/SKILL.md) and registers the MCP server with claude mcp add --scope user --transport stdio agenthandover -- /usr/local/bin/agenthandover-mcp. Type /reddit-community-marketing, or describe the task and Claude Code picks the Skill. /agenthandover-list lists them.

Codex

agenthandover connect codex

Writes all agent-ready Skills, strategy, guardrails, and voice guidance into ./AGENTS.md (or --path), between <!-- BEGIN agenthandover --> and <!-- END agenthandover --> markers; a rerun replaces only that block. An existing AGENTS.md without the markers is left alone unless you pass --append (add the block at the end) or --force (replace the file).

OpenClaw

agenthandover connect openclaw

With [export] adapter set to openclaw or all (a pkg install writes all), the worker writes approved Skills into the OpenClaw workspace (~/.openclaw/workspace/memory/apprentice/); the command checks the workspace and reports what is synced.

Hermes

agenthandover connect hermes

Installs your Skills into ~/.hermes/skills/agenthandover/<slug>/SKILL.md for Hermes, Nous Research’s self-improving agent. Hermes walks ~/.hermes/skills/ looking for SKILL.md files (agentskills.io / anthropic-skills convention), so AgentHandover Skills drop in directly — /skills lists them, /<skill-name> runs them. For live semantic search and the execution-feedback loop, also add the MCP server to ~/.hermes/config.yaml:

mcp:
  servers:
    agenthandover:
      command: "agenthandover-mcp"

REST API

Already running on localhost:9477 (loopback only). Every POST needs the X-AgentHandover-Token header; the worker keeps the token in a file only your user can read. Requests that carry a browser Origin header, or a Host other than 127.0.0.1:9477 / localhost:9477, are refused, so a web page cannot reach the API.

curl http://localhost:9477/ready              # Agent-ready Skills
curl http://localhost:9477/bundle/my-workflow  # Handoff bundle (read only)
TOKEN=$(cat ~/Library/Application\ Support/agenthandover/query-api-token)
curl -X POST http://localhost:9477/bundle/my-workflow \
  -H "X-AgentHandover-Token: $TOKEN"          # Compile it for every adapter
curl -X POST http://localhost:9477/search/semantic \
  -H "X-AgentHandover-Token: $TOKEN" \
  -d '{"query": "deploy to production"}'      # Semantic search
curl -X POST http://localhost:9477/commonplace/search \
  -H "X-AgentHandover-Token: $TOKEN" \
  -d '{"query": "the Acme invoice", "kinds": ["memory", "days"]}'  # Commonplace

Install

Download and run

Download the latest .pkg from Releases and double-click. Requires macOS 14 (Sonoma) or later and Ollama; Memory needs Ollama 0.40 or later.

The onboarding app walks you through: permissions, AI model downloads (it recommends a tier for your Mac’s RAM and shows the memory each tier needs against what is free now), Chrome extension, and your first recording.

Upgrading keeps your observing state: if you were observing before, capture resumes as soon as macOS permissions are in place, and setup opens only at a permission that is missing. A model configuration that the app or installer wrote for an earlier default (including every 0.4.x setup) moves to your tier’s current models, but only once they are downloaded: until then your Mac keeps the models it has. After upgrading from 0.4.x the app asks once, “0.5 uses a faster model (…). Download now?”; the download is 1.9 GB (qwen3.5:2b-q4_K_M) if you ran 0.4’s Standard models and 3.4 GB (qwen3.5:4b) otherwise, and the switch (after a timestamped backup) happens when it finishes. “Not now” keeps your current models until the next upgrade; agenthandover doctor names the switch and agenthandover setup --tier <tier> makes it. A [vlm] block you edited yourself is left alone.

agenthandover doctor     # Verify prerequisites
agenthandover start all  # Start daemon + worker

# Or pull manually (Recommended tier):
ollama pull qwen3.5:4b          # Screen annotation and Skills (~3.4 GB)
ollama pull embeddinggemma-2:440m  # Search and Memory, Ollama 0.40+ (~710 MB)
ollama pull nomic-embed-text    # Search with an older Ollama (~274 MB)
# Standard tier (8 GB) adds:
ollama pull qwen3.5:2b-q4_K_M   # Screen annotation (~1.9 GB)
# Performance tier (24 GB) adds:
ollama pull gemma4:12b-it-qat   # Skill generation (~7.2 GB)

agenthandover setup --extension

brew tap sandroandric/agenthandover
brew install --cask agenthandover

git clone https://github.com/sandroandric/AgentHandover.git && cd AgentHandover
just package-pkg              # builds daemon + CLI + extension + app, then runs
                              # scripts/build-pkg.sh to package target/AgentHandover-<version>.pkg
sudo installer -pkg target/AgentHandover-*.pkg -target /

Choose your AI model

AgentHandover runs its models locally through Ollama: free and private. Screen annotation, Skill writing, synthesis, questions and embeddings all use Ollama, on your Mac or on another machine you point [vlm] ollama_host at. There is no cloud mode (it was removed in 0.5.0).

Pick the tier’s models via config.toml or agenthandover setup --vlm.

The Menu Bar App

AgentHandover lives in your menu bar:

• Status – daemon and worker health
• Today’s stats – events captured, annotations completed, Skills generated
• Attention items – questions waiting, drafts ready for review
• Record – one click to start a focus recording
• Workflows – browse all Skills, approve drafts, see what each Skill knows and what it doesn’t
• Memory – search what you saw, pause Memory, forget the last hour or today, and Memory Settings
• Digest – daily summary of what was learned, and the questions still open

Review the strategy, steps, and guardrails. Click “Approve for Agents” when it looks right. One click. No Skill reaches agents without your sign-off.

Privacy

Everything runs on your machine:

• Local-only models. Every model runs through Ollama on your Mac (or the Ollama host you configure). No cloud model API is called and no API key is stored.
• Screenshots are temporary. Each frame is a JPEG of the focused window at half its native pixel resolution (one pixel per point on a Retina display), deleted after annotation and, with Memory on, after it is embedded (Memory gives up on a frame it could not embed within 48 hours). Frames never annotated are deleted by the daily maintenance run once they are older than job_ttl_days (default 7). Only structured text, Memory’s vectors and its encrypted thumbnails survive.
• Memory stays on your Mac. Its descriptions, vectors and thumbnails are stored with the rest of your data, and the thumbnails are AES-256-GCM encrypted with a key kept in your Keychain. A Memory vector encodes what was on screen, so treat it like the screenshot it came from: it never leaves the Mac, agents get descriptions only when you allow it, and forget deletes it.
• Redaction where the data flows. API keys, tokens, passwords (including “password is …” phrasings) and card numbers are scrubbed by the daemon before anything is stored, and again by the worker before any text goes into a model prompt. URLs keep their origin and path; query strings are dropped except for a short allow-list of harmless keys.
• Blocked by default. Password managers, macOS password and Touch ID prompts, permission dialogs, the login window, Apple’s Passwords app, and banking, payroll and login pages are never captured, and neither are AgentHandover’s own windows (Commonplace shows other moments, so capturing it would copy them). Add your own apps, URLs and quiet hours as privacy zones ([privacy.zones]): the daemon checks them before it takes a frame and again after, and the worker once more on stored events.
• Secure field exclusion. Password and credit card inputs are never captured, and form values are left out of browser snapshots unless you turn on capture_input_values.
• No keylogging. Each frame records only how many keys were pressed since the previous frame (macOS’s key-press counter): no key codes, no text, no event tap, no Input Monitoring permission. Typed text in a Skill must be backed by it. Keys from text expanders, remote control and automation count; text inserted by Apple Dictation or other voice typing presses no key, so dictated text is not recorded as typed input yet.
• Clipboard. A copy is recorded as an event; the copied text itself is kept only if you turn on enable_clipboard_preview.
• Reading app state is opt-in. Reading the open document, page or message from Safari, Mail, Notes and a few other apps needs macOS’s per-app Automation consent, so it is off until you turn it on in onboarding.
• Knowledge base is local. Vector store, voice profiles, and all Skills live on your machine. Never uploaded.
• No encryption at rest of its own, except Memory’s thumbnails. Screenshots, the event database and the knowledge base are stored as plain files under your home folder; turn on FileVault to encrypt them on disk.
• Configurable retention. Raw events are deleted after 14 days (retention_days_raw); the Skills keep the evidence they cite.
• No telemetry. AgentHandover sends no usage data and none of your content anywhere. The only request the app makes on its own is Sparkle’s daily update check against www.agenthandover.com/appcast.xml; turn it off with defaults write com.agenthandover.app SUEnableAutomaticChecks -bool false.

                              You work normally
                                    |
                                    v
Chrome Extension -----> Daemon (Rust) ---SQLite WAL---> Worker (Python)
  DOM snapshots           Screenshots                     |
  Click targets           OS events                       v
  Form field IDs          Clipboard                  Pipeline:
                          Change detection           Text-first annotation
                          Privacy zones              Activity classification
                    Menu Bar App (SwiftUI)            Embeddings
                    Status - Record - Workflows      Sessions + recurrence
                    Digest - Questions               Skill generation
                                                     Grounding
                                                     Behavioral synthesis
                                                     Knowledge ledger
                                                          |
                                                          v
                                              +------------------------+
                                              |    Knowledge Base      |
                                              |                        |
                                              |  Skills (v3 schema)    |
                                              |  Knowledge ledger      |
                                              |  Vector store (768d)   |
                                              |  Voice profiles        |
                                              |  User profile          |
                                              |  Evidence + runs       |
                                              +-----+------+-----------+
                                                    |      |
                                      +-------------+      +------------+
                                      v              v                  v
                                MCP Server     Claude Code       OpenClaw
                                (any agent)    Skills            Hermes
                                Codex          REST API
                                AGENTS.md      localhost:9477

Uninstall

agenthandover uninstall              # Remove services, keep data
agenthandover uninstall --purge-data # Remove everything

Contributing

AgentHandover is early and unusually high-leverage for contributors. The prompt files, agent connectors, and skill templates are all plain text that anyone can read, run, and improve — a careful hour of prompt tuning can measurably change the quality of every Skill the tool produces for every user.

Ways to help (no code required)

• Share a Skill you actually use. Record a real workflow, review the generated Skill, and post it in Discussions → Show & Tell. Real workflows beat synthetic examples and become the reference library everyone learns from.
• Report bad outputs. Did a generated Skill miss a step, add a redundant click, or misread your strategy? Open an issue with the Skill + what it should have been. The prompts get tuned directly from this feedback.
• Bug reports from real usage. Everything is logged locally so reproductions are usually easy. The more unusual your Mac setup, model tier, or workflow, the more valuable the report.
• Answer questions in Discussions. Anyone who’s used the tool for more than a week has context new users need.

Code contributions we’d love

• New agent connectors. Follow the pattern in worker/src/agenthandover_worker/agent_connect.py. Cline, Aider, RooCode, and any agent that reads Claude Code-format skills or MCP are straightforward — the Hermes and Codex connectors are short, and every connector hands over only what passes ledger.handoff_gate.
• Model runtimes. Every model call goes to Ollama through one client (worker/src/agenthandover_worker/ollama.py). A second local runtime for annotation and Skills (with structured output) would be a real addition.
• Prompt engineering. The prompts in sop_generator.py and behavioral_synthesizer.py drive the entire output quality. If you see a way to make them more precise, more robust, or better at handling your language, send a PR; agenthandover bench and the recorded journey cassettes let you measure the change.
• Browser extension ports. Chrome / Chromium / Brave / Edge / Arc / Comet are supported. Firefox and Safari are wide open.
• Privacy review. This is a local-first tool that handles sensitive data. Extra eyes on crates/common/src/redaction.rs, the worker’s prompt-side redaction.py, the privacy zones and the screenshot retention path (crates/storage/src/maintenance.rs) are genuinely wanted.

Getting started

If you’re not sure where to begin, open a Discussion with a rough idea — it’s faster to shape something together than to send a PR cold. Small PRs get reviewed quickly. If your contribution is non-trivial, running just test and cargo test before opening the PR saves a review round-trip. tests/integration/test_docs.py and the CLI’s docs_tests keep this README’s tables and commands in step with the code.

Direct line for anything that doesn’t fit: [email protected].

Community

Join the AgentHandover Discord →

The Discord is where the community actually talks in real time:

• #skills-gallery — share a Skill you’re using and see what other people have built
• #help — get a response in minutes instead of days
• #bugs — fast triage before things become GitHub issues
• #dev — prompt engineering, connector authors, contributor chat
• #announcements — release notes and updates

GitHub Discussions and Issues are still the right home for anything that should be public and searchable long-term — bug reports with reproductions, feature proposals, design discussions. Discord is for the ephemeral stuff in between.

Contact

[email protected]

Changelog

v2.0.3

• Commonplace shows what it keeps before you type. Open it and the newest moments, days and Skills are there, newest first; type to search. Agents can ask for the newest too (search_commonplace with an empty query).
• Frames are of the window you work in. A toolbar on top could be captured instead of your window: every Comet frame was one of its toolbar strips, a black band. Frames now come from the app you are using, from its titled window (the page, the document), never a bar.

v2.0.2

• Upgrading while capture is paused works. The database upgrade ran only when capture started, so a Mac upgraded with capture paused stayed on the old database and AgentHandover waited for it: no Memory, no search, and Commonplace said the worker was not running. The worker now runs the same upgrade itself (agenthandover db migrate), so everything works right after an update, paused or not.

v2.0.1

Fixes found on the first upgrade of a 24 GB MacBook Pro.

• The Skills model’s swap limit follows the Mac. 2.0.0 held back the model that writes Skills whenever more than 8 GB of swap was in use, on every Mac; swap stays in use long after the pressure that caused it, so a 24 GB Mac at 8.5 GB of swap would not write Skills. The worker now waits while macOS reports memory pressure (warning or critical), as Memory already did, and keeps swap only as an emergency stop at twice the Mac’s memory (32 GB on a 16 GB Mac, which still catches the ~44 GB that once crashed our test Mac). agenthandover doctor warns at the same points.
• Setup speaks of the mode you picked. With Memory only selected, setup’s Ollama panel still warned about the Skill models (their Ollama minimum and the swap limit), because it read the settings file, which names the mode only after the download. It now reports for the mode on screen: in Memory only, an Ollama older than 0.40 is the one problem, said plainly. Setup no longer says “Local setup looks good.” when there is nothing it can download, and the button says “Pull Model” for Memory’s one model.

v2.0.0

The biggest release yet. AgentHandover grows from Skills into a private memory of everything you saw, and Commonplace, one place you and your agents search for everything it knows: what you saw, your days and your Skills. The version jumps from 0.5 to 2.0 to say so. Numbers are measurements on the 16 GB test Mac with Ollama 0.40.3 unless stated.

• Memory. Search anything you saw by describing it, from the menu bar, the CLI or (if you allow it) your agents. Each kept screen is embedded with its app and window title by EmbeddingGemma 2 on your Mac; near-identical screens of one window become one moment. On 52 questions about 26 screens: the right screen first 90% of the time, in the top five every time, 88% first for questions about how a screen looked (0.5’s text search: 75% and 65%). See Memory.
• Commonplace. Your Skills, Memory, daily summaries and profile as one hub your agents know about and can search (search_commonplace over MCP, agenthandover search in a terminal), grouped by kind, text only, Memory only when you allow it. See Commonplace.
• The Commonplace window. Commonplace… in the menu bar: one search over what you saw, your days and your Skills, with thumbnails, a moment opening in place, a Skill in Workflows and a day in the Daily Digest, and a line saying what your agents can see. Empty, it suggests searches and requests to give your agents (“Roast my week: where did my hours really go?”).
• Light enough to leave on. Memory embeds each screen in about half a second as a background job that waits while macOS reports memory pressure; its search index is held as 8-bit numbers, loaded on the first search and freed after 10 idle minutes (300,000 moments: 207 MB while in use instead of 666 MB, with identical results).
• Memory only. Want Memory without Skills? Choose Memory only in setup or Memory Settings: AgentHandover then runs one 710 MB model and nothing else, no Skill writing in the background. See Memory.
• Private by construction. Thumbnails are AES-256-GCM encrypted with a Keychain key and kept 7 days; descriptions are redacted; privacy zones are never kept; forget deletes a time range, an app, a moment or everything, including the day’s summaries; nothing captured while Memory is paused is ever kept, nor are AgentHandover’s own windows; agents’ access is a separate switch, off by default, and returns text, never images.
• EmbeddingGemma 2 for search. New installs use it for Skill search, task grouping and session linking too; upgraders choose Add Memory or Upgrade everything (a background re-index that switches over in one step). Every threshold was measured on labelled sets for both models: with EmbeddingGemma, session linking separates same-task from different-task pairs completely (nomic: two thirds), and Skill search ranked 15 of 16 agent questions first (nomic: 16 of 16).
• Frames show the right page. A frame used to be taken the moment a window’s title changed, before the app had drawn the new page, so it could show the page you were leaving. Capture now waits until the window has been still for a second (at most three), one frame per change.
• Fixes in search. Search compared vectors of different models when they had the same size, and the daily vector purge would have deleted the vectors of any model but the configured one; /search/semantic answers malformed requests with 400 instead of crashing.
• Removed. The SigLIP “Visual search” option: it stored image vectors that nothing ever searched. If you had it on, the upgrade offer says Memory replaces it.
• Needs Ollama 0.40 or later for Memory and EmbeddingGemma 2; with an older Ollama everything else works as in 0.5 and agenthandover doctor says what to update.

v0.5.0

The biggest release since the first one, and the one where the product does what this README says. Skills are built from what was actually recorded, a recording turns into a Skill and its questions in minutes instead of most of an hour, everything runs on your Mac, and it stays light enough to leave on all day. Numbers are single measurements on a 16 GB test Mac (Ollama 0.34.2) unless stated.

• Right-sized models. The 16 GB tier runs Qwen 3.5 4B for everything, and 8 GB Macs annotate with Qwen 3.5 2B (see AI Models for the head-to-head). On the same kind of focus session, Stop to questions went from 50 minutes with Gemma 4 12B (v0.4.0’s 16 GB default) to ~2.5 minutes (later sessions took 3.5 and 5); the Skill was written in 60 s instead of 549 s.
• Memory-aware scheduling. Where a tier has two models the worker loads one at a time, checks memory, swap and disk first, and defers instead of pushing the Mac into swap. Model work runs on one inference thread in priority order, so the app stays responsive during long calls.
• Event-driven capture. Frames when something happens, of the focused window at one pixel per point (a 1324×940 pt Safari window is captured at 1324×940 px). Unchanged screens skip OCR and the model.
• Text-first annotation. A small model reads OCR and page elements (~2.2 s a frame) and looks at the image only when needed; a cache answers screens already seen. On a recorded busy hour: 1,190 cache hits and 10 model calls instead of 896 and 304, and 422 model-seconds within the 600 s hourly budget.
• Privacy where the data flows. Redaction before storage and before every prompt, URL query strings dropped, macOS password, Touch ID and permission prompts blocked, privacy zones checked before and after the shutter, clipboard text off by default, reading app state opt-in.
• Grounded Skill steps. Every step is checked against the recording: a copy or paste needs clipboard evidence, a scroll or save needs screen evidence, typed lines are quoted exactly and need key presses behind them (text the model read off a toolbar no longer becomes a “type” step), clicks carry DOM anchors, steps keep the recorded order and cite their frames. Passively discovered Skills get element anchors too.
• Knowledge ledger and budgeted questions. Each Skill tracks what it knows, guesses and doesn’t know, with evidence. The four-check hand-off gate replaces the six gates. Questions come from the gaps (up to 3 after a recording, 5 a week) and no model writes them.
• Recognition of repeated workflows. Passive mining measures recurrence and drafts at most 3 new Skills a week; doing a task you already have a Skill for becomes a run of it (a branch where you did it differently), not a duplicate. Drafts keep learning from later runs until you approve them, and a run interrupted by a call stays one run.
• Agent runs feed Skills. Three runs that follow the steps confirm them; a deviation on a guessed decision reopens it as a question.
• Doctor checks the machine. The serving Ollama’s version and install, duplicate installs, and memory, swap and disk headroom; an old Ollama fails only when a Gemma 4 model is configured.
• Upgrades keep observation on. Setup reopens only at a missing permission, stale grants from a changed signature are reset, and model configs written for an earlier default move to the tier’s current models once the app has downloaded them.
• Agents. search_skills answered in 17.5 s instead of 255 s while Ollama was busy (an 8 s embedding timeout and a keyword fallback). Claude Code pairs through claude mcp add with a real Connected check; Codex gets a marked AGENTS.md block.
• Light enough to leave on. Idle with capture on, the menu bar app uses about 0.3 s of CPU a minute and the capture daemon 0.09 s; models unload when there is nothing to do, and model time is capped per hour and per day. The daily pass that compared every pair of tasks with its own model requests (35,983 requests on the three-week journey) now makes 422.
• The daily pass works again. Since v0.4.0 it stopped on every day with work, so the daily digest, profile, patterns and the day’s questions never ran from it.
• Capture starts reliably. With a Chromium browser open, the app took the extension’s helper for the capture daemon and never started it, after upgrades and at login. A second recording no longer erases the first one’s unanswered questions, and upgrades remove the files a release dropped.
• Cluster labels and synthesis run every day. The LLM reasoner and the behavioral synthesizer used to share their daily budget with the VLM fallback queue, so after 50 unclassified events a day every later cluster label and synthesis was skipped without a word. They now have their own budget ([vlm] reasoning_max_calls_per_day, reasoning_max_compute_minutes_per_day), and when it is spent worker-status.json and agenthandover status --compute say so.
• Removed. Cloud mode: it never did the main work (screen annotation and Skill writing always ran on Ollama), and by 0.5.0 it only sent the older focus path’s Skill steps to a provider for a description, while reading its API key from an environment variable the app never set. The upgrade turns an old cloud config local (with a backup) and deletes the stored API key. Also the MLX and llama.cpp backends (they only ever served the fallback queue), the fallback queue itself (its answers fed nothing but its own re-scoring), the legacy pattern miner, the six gates, and config keys that nothing read.
• Corrections to v0.4.0’s notes. Homebrew’s ollama 0.34.2 runs the QAT tags on the test Mac, and the Gemma tiers need Ollama 0.34.0+, not 0.30.6.

v0.4.0 (2026-06-09)

New default local models — Google’s QAT (Quantization-Aware Training) Gemma 4 checkpoints — chosen by a head-to-head A/B test on a real focus recording, not by spec sheets.

The 16 GB tier moves from Gemma 4 E4B to Gemma 4 12B QAT (and uses less memory: ~7 GB vs ~9.6 GB). In the A/B, the E4B model couldn’t even identify what the recorded workflow was — it returned “Unclear … the user does not complete a final artifact” on both runs. The 12B QAT model correctly identified the task both runs (“Drafts a daily news digest email, subject ‘Thursday Daily News’, aggregating updates from X, Reddit, and Hacker News”), extracted a typed variable, and produced goal-directed steps. A 12B-dense model fits where a 4B-effective one used to, and reasons dramatically better about why you did what you did — which is where Skill quality lives.

New tier table:

The 8 GB tier stays on Qwen 3.5 — we A/B-tested the smallest Gemma QAT (e2b) there too, and it was a regression: the 2B model got the task wrong both runs while Qwen 3.5:4b nailed it. Small models lose the plot; we didn’t ship that to the most constrained users.

Ollama 0.30.6+ now required for the Gemma tiers. The QAT tags need it (older Ollama returns HTTP 412 on pull). Install the official Ollama app or brew install --cask ollama-app — note the Homebrew ollama formula does not bundle the GGUF runner and cann

README 内容过长，已截取前 64 KB。完整内容请前往 GitHub 仓库查看。