HouseCap

Free · local · Linux-first screen recorder CLI
Cap-inspired (not affiliated with Cap / CapSoftware). No paid cloud required.

Record your screen under X11, optional mic + system audio, agent-friendly --json, optional MCP + local library HTTP.

Why

Cap is a great open Loom alternative (desktop + cloud + official Cap CLI). HouseCap fills a practical gap:

Cap	HouseCap
Strong on macOS / Windows desktop	Linux + X11 CLI first
Cap Cloud share links	Local files (optional self-host copy)
Official agent CLI / MCP	Free house CLI + skill + MCP

Use official Cap where it fits; use HouseCap when you want zero-cost local Linux recording for humans and agents.

Features

• Screen capture via ffmpeg x11grab
• Optional microphone and system audio (PulseAudio)
• Detached record start / record stop
• Machine-readable --json
• MCP server (stdio) for coding agents
• Optional library HTTP (127.0.0.1:8795) list/download
• MIT licensed

Requirements

• Linux with X11 session (DISPLAY set)
• ffmpeg
• pactl (recommended for audio)
• python3 (MCP + library serve)
• xdpyinfo (optional, display size probe)

# Debian / Ubuntu / Mint
sudo apt install -y ffmpeg pulseaudio-utils x11-utils python3

Install

git clone https://github.com/teamrustyonmars-byte/housecap.git
cd housecap
chmod +x housecap install.sh agents-install.sh housecap_mcp.py housecap_serve.py
./install.sh
# optional: agent skill + MCP snippet
./agents-install.sh grok    # or: cursor | all | print

Ensure ~/.local/bin is on your PATH.

Quick start

housecap doctor --json
housecap targets --json

# ask a human before recording if you're an agent
housecap record start --system-audio --mic --json
housecap record stop --json
housecap recordings list --json

Recordings default to ~/.local/share/housecap/recordings/.

Agents

CLI

housecap guide --json   # discover contract

MCP

housecap mcp serve
# or: python3 housecap_mcp.py

Tools include doctor, targets, record start/stop (start requires confirmed=true), recordings list, share local.

Snippets after ./agents-install.sh:

• ~/.grok/housecap-mcp.snippet.json
• ~/.cursor/housecap-mcp.snippet.json

Merge into your agent MCP config and restart the agent.

Safety (Cap-like)

1. Confirm before record and share.
2. Prefer guide --json over guessing flags.
3. Never invent cloud URLs — return real paths only.
4. Do not pass secrets into MCP.

Local library service (optional)

housecap serve
# GET http://127.0.0.1:8795/v1/health
# GET http://127.0.0.1:8795/v1/recordings
# GET http://127.0.0.1:8795/files/<name>.mp4

Default bind is localhost only. For LAN, set HOUSECAP_SERVE_BIND=0.0.0.0 deliberately (trusted networks only).

Optional systemd user unit: housecap-serve.service.

Environment

Variable	Meaning
HOUSECAP_RECORDINGS	Output dir
HOUSECAP_STATE	PID / meta dir
HOUSECAP_SHARE	Optional copy root for share local
HOUSECAP_SERVE_BIND	HTTP bind (default 127.0.0.1)
HOUSECAP_SERVE_PORT	HTTP port (default 8795)
HOUSECAP_BIN	Path to CLI (MCP)

Layout

housecap              # main CLI (bash)
housecap_mcp.py       # MCP stdio server
housecap_serve.py     # local library HTTP
install.sh            # symlink to ~/.local/bin
agents-install.sh     # skill + MCP snippets
SKILL.md              # agent skill text
housecap-serve.service

Wayland / later

X11 is supported today. Wayland (wf-recorder / portals) is a welcome contribution — see CONTRIBUTING.md.

License

MIT — see LICENSE.

Credits

Inspired by Cap and Cap for Agents (cap.so, CapSoftware/Cap). HouseCap is an independent free Linux-oriented project.