# Run your agent through a week of work in seconds.

Minutehand, Alknoma’s free tool for engineers building proactive AI agents, runs your agent through simulated days of work in seconds and tells you how well it carried the work. The agent talks to fake Slack, Teams, Jira, Notion and other services, with people who answer late or not at all. Each finding names the declaration it was measured against.

Product site: https://minutehand.ai. Source: https://github.com/Alknoma/minutehand. Package: https://pypi.org/project/minutehand/.

## Install it and run a scenario

Write a scenario (its goal, its people, what they know and when they answer) and an agent file, then run your agent's own command under Minutehand.

```
pip install minutehand
minutehand run scenario.yaml --agent agent.yaml -- python agent.py
minutehand findings <run_id>
```

Needs Python 3.12 or later. The repository has a worked example in `examples/follow_up`.

## The services your agent works in

Minutehand points the agent at fakes through its environment (HTTPS_PROXY and a CA bundle), so the agent calls the services as it would in production.

Slack, Microsoft Teams, Asana, Jira, YouTrack, Notion, GitHub, Google Drive, AWS EventBridge, AWS SQS, Google Cloud Tasks.

## What a run gives you

- **People who answer late, or never.** A scenario declares who knows what and when each person answers. Simulated people reply on that schedule, or not at all.
- **Minutehand owns the clock.** Days of work play out in a few seconds. The agent's wakes, deadlines and reply windows all run on the simulated clock.
- **One import, inert in production.** The one change to the agent’s code is `minutehand.agent`, which does nothing unless `MINUTEHAND_ON` is set.
- **Findings against your declarations.** Too early, too late, the same message again with nothing new, a move the service refuses, acting before an approval: each finding names the declaration it was held to.
- **Fork a finished run.** Fork any run from a checkpoint with the prompt, the model, a person or the world changed, and play it forward again.
- **Every run is queryable.** Read a run with SQL over documented views, with `trace` and `explain`, or through the same tools over MCP.
- **Built for CI.** `minutehand run-all` plays every scenario in a folder in parallel and exits 1 when a verdict differs from the one the scenario expects.
- **Invented facts, with --judge.** With --judge and a model, a reviewer flags facts the agent was never given, such as a made-up quote, for a person to review.

## Licence

Free to use. Source-available under FSL-1.1-ALv2; each release becomes Apache 2.0 two years after it ships.

Want us to build and secure it for you? https://www.alknoma.com/services