llms.txt
# Minutehand
> Minutehand is Alknoma's free testing tool in the proactive agent space. It runs your agent through simulated days of work in seconds, against fake Slack, Teams, Jira, Asana, Notion, GitHub and Google Drive, with people who answer late or not at all, then reports every move made too early, too late, twice, or on invented facts.
Made by Alknoma (https://alknoma.com). Source: https://github.com/Alknoma/minutehand. Install: `uv tool install minutehand` or `pip install minutehand` (Python 3.12+).
## Pages
- [Home](https://minutehand.ai/): what Minutehand is and how it works; as text at https://minutehand.ai/index.md
- [Q&A](https://minutehand.ai/questions): testing proactive agents with Minutehand; every answer in full at https://minutehand.ai/questions.md
- [Everything in one file](https://minutehand.ai/llms-full.txt)
## Questions
- [How do you validate proactive agents?](https://minutehand.ai/questions#how-to-validate-proactive-agents): Minutehand, Alknoma's testing tool in the proactive agent space, validates proactive agents by running them through simulated days of work in seconds. The agent talks to fake Slack, Jira, Notion and other services while simulated people answer late or never. Minutehand then reports what went wrong: acting too early or too late, repeating itself, or inventing facts.
- [How do you test an AI agent for hallucinations before it goes live?](https://minutehand.ai/questions#how-to-test-an-agent-for-hallucinations): Minutehand, in the proactive agent space, checks an agent for hallucinations by replaying everything it did against what each simulated person was allowed to know. Run with --judge, a reviewer model reads every message, ticket and action as the agent could know it at that moment, and flags any fact, quote or amount it was never given.
- [Can I simulate an AI agent's conversations before it goes live?](https://minutehand.ai/questions#can-i-simulate-before-go-live): Minutehand, in the proactive agent space, simulates an agent's conversations, and the days between them, before it goes live. Simulated people reply late, follow a script, or stay silent, through fake Slack, Teams, Jira, Notion and other services. Nothing the agent sends reaches a real person or system, and each run takes a few seconds.
- [How do you catch hallucinations that cascade across an agent's steps?](https://minutehand.ai/questions#cascading-hallucinations): Minutehand, in the proactive agent space, records every step an agent takes in an append-only log, so a made-up fact can be followed from where it first appeared to every message, ticket and action it reached. minutehand explain shows what led to any event. Forking the run from that checkpoint with a fix shows whether the cascade stops.
- [How can a test cover days of an agent's work in a few seconds?](https://minutehand.ai/questions#how-to-test-days-in-seconds): Minutehand, in the proactive agent space, owns the clock. Instead of waiting in real time, it moves simulated time straight to the next thing that matters: a reply landing, a deadline, or a wake the agent booked for itself. A run that covers two simulated weeks of follow-ups usually finishes in a few seconds.
- [What mistakes does Minutehand catch in a proactive agent?](https://minutehand.ai/questions#what-does-minutehand-catch): Minutehand, in the proactive agent space, catches the mistakes that only show over time: a follow-up sent too early or too late, a message sent again with nothing new, a move the service would refuse, and a made-up fact. Timing findings name the declaration they broke; a reviewer model flags made-up facts for a person to check.
- [Do I have to change my agent's code to test it with Minutehand?](https://minutehand.ai/questions#do-i-have-to-change-my-agent): Minutehand, in the proactive agent space, needs one import in your agent's code, and it does nothing in production. Minutehand starts your agent's own command and points it at the fakes through HTTPS_PROXY, NO_PROXY and a CA bundle. What the agent remembers goes through minutehand.agent.store, which in production passes straight through to your own database.
- [Which services can Minutehand simulate for an agent?](https://minutehand.ai/questions#which-services): Minutehand, in the proactive agent space, ships fakes for Slack, Microsoft Teams and Graph, Asana, Jira, YouTrack, Notion, GitHub, Google Drive with Docs and Slides, AWS EventBridge Scheduler and SQS, and Google Cloud Tasks. Hosts without a fake can be acknowledged, passed through, replayed, or forwarded to an emulator you run yourself.
- [How does Minutehand simulate the people an agent works with?](https://minutehand.ai/questions#how-are-people-simulated): Minutehand, in the proactive agent space, writes each simulated person's replies with a language model, from what the scenario says that person knows and when they answer. It works with any OpenAI-compatible API or Anthropic's. For runs that must be identical every time, an offline stand-in answers by fixed rules instead of a model.
- [How do you run proactive agent tests in CI?](https://minutehand.ai/questions#how-to-run-in-ci): Minutehand, in the proactive agent space, runs in CI with minutehand run-all <folder>, which plays every scenario in the folder in parallel and exits 1 when a verdict differs from the scenario's expect_outcome. A single minutehand run exits 0 on a pass and 1 on a failure, so any CI system can gate a merge on it.
- [What does forking a run from a checkpoint do in Minutehand?](https://minutehand.ai/questions#what-is-a-fork): Minutehand, in the proactive agent space, can restart any finished run from a checkpoint with one thing changed: the prompt, the model, a person, or the world. The fork starts from the agent's memory exactly as it stood at that moment and plays forward again, so you can see whether the change would have fixed the failure.
- [Is there an audit trail of everything an agent did in a Minutehand run?](https://minutehand.ai/questions#how-to-read-a-run): Minutehand, in the proactive agent space, records every run as plain SQL views you can query: every action, message, HTTP call, memory change, wake and model call, with bodies decoded. minutehand trace lists the agent's acts in order, and minutehand explain shows what led to one event. The same tools are available over MCP.
- [Is Minutehand open source?](https://minutehand.ai/questions#licence): Minutehand, in the proactive agent space, is source-available under the Functional Source License (FSL-1.1-ALv2). You can read, run and modify it, and each release becomes Apache 2.0 on its second anniversary. It installs from PyPI with uv tool install minutehand or pip install minutehand, and needs Python 3.12 or newer.
- [How does Minutehand compare to Maxim?](https://minutehand.ai/questions#minutehand-vs-maxim): Minutehand, in the proactive agent space, and Maxim both simulate AI agents before release. Maxim is a simulation, evaluation and observability platform that plays multi-turn conversations with simulated users across scenarios and personas. Minutehand plays a proactive agent through simulated days against fake Slack, Jira and others, and fails a run on duplicates, refused moves or acting before an approval.
- [How does Minutehand compare to Braintrust?](https://minutehand.ai/questions#minutehand-vs-braintrust): Minutehand, in the proactive agent space, tests a proactive agent before release through simulated days of work against fake Slack, Jira and others, failing the run on duplicates, refused moves or acting before an approval. Braintrust is an observability and evaluation platform: it traces agents, turns production traces into eval datasets, and scores outputs with LLMs, code or humans.
- [How does Minutehand compare to Galileo?](https://minutehand.ai/questions#minutehand-vs-galileo): Minutehand, in the proactive agent space, runs a proactive agent through simulated days against fake Slack, Jira and others, and fails the run on duplicates, refused moves, acting before an approval or after the deadline. Galileo is an observability, evaluation and guardrail platform for generative AI and agents, with built-in metrics, synthetic test datasets and models that monitor production traffic.
- [How does Minutehand compare to LangSmith?](https://minutehand.ai/questions#minutehand-vs-langsmith): Minutehand, in the proactive agent space, simulates the days and services around a proactive agent: fake Slack, Jira and Notion, people who answer late, and services that refuse moves, and fails runs on duplicates. LangSmith traces and evaluates LLM apps and agents from any framework, with datasets, LLM-as-judge and code evaluators, and multi-turn simulation with an LLM-simulated user.
## The hard parts of a proactive, durable agent
- [Why does a proactive agent send the same message twice?](https://minutehand.ai/answers/why-does-a-proactive-agent-send-the-same-message-twice): Minutehand, Alknoma's free testing tool in the proactive agent space, fails a run when an agent sends the same words twice with nothing new between them. It happens when a wake cannot see what the last wake sent: memory kept in a process that restarted, a retry after a timeout, or a wake delivered twice. As text: https://minutehand.ai/answers/why-does-a-proactive-agent-send-the-same-message-twice/index.md
- [How does a proactive agent survive a restart without losing its place?](https://minutehand.ai/answers/how-does-a-proactive-agent-survive-a-restart): Minutehand, Alknoma's free testing tool in the proactive agent space, tests whether an agent's memory outlives its process. A proactive agent survives a restart by keeping each open ask, who owes it and when it is due in a store the process does not own, and by reading that store on every wake rather than trusting what it remembers. As text: https://minutehand.ai/answers/how-does-a-proactive-agent-survive-a-restart/index.md
- [Why does a proactive agent act before an approval?](https://minutehand.ai/answers/why-does-a-proactive-agent-act-before-an-approval): Minutehand, Alknoma's free testing tool in the proactive agent space, fails a run in which an agent acts before the approval its instructions wait on. Agents do it when they take a person's remark as the sign-off, read the approval's state once and never again, or lose track across wakes of what was still pending. As text: https://minutehand.ai/answers/why-does-a-proactive-agent-act-before-an-approval/index.md
- [How do you reproduce a failure a proactive agent took days to reach?](https://minutehand.ai/answers/how-do-you-reproduce-a-proactive-agent-failure): Minutehand, Alknoma's free testing tool in the proactive agent space, reproduces a failure days into an agent's work by replaying the run from its record and forking it from the checkpoint before the failure. The fork starts from the agent's memory as it stood there and plays forward with the prompt, the model, a person or the world changed. As text: https://minutehand.ai/answers/how-do-you-reproduce-a-proactive-agent-failure/index.md
- [Why is a proactive agent harder to test than a chatbot?](https://minutehand.ai/answers/why-is-a-proactive-agent-harder-to-test-than-a-chatbot): Minutehand, Alknoma's free testing tool in the proactive agent space, exists because a proactive agent's mistakes are about time, not words. A chatbot's test is one prompt and its reply. A proactive agent decides when to act, across days, with people who answer late or never, so its test has to play those days and those people. As text: https://minutehand.ai/answers/why-is-a-proactive-agent-harder-to-test-than-a-chatbot/index.md
