ArtifactGuard

ArtifactGuard is a privacy-aware CLI for AI-assisted development workflows. It snapshots your workspace, detects agent-created artifacts, classifies source/temporary/sensitive files, safely deletes disposable artifacts, and generates end-of-session cleanup reports.

Problem

AI coding agents often create temporary files while solving tasks: downloaded documents, extracted archives, debug logs, scratch scripts, JSON dumps, and one-off reports. These artifacts can clutter workspaces and may create privacy risk when sensitive files are left behind.

ArtifactGuard provides a lightweight artifact lifecycle layer for these sessions.

Install

From npm:

npm install -g artifact-guard

From source:

git clone https://github.com/ekta-chaudhry/artifact-guard.git
cd artifact-guard
pnpm install
pnpm build
pnpm link --global

Then run from any workspace:

artifact-guard --help

Commands

artifact-guard start                 # Capture a baseline workspace snapshot
artifact-guard status                # Show files changed since the snapshot
artifact-guard finish                # Classify artifacts and print a cleanup report
artifact-guard finish --delete-safe  # Delete created files classified as safe temporary artifacts
artifact-guard finish --interactive  # Review safe temporary artifacts before deleting
artifact-guard finish --report       # Write .artifact-guard/report.md
artifact-guard finish --clean-state  # Remove .artifact-guard/session.json after finish

Flags can be combined:

artifact-guard finish --interactive --report --clean-state
artifact-guard finish --delete-safe --report --clean-state

--delete-safe and --interactive are mutually exclusive.

Example Workflow

artifact-guard start

# Simulate agent work
echo "debug" > debug.log
echo "SECRET=value" > .env.test
echo "# Notes" > notes.md

artifact-guard status
artifact-guard finish --delete-safe --report

Example report categories:

• Source changes: Git-tracked files, code, docs, config, and deleted tracked files
• Temporary artifacts: logs, archives, scratch/debug files
• Sensitive / needs review: env files, credentials, resumes, patient/customer exports
• Deliverables: reports or document outputs
• Unknown / needs review: untracked files not matched by current rules

Safe Deletion Policy

finish --delete-safe deletes only files classified as both:

• temporary
• created

finish --interactive uses the same safety boundary, but asks before deleting each safe candidate.

ArtifactGuard does not auto-delete or offer interactive deletion for:

• modified files
• source changes
• sensitive files
• deliverables
• unknown files
• deleted-file records

Git-Aware Classification

When run inside a Git repository, ArtifactGuard uses git ls-files to identify tracked files.

This means:

• modified Git-tracked files are classified as source-impacting changes even if their extension is unknown
• untracked files are still classified by sensitive, temporary, deliverable, source-extension, or unknown rules
• sensitive patterns take priority over Git tracking for privacy-first reporting

If Git is unavailable or the workspace is not a Git repository, ArtifactGuard falls back to pattern and extension-based classification.

ArtifactGuard State

ArtifactGuard creates its own state directory in the workspace:

.artifact-guard/
├── session.json   # created by `artifact-guard start`
└── report.md      # created/updated only when `--report` is used

By default, finish keeps this state so you can inspect the session and report afterwards.

Use --clean-state to remove the session snapshot after finish completes:

artifact-guard finish --report --clean-state

Behavior:

• removes .artifact-guard/session.json
• keeps .artifact-guard/report.md when --report is used
• removes the empty .artifact-guard/ directory if no report or other state files remain

Markdown Reports

Use --report to write a session report:

artifact-guard finish --report

Output:

.artifact-guard/report.md

The report includes:

• summary counts
• safe-to-delete bytes
• deleted bytes when cleanup runs
• preserved source/sensitive/deliverable/unknown counts
• grouped artifact categories
• classifier reasons
• cleanup policy
• deleted/skipped files when --delete-safe is used

Configuration

Add .artifactguardrc.json to customize project rules:

{
  "ignore": ["coverage/**", "tmp/**"],
  "sourceExtensions": [".toml"],
  "temporaryPatterns": ["*.debug.json", "scratch/**"],
  "sensitivePatterns": ["*resume*", "*patient*", "*secret*"],
  "deliverablePatterns": ["reports/**", "deliverables/**"]
}

See .artifactguardrc.example.json for a starter config.

Pattern values support simple glob-like * / ** matching. Regex strings are also supported with /pattern/flags syntax.

AI Agent Integration

Integration examples are included for common agent workflows:

integrations/pi-skill/SKILL.md
integrations/claude-code/CLAUDE.md
integrations/codex/AGENTS.md
integrations/generic-agent/ARTIFACTGUARD.md

They show how AI coding agents can run ArtifactGuard at the start and end of artifact-producing tasks.

CI

GitHub Actions runs on pushes and pull requests to main:

pnpm install --frozen-lockfile
pnpm build
pnpm test

Workflow file:

.github/workflows/ci.yml

Current Behavior

• start stores a baseline snapshot in .artifact-guard/session.json
• status shows created, modified, and deleted files since the baseline
• finish classifies changes and prints cleanup recommendations
• Git-tracked files are classified as source-impacting changes
• finish --delete-safe deletes only created temporary artifacts
• finish --interactive prompts before deleting safe temporary artifacts
• finish --report writes .artifact-guard/report.md
• finish --clean-state removes .artifact-guard/session.json after finishing

Planned Features

• Multi-session history

Development

pnpm install
pnpm build
pnpm test
pnpm dev -- start
pnpm dev -- status
pnpm dev -- finish