What is IntentLoop?

IntentLoop is a Rust CLI tool for recording AI agent coding sessions locally. It wraps any agent command — GitHub Copilot, custom LLM prompts, or shell scripts — and captures the full session: intent metadata, terminal output, structured events, and a minimal Markdown report.

Everything stays on your machine. No cloud, no telemetry, no accounts.

Session recording

Wrap any command with intentloop run to capture a full session. The command runs inside a real pseudo-terminal (PTY), so interactive tools work exactly as expected. Every keystroke, every line of output, every ANSI escape sequence is recorded.

# Record any command as a session
intentloop run -- echo "hello-intentloop"

# Record with a specific intent reference
INTENT_ID=auth-jwt-001 intentloop run -- cargo test

GitHub Copilot integration

Run GitHub Copilot CLI sessions directly inside IntentLoop with full PTY interaction and transcript capture. IntentLoop auto-detects gh copilot or falls back to gh agent-task, so you always get a recorded session.

# Auto-detect backend
intentloop copilot

# Force a specific backend
intentloop copilot --mode copilot -- suggest "analyze auth flow"
intentloop copilot --mode agent-task -- create "Refactor auth module"

# Wait for final result (agent-task)
intentloop copilot --mode agent-task --wait

Inspect sessions

Every session is stored with a unique ID. Use intentloop show to inspect metadata, view paths to the raw terminal log, events JSONL, and the generated report.

intentloop show a3f9c1e2-7b44-4d8a

Intent references

Create an INTENT.md file in your repo root to link sessions to specific development intents. IntentLoop reads the id and title fields and embeds them in session metadata.

# INTENT.md
id: auth-jwt-001
title: Login refactor to JWT

Local storage

All session data is stored in ~/.intentloop/ (or $INTENTLOOP_HOME) with a clean, inspectable layout. SQLite for metadata, flat files for logs and reports.

~/.intentloop/
  db.sqlite              # Session metadata
  sessions/
    <session_id>/
      terminal.raw.log   # Full PTY transcript
      events.jsonl       # Structured events
      report.md          # Summary report

Environment variables

IntentLoop auto-loads .env from the current directory. Configure your LLM provider and API keys per-project without polluting your global environment.

LLM_PROVIDER=openai
LLM_MODEL=gpt-4o
LLM_API_KEY=your_key
INTENTLOOP_HOME=/path/to/custom/store

Commands

Single binary

Written in Rust. Compiles to a single, fast binary. Install via Cargo or build from source. No runtime dependencies, no containers, no cloud services required.