Checkpoint Skill

The Checkpoint Skill provides file snapshots for agents, enabling version control of the agent's working directory.

[!NOTE] The Python implementation uses Git as the underlying store and exposes commands as /checkpoint/* slash commands. The TypeScript implementation uses content-hashed manifests under .webagents/checkpoints/ and exposes its operations as regular agent tools (no slash commands). Both produce restorable snapshots; the storage layout differs. Track parity at internal/python-typescript-parity.md.

Overview

Checkpoints are stored in the agent's local .webagents/ directory:

Git History: <agent_path>/.webagents/history/ (Git repository)

Metadata: <agent_path>/.webagents/checkpoints/ (JSON files)

Commands

All checkpoint commands require owner scope by default.

Create Checkpoint

Create a new checkpoint snapshot.

/checkpoint/create [description] [files]

Or use the alias:

/checkpoint

Parameters:

Parameter	Type	Description
`description`	str	Description of the checkpoint
`files`	str	Comma-separated list of files to snapshot (all files if not specified)

Example:

/checkpoint create "Before refactoring auth module"

Restore Checkpoint

Restore files from a previous checkpoint.

/checkpoint/restore <checkpoint_id>

Parameters:

Parameter	Type	Description
`checkpoint_id`	str	ID of the checkpoint to restore

Example:

/checkpoint restore 20240115_143022_abc12345

List Checkpoints

List recent checkpoints.

/checkpoint/list [limit]

Parameters:

Parameter	Type	Default	Description
`limit`	int	20	Maximum number of checkpoints to return

Get Checkpoint Info

Get detailed information about a checkpoint.

/checkpoint/info <checkpoint_id>

Delete Checkpoint

Delete a checkpoint (removes metadata only, not Git history).

/checkpoint/delete <checkpoint_id>

Configuration

import { BaseAgent } from 'webagents';
import { CheckpointSkill } from 'webagents/skills/checkpoint';

const agent = new BaseAgent({
  name: 'my-agent',
  skills: [
    new CheckpointSkill({
      workDir: process.cwd(),
      maxCheckpoints: 50,
      excludePatterns: ['node_modules', '.git', 'dist', '.next'],
    }),
  ],
});

Auto-Checkpointing

The FilesystemSkill can be configured to automatically create checkpoints before file modifications:

// Coming soon — track at https://github.com/robutlerai/webagents/issues
// In TypeScript, manually call `checkpoint.create()` before destructive
// FilesystemSkill operations. There is no `setCheckpointManager` hook yet.

When enabled, a checkpoint is created before any write_file or replace operation.

API Endpoints

List Checkpoints

GET /agents/{name}/command/checkpoint/list

Create Checkpoint

POST /agents/{name}/command/checkpoint/create
Content-Type: application/json

{
  "description": "My checkpoint"
}

Restore Checkpoint

POST /agents/{name}/command/checkpoint/restore
Content-Type: application/json

{
  "checkpoint_id": "20240115_143022_abc12345"
}

Storage Structure

.webagents/
├── history/           # Git repository
│   ├── .git/
│   ├── .gitignore
│   └── (snapshotted files)
└── checkpoints/       # Checkpoint metadata
    ├── 20240115_143022_abc12345.json
    └── 20240115_150000_def67890.json

Each checkpoint JSON file contains:

{
  "checkpoint_id": "20240115_143022_abc12345",
  "created_at": "2024-01-15T14:30:22.123456",
  "description": "Before refactoring",
  "commit_hash": "abc123def456...",
  "files_changed": ["src/auth.py", "config.json"],
  "session_id": "uuid-of-session",
  "metadata": {}
}

On this page