# AgentHandover learns your workflows by watching you work

> AgentHandover is a macOS app that records what you do on screen, turns the recording into a Skill with steps, strategy, guardrails and your writing voice, and hands that Skill to Claude Code, Codex, OpenClaw or any MCP-compatible tool. The loop is genuinely clever, and it depends on screen recording, an approving step and an agent that reports back after each run.

**sandroandric/AgentHandover** — What if OpenClaw, Claude Code, Codex etc. knew how to do your work without you saying it? AgentHandover observes you, learns and teaches your agents with self-improving skills.

- Repository: https://github.com/sandroandric/AgentHandover
- Stars: 702 · Forks: 58
- Language: Python
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/sandroandric-agenthandover

## The premise is that you should not have to describe your own job

The stated problem is that getting an AI agent to do real work means writing prompts or hand-crafting skills, which the project calls brittle, time-consuming and stale the moment your process changes, and worse, skills that capture what you do rather than how you decide. AgentHandover inverts that. You work, the system watches, and it produces Skills that carry the reasoning. Each Skill is described as capturing the what, the why and the how, broken down into steps, strategy, decision logic, guardrails and your writing voice, and each one also says plainly what it does not know yet. The target audience is not a developer audience, incidentally. The listed use cases are research routines, community engagement on Reddit or Discord, support triage, data extraction from dashboards and CRMs, ops checklists, and any personal workflow you would rather not explain twice. The rule of thumb the project gives is blunt: if it is a workflow you have done three times and will do again, it belongs in a Skill. The tooling is meant for a Mac user, and the badge in the README says macOS, with local-first storage described as a feature.

## Recording, three questions, then a human approval

The quickstart is six steps, and the middle three are where the judgement lives. You install the app, then click Record in the menu bar, give the recording a name such as Daily Reddit marketing, perform the task once, and click Stop. The recording cannot capture everything a screen watcher sees, so the app asks up to three questions about what the recording could not show, for example what starts the task, when it is done, or a step it is unsure about. Those questions are the mechanism by which intent enters the Skill, and asking at most three is a deliberate constraint that keeps the loop short. You then open the Skill in the menu bar app, read the steps, strategy and guardrails, and click Approve for Agents. Nothing reaches an agent before that click. This is the single most important design decision in the project. An inferred workflow can be wrong, and an agent that acts on a wrong workflow at speed is worse than no agent at all, so the human review sits between observation and execution. It also means the cost of a bad inference is one rejected Skill rather than a run of wrong actions.

## What a generated Skill actually contains

The example Skill in the README shows a concrete file, and the shape of it explains why the approach works better than a prompt. It has a title and a header line recording the workflow type, the number of steps and the number of sessions learned, so the artifact carries its own history. Then a STRATEGY section written in prose that explains how to find high-signal posts and what a good reply looks like, and a numbered STEPS section with each step as an imperative. After that come two parallel lists, SELECTION CRITERIA and GUARDRAILS, which is the part a hand-written prompt usually lacks. Selection criteria describe what qualifies for the action, and guardrails describe the limits, such as a maximum number of replies per day, never using identical phrasing, never replying to your own posts, and an empathy-first tone. A VOICE AND STYLE section records tone, sentence length and a sample reply, and the file closes with a time estimate and a confidence percentage. The last part matters most: the Skill states its own confidence, so a caller can decide how much to trust it.

## Skills improve through an agent report-back loop

The learning mechanism is the second half of the design and it is unusual. Agents report back after every run. A run that follows the steps confirms them, so the Skill gains sessions and keeps the confirmed path. A run that deviates at a point where the recorded decision was only a guess turns into a question for you. In other words, the system treats your own recorded uncertainty as the thing to ask about, rather than asking about everything. The consequence is that a Skill is not a frozen artifact. It carries a count of sessions learned, and its decision logic is refined as evidence accumulates from actual runs rather than from a single demonstration. The cost of that design is that the loop only closes if your agent tool actually reports back. That is a protocol assumption, and the integration surface is what makes it plausible. The Skills follow the same format as Claude Code's native skills, with the same frontmatter, and the connect step accepts claude-code, codex, openclaw and hermes, with any MCP-compatible tool named as a target.

## The 2.0 release adds a searchable memory of your screen

Version 2.0 added two things, and the release titles tell you how they landed. The v2.0.3 release on 2026-10-14 is titled Browse Commonplace; the right window, v2.0.2 on the same day is titled Upgrades with capture paused, and v2.0.1 is titled Swap guard and Memory-only setup fixes. Three releases in one day, each fixing a rough edge, which tells you this was a large change landing quickly. The new features are 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, with the example queries being the invoice from Acme and that orange news site. If you allow it, your agents can search that memory too. Commonplace appears to be the browsing surface over that store, given the release title. The pause on capture during an upgrade, and the setup fix for a memory-only configuration, are the kind of details you only see in a release built by someone using the tool daily. They are also the details that tell you the local store is a real database with real lifecycle, and that the project treats screen contents as sensitive data.

## A Rust core, a Python worker and a native app

The repository layout shows a multi-language build with a clear division. The Cargo.toml at the root declares a Rust workspace with four members, daemon, common, storage and cli, and a shared dependency set built on serde for serialisation, tokio for async work, tracing for logging, anyhow and thiserror for error handling, uuid and chrono, and rusqlite with the bundled and backup features, which points to a local SQLite store for the memory. The Python side is the worker, configured separately in pyproject.toml for pytest.

```toml
[tool.pytest.ini_options]
testpaths = ["worker/tests", "tests/e2e", "tests/integration", "tests/load"]
pythonpath = ["worker/src", "worker/tests"]
# importlib mode avoids the tests/__init__.py namespace collision between
# worker/tests and the repo-root tests/ directories.
addopts = "--import-mode=importlib"
markers = ["eval: evaluation harness and scorecard tests"]
```

The test layout separates unit tests for the worker from end to end, integration and load tests, and the marker list includes an eval harness with scorecard tests, which is how the project measures whether a generated Skill actually works. The justfile at the root holds the build recipes, and build-all compiles the daemon, the CLI, the extension, the worker and the app, with the daemon recipe building both aarch64-apple-darwin and x86_64-apple-darwin targets and combining them with lipo into a universal binary. The TypeScript side is thin, a package.json with a single dependency on @cli-me/cli, and the rest of the tree is the native app in app/, the browser extension in extension/, a homebrew directory for distribution, a config.example.toml and a rust-toolchain.toml.

## The costs of a screen watcher on your machine

Two constraints are visible in the documentation and neither is a bug. The first is the platform. The app is a macOS application, the build recipes target apple-darwin specifically, and the quickstart starts with downloading a .pkg installer that walks you through permissions. The README does not describe a Linux or Windows version, so this is a Mac-only tool today. The second is the data. Everything the system sees on your screen goes into a private memory on the machine, and the project says the agents can search it if you allow it. That is the mechanism that makes the recall feature work, and it is also the reason to think carefully about what you leave running. A screen watcher sees every application you open, not just the workflow you recorded, which is a much larger exposure than a prompt describing a process. The mitigating details are worth noting too: the storage is local, the badge says local-first, and the search interface takes a plain description rather than requiring an embedding pipeline you have to operate. The remaining risk is ordinary, and it is the risk of any tool that reads your screen: a captured secret, a customer record or a half-finished draft sits in the store until you delete it, and the README does not document a retention or purge policy for it.

## Licence, release cadence and what to check first

The licence picture needs a note. The repository is listed under Apache-2.0, and the README carries a licence badge, but the Rust workspace declares its own licence as MIT.

```toml
[workspace.package]
version = "2.0.3"
edition = "2021"
license = "MIT"
```

Two different licences across two build systems in one repository is ambiguous, so if you plan to ship anything derived from it, resolve which one applies. The maintenance picture is the healthier half of this project. The last push was on 2026-10-14, the same day as the v2.0.1, v2.0.2 and v2.0.3 releases, so the code is moving, and the version numbers in the workspace show a 2.0.3 build with edition 2021 on Rust. The project is also distributed through a homebrew directory and through GitHub releases with an .pkg installer, which means the install path is a signed package rather than a build from source, which is the right choice for a tool that asks for screen and accessibility permissions. For an evaluation, the order of operations matters. Install the package, record one task you know well, refuse the inferred steps you disagree with, approve the rest, then connect one agent and watch a single run before letting the report-back loop start refining the Skill.

## Conclusion

Adopt AgentHandover if you are on a Mac, you repeat workflows an agent could do for you, and you are willing to review and approve each generated Skill before an agent uses it. Skip it if you are on Linux or Windows, if your work happens where a screen recorder cannot follow, or if you need the generated Skills to be guaranteed accurate rather than probably right. Before your first run, read the recording step carefully, because the app stores what it sees on your screen in a private memory, and check the licence, since the project is filed under Apache-2.0 while the Rust workspace declares MIT.

## FAQ

### How do I install and set up AgentHandover?

Download the latest .pkg from the GitHub releases and double-click it. The onboarding app walks you through permissions, recommends models for your Mac's memory and downloads them, after which you record a task from the menu bar, answer up to three questions and approve the resulting Skill.

### Which coding agents can AgentHandover hand Skills to?

The connect command accepts claude-code, codex, openclaw and hermes, and the project names any MCP-compatible tool as a target. The generated Skills follow the same format as Claude Code's native skills, with the same frontmatter.

### Does AgentHandover work on Linux or Windows?

Not as documented. The project is a macOS application, the build recipes target apple-darwin, and the install path is a .pkg package, with no Linux or Windows version described in the README.

### What is the Memory feature added in AgentHandover 2.0?

Everything AgentHandover sees on your screen also goes into a private memory on your Mac that you can search by describing it, such as the invoice from Acme. If you allow it, your agents can search that memory too, and Commonplace is the browsing surface added in 2.0.3.

### How do AgentHandover Skills improve over time?

Agents report back after every run. A run that follows the recorded steps confirms them, while a run that deviates where a decision was only a guess becomes a question for you, so the decision logic is refined from actual runs rather than from a single demonstration.

## Sources

- [Issues](https://github.com/sandroandric/AgentHandover/issues)
- [License: Apache-2.0](https://github.com/sandroandric/AgentHandover/blob/main/LICENSE)
- [README](https://github.com/sandroandric/AgentHandover/blob/main/README.md)
- [Releases](https://github.com/sandroandric/AgentHandover/releases)
- [sandroandric/AgentHandover on GitHub](https://github.com/sandroandric/AgentHandover)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sandroandric-agenthandover