---
title: Checkpoint Skill
description: File-system snapshots for agent working directories — Git-backed in Python, content-hashed in TypeScript.
---

# 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](../../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:**

```bash
/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:**

```bash
/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

```typescript tab="TypeScript"
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'],
    }),
  ],
});
```

```yaml tab="Python"
# Enable via AGENT.md front-matter
---
name: my-agent
skills:
  - checkpoint
  - filesystem  # Required for file operations
---
```

## Auto-Checkpointing

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

```typescript tab="TypeScript"
// 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.
```

```python tab="Python"
filesystem_skill.set_checkpoint_manager(checkpoint_manager)
```

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

## API Endpoints

### List Checkpoints

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

### Create Checkpoint

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

{
  "description": "My checkpoint"
}
```

### Restore Checkpoint

```http
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:

```json
{
  "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": {}
}
```
