Content
# recit
> **Record it. Agents see it.**
Free, open-source screen recording CLI + MCP server for AI agents. Zero cost. 100% local. No cloud. No API keys.
## Features
- **Screen Recording** — Capture full screen, windows, or regions via ffmpeg
- **Screenshots** — Instant PNG capture with JSON metadata output
- **MCP Server** — 5 tools exposed via Model Context Protocol (stdio)
- **Frame Extraction** — Scene-detection key frames for vision model analysis
- **Event Logging** — JSONL event log synced to video clock (clicks, keystrokes, annotations)
- **Cross-Platform** — macOS, Windows, Linux
- **$0 Cost** — No APIs, no cloud, no hosting, no subscriptions
## Quick Start
```bash
# For Claude Code
claude mcp add recit -- npx -y @zum-x/recit
# For Cursor / VS Code — add to mcp.json:
{
"mcpServers": {
"recit": {
"command": "npx",
"args": ["-y", "recit"]
}
}
}
# Prerequisites (both free)
brew install ffmpeg # macOS
sudo apt install ffmpeg # Ubuntu/Debian
winget install ffmpeg # Windows
```
## CLI Usage
```bash
# Start recording
recit start [--output path] [--fps 15] [--json]
# Stop recording
recit stop <id> [--json]
# Capture screenshot
recit snap [--output path] [--json]
# Extract frames from video
recit frames <video> [--max 20] [--output dir]
# Check recording status
recit status [id]
# Start MCP server
recit mcp
```
## MCP Tools
| Tool | Description |
|------|-------------|
| `recit_start` | Start screen recording |
| `recit_stop` | Stop recording, get file path |
| `recit_snap` | Capture screenshot |
| `recit_frames` | Extract key frames from video |
| `recit_status` | Get recording status or active count |
## Architecture
```
AI Agent (Claude/Codex/Cursor)
│
│ stdio (stdin/stdout)
▼
recit MCP Server (Node.js, local)
│
│ child_process
▼
ffmpeg (free, local)
│
▼
.mp4 / .png saved to user's disk
```
**$0 spent. Nothing uploaded. Everything local.**
## Development
```bash
git clone https://github.com/codedbytahir/recit.git
cd recit
npm install
npm test # Run 43 tests
npm run build # Build TypeScript
```
## Tech Stack
| Layer | Tool | Cost |
|-------|------|------|
| Recording | ffmpeg | $0 |
| Agent Integration | MCP SDK (stdio) | $0 |
| Distribution | npm | $0 |
| Code Hosting | GitHub | $0 |
| Runtime | Node.js | $0 |
| Testing | Vitest | $0 |
## License
Apache 2.0
