<div align="center">

agent-receipts

Append-only local receipts for AI agent actions: capture commands, outputs, and handoff evidence, then expose them to agents over MCP.

<img src="demo.gif" alt="Demo" width="700" />

</div>

---

🎯 Why?

Trending agent projects increasingly mention evidence logs, verifiable handoffs, and agent observability, but most solutions are large frameworks or platform-specific hubs. Developers using Claude Code, Codex, OpenCode, or custom agents need a tiny local-first tool that simply records what happened and proves it was not edited. agent-receipts fills that gap with a zero-depend CLI plus a minimal MCP adapter.

Target audience: Developers running AI coding agents, agent-framework authors, and platform/security engineers who need lightweight local audit trails, reproducible handoffs, and evidence that an agent really ran a command or completed a step.

✨ Features

• ✨ Capture command executions with stdout/stderr tails, exit codes, duration, cwd, agent, session, and tags
• ✨ Append-only hash-chained JSONL receipts with tamper detection via verify
• ✨ Manual evidence notes for handoffs, plus search/export and a minimal MCP stdio server

🚀 Quick Start

# Install
pip install agent-receipts

# Run
agent-receipts --help

📦 Installation

From Source

git clone https://github.com/YOUR_USERNAME/agent-receipts.git
cd agent-receipts

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest -v

🎬 Demo

The GIF above was recorded using Charm VHS:

vhs < demo.tape

📖 Usage

# Show help
agent-receipts --help

# Common usage examples
agent-receipts --example

🏗️ Architecture

graph LR
    A[Input] --> B[Core Engine]
    B --> C[Output]
    B --> D[Plugins]
    D --> E[Extensions]

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT © 2026 — See LICENSE for details.

---

<div align="center">

If this project helped you, please ⭐ star it!

Made with ❤️ and AI

</div>