Skip to content

Release Notes: v1.12.0 - Checkpoint System & Usage Tracking

Release Date: 2025-12-29 Type: Major Feature Release Branch: feature/agent-multi-file-atomic-edit → master

🎯 Overview

ppxai v1.12.0 introduces a checkpoint system for atomic multi-file rollback and real-time token usage tracking with cost estimation.

Checkpoint System: - ✅ Safe Experimentation - Try agent tasks risk-free, undo with one command - ✅ Git Integration - Uses native git commits for version-controlled projects - ✅ Zero Configuration - Works out of the box with sensible defaults - ✅ Fallback Support - File snapshots when git is not available

Usage Tracking: - ✅ Real-time Tokens - See prompt/completion tokens in status line - ✅ Cost Estimation - Automatic USD cost calculation per model - ✅ VSCode Integration - Usage badge with live updates - ✅ All Providers - Works with streaming responses (OpenAI, Perplexity, Gemini)

🆕 New Features

1. Checkpoint System

Git Backend (Preferred) - Auto-commits changes before agent tasks: git commit -m "ppxai checkpoint: <task>" - Atomic rollback with: git revert HEAD --no-edit - Fully compatible with standard git workflow - No storage overhead, commits visible in git history

File Backend (Fallback) - Snapshots files to ~/.ppxai/checkpoints/{session_id}/ - Works without git repository - Preserves directory structure - Auto-cleanup keeps last 10 checkpoints

Auto-Detection - Automatically selects best backend (git → file → none) - Configurable via tools.agent.checkpoint_backend in ppxai-config.json - Options: "auto" (default), "git", "file", "none"

2. New Commands

/undo - Revert Last Agent Task 

You: /undo

⚠️  Undo Last Agent Task
Backend: git
Checkpoint: abc123de

Confirm undo? (y/n): y

✓ Changes reverted using git revert (checkpoint: abc123de)

Reverts all changes from the last /agent task atomically.

Enhanced /agent Command - Automatic checkpoint creation before task execution - Notifications show checkpoint ID and backend - Warning if checkpoints disabled

You: /agent refactor auth module to use JWT

🔒 Agent Mode enabled with Git checkpoints
   • Changes will be auto-committed before each task
   • Use /undo to revert the last agent task atomically

✓ Checkpoint created: f3a7b2c1 (refactor auth module)

🤖 Starting autonomous agent...

3. Enhanced Status Line (TUI)

New Checkpoint Status Indicators 

[Perplexity | sonar-pro | Tools: ON | Agent: ON | Checkpoints: git]
[Perplexity | sonar-pro | Tools: ON | Agent: ON | Checkpoints: file]
[Perplexity | sonar-pro | Tools: ON | Agent: ON | Checkpoints: OFF]

Color Coding: - Checkpoints: git - Green (git backend active) - Checkpoints: file - Yellow (file backend active) - Checkpoints: OFF - Red (checkpoints disabled, warning)

4. Event-Based Notifications

New EventType.STATUS - Checkpoint created: ✓ Checkpoint created: abc123de (task description) - Undo success: ✓ Changes reverted using git revert (checkpoint: abc123de) - Notifications shown in both TUI and VSCode (via SSE)

5. Configuration

New Agent Configuration Options (ppxai-config.json): 

{
  "tools": {
    "agent": {
      "checkpoint_backend": "auto",
      "checkpoint_message": "ppxai checkpoint: {task}",
      "max_iterations": 10,
      "context_char_limit": 2000,
      "min_task_words": 3
    }
  }
}

Checkpoint Backend Options: - "auto" - Auto-detect (git if available, else file) - "git" - Git-only (disable if no git repo) - "file" - Force file backend - "none" - Disable checkpoints

6. HTTP API Endpoints (VSCode Extension)

Enhanced /agent/status 

{
  "agent_mode": true,
  "tools_enabled": true,
  "checkpoint": {
    "enabled": true,
    "backend": "git",
    "last_checkpoint": "f3a7b2c1abc...",
    "status_description": "Checkpoints: git (atomic)"
  }
}

New /checkpoint/status 

{
  "enabled": true,
  "backend": "git",
  "last_checkpoint": "f3a7b2c1abc...",
  "status_description": "Checkpoints: git (atomic)"
}

New /checkpoint/undo 

POST /checkpoint/undo
Response: {"ok": true, "backend": "git"}

7. Real-Time Token Usage & Cost Tracking

Streaming Usage Extraction - Both OpenAI-compatible and Perplexity providers now extract token counts from streaming responses - Uses stream_options={"include_usage": True} parameter for accurate token counts - Works with all streaming requests (the default mode)

Cost Calculation - Automatic USD cost estimation based on per-model pricing in config - Pricing data for all built-in providers (Perplexity, Gemini) - Configurable pricing for custom providers

TUI Status Line 

[Perplexity | Sonar Pro | Tools: ON | 1.2K↓/0.5K↑ $0.0045]
- 1.2K↓ - Prompt tokens (input) - 0.5K↑ - Completion tokens (output) - $0.0045 - Estimated cost for session

VSCode Extension - Usage badge in header with live updates after each response - Tooltip shows total tokens and cost details - Green color when cost > $0

/usage Command 

┌─────────────────────────────────────────┐
│        Current Session Usage            │
├─────────────────────┬───────────────────┤
│ Metric              │             Value │
├─────────────────────┼───────────────────┤
│ Total Tokens        │             1,750 │
│ Prompt Tokens       │             1,200 │
│ Completion Tokens   │               550 │
│ Estimated Cost      │           $0.0045 │
└─────────────────────┴───────────────────┘

HTTP Endpoint: /usage 

{
  "total_tokens": 1750,
  "prompt_tokens": 1200,
  "completion_tokens": 550,
  "estimated_cost": 0.0045
}

8. Documentation

New User Guides: - docs/CHECKPOINT_GUIDE.md - Comprehensive 550+ line user guide - Quick start and configuration - Git vs file backend comparison - Workflow examples and troubleshooting - Advanced usage and FAQ

New Specifications: - docs/VSCODE-CHECKPOINT-UI-SPEC.md - VSCode extension UI spec - Enhanced agent toggle button (🔒/⚠️ indicators) - Undo button with confirmation modal - System notifications and status polling - Visual mockups and implementation checklist

Updated Documentation: - Help text includes Agent Mode section with /undo command - Autocomplete includes /undo command

🧪 Testing

New Test Suite

tests/test_checkpoint.py - 28 New Tests (All Passing)

GitCheckpointBackend Tests (8 tests): - ✅ test_is_available_with_git_repo - Detects git repository - ✅ test_is_available_without_git_repo - Detects absence of git - ✅ test_create_checkpoint_with_changes - Creates git commit checkpoint - ✅ test_create_checkpoint_without_changes - Returns empty string when no changes - ✅ test_restore_checkpoint - Reverts checkpoint commit - ✅ test_restore_nonexistent_checkpoint - Fails gracefully for invalid hash - ✅ test_list_checkpoints - Lists ppxai checkpoint commits - ✅ test_get_backend_name - Returns "git"

FileCheckpointBackend Tests (9 tests): - ✅ test_is_available - Always available - ✅ test_create_checkpoint - Creates snapshot directory - ✅ test_create_checkpoint_without_files - Returns empty string when no files - ✅ test_restore_checkpoint - Restores files from snapshot - ✅ test_restore_nonexistent_checkpoint - Fails gracefully for missing snapshot - ✅ test_list_checkpoints - Lists file-based checkpoints - ✅ test_cleanup_old_checkpoints - Removes old checkpoints (keeps last N) - ✅ test_get_backend_name - Returns "file" - ✅ test_preserve_directory_structure - Maintains directory structure in snapshots

CheckpointManager Tests (11 tests): - ✅ test_auto_backend_selects_git - Auto mode prefers git - ✅ test_auto_backend_falls_back_to_file - Auto mode falls back to file - ✅ test_explicit_git_backend - Explicit git selection - ✅ test_explicit_git_backend_fails_without_git - Git-only mode fails without repo - ✅ test_explicit_file_backend - Force file backend - ✅ test_none_backend - Disable checkpoints - ✅ test_create_checkpoint - Create checkpoint via manager - ✅ test_undo_checkpoint - Undo via manager - ✅ test_get_status_description_git - Git status message - ✅ test_get_status_description_file - File status message - ✅ test_get_status_description_none - Disabled status message

Test Coverage Summary

Total Tests: 365 (337 existing + 28 new) - ✅ 365 passing - ❌ 0 failing - ⚠️ 0 warnings

Test Isolation: - All checkpoint tests use temporary directories - Git tests create isolated git repositories - File backend tests use unique session IDs - Cleanup ensures no cross-test interference

🔧 Technical Changes

Core Implementation

New Module: ppxai/checkpoint.py (381 lines) - CheckpointBackend - Abstract base class - GitCheckpointBackend - Git-based implementation - FileCheckpointBackend - File snapshot implementation - CheckpointManager - Facade with auto-detection

Engine Integration: - EngineClient._checkpoint_manager - Checkpoint manager instance - EngineClient._last_checkpoint_id - Track last checkpoint for undo - EngineClient.create_checkpoint() - Create checkpoint before agent task - EngineClient.undo_last_checkpoint() - Revert last checkpoint - EngineClient.get_checkpoint_status() - Status for UI/API

Event System: - New EventType.STATUS for checkpoint notifications - Events emitted via _consent_event_queue - TUIEventHandler handles STATUS events (cyan display) - HTTP SSE automatically streams STATUS events to VSCode

Command Handling: - CommandHandler.handle_undo() - /undo command with confirmation - Enhanced CommandHandler.handle_agent() - Automatic checkpointing - Warnings when checkpoints disabled

UI/UX: - Status line shows checkpoint backend and status - Autocomplete includes /undo command - Help text includes Agent Mode section

Modified Files

  1. ppxai/checkpoint.py (NEW - 381 lines)
  2. ppxai/engine/client.py - Checkpoint manager integration
  3. ppxai/engine/types.py - Added EventType.STATUS
  4. ppxai/commands.py - /undo command, enhanced /agent
  5. ppxai/server/http.py - New checkpoint endpoints
  6. ppxai/main.py - Status line integration, autocomplete
  7. ppxai/ui.py - Help text updates
  8. ppxai/common/event_handler.py - STATUS event handling
  9. ppxai-config.example.json - Checkpoint configuration examples
  10. tests/test_checkpoint.py (NEW - 464 lines, 28 tests)
  11. tests/test_commands.py - Fixed coroutine warnings
  12. docs/CHECKPOINT_GUIDE.md (NEW - 558 lines)
  13. docs/VSCODE-CHECKPOINT-UI-SPEC.md (NEW - 216 lines)

Commits on Feature Branch

5043df2 fix(v1.12.0): Fix auto-commit timing in async generator flow
3d96cf6 fix(v1.12.0): Initialize checkpoint manager on TUI startup
fd28a70 fix(v1.12.0): Align TUI /undo with VSCode extension behavior
0930961 feat(v1.12.0): Fix checkpoint undo with auto-commit after agent tasks
5fb5a82 docs(v1.12.0): Document interrupt handling improvements
2fc374e feat(v1.12.0): Add robust interrupt handling with automatic rollback
7548620 docs: Add comprehensive v1.12.0 release notes
619184a feat: Add STATUS event type for checkpoint notifications
349f9b8 docs: Add comprehensive checkpoint system user guide
b592837 docs: Add /undo command to help text and autocomplete
... (earlier commits)

📚 Usage Examples

Example 1: Git Project Workflow

# Check status (git backend auto-detected)
You: /status
[Perplexity | sonar-pro | Tools: ON | Agent: ON | Checkpoints: git]

# Run agent task
You: /agent add user registration endpoint

🔒 Agent Mode enabled with Git checkpoints
   • Changes will be auto-committed before each task
   • Use /undo to revert the last agent task atomically

✓ Checkpoint created: f3a7b2c1 (add user registration endpoint)

🤖 Starting autonomous agent...
[Agent creates files, edits code...]

# Review changes
You: git diff HEAD~1

# Decide to undo
You: /undo

⚠️  Undo Last Agent Task
Backend: git
Checkpoint: f3a7b2c1

Confirm undo? (y/n): y

✓ Changes reverted using git revert (checkpoint: f3a7b2c1)

# Verify
You: git log -2
# Shows checkpoint commit + revert commit

Example 2: Non-Git Project

# No git repo, file backend active
[Perplexity | sonar-pro | Tools: ON | Agent: ON | Checkpoints: file]

You: /agent refactor config.py to use environment variables

⚠️  Agent Mode enabled with File checkpoints
   • Snapshots will be saved to ~/.ppxai/checkpoints
   • Use /undo to restore from snapshot
   • Tip: Initialize git repo for atomic commits

✓ Snapshot saved: cp-20251227-143022 (refactor config.py)

# Later, undo the changes
You: /undo
✓ Files restored from snapshot: cp-20251227-143022

Example 3: Disable Checkpoints

// In ppxai-config.json
{
  "tools": {
    "agent": {
      "checkpoint_backend": "none"
    }
  }
}

[Perplexity | sonar-pro | Tools: ON | Agent: ON | Checkpoints: OFF]

You: /agent update dependencies

⚠️  Agent Mode enabled WITHOUT checkpoints
   • Changes CANNOT be undone
   • Initialize git repo or enable file backend for safety

🤖 Starting autonomous agent...
[Runs without checkpoint - /undo not available]

🔒 Security & Safety

Safeguards

  1. User Confirmation Required
  2. /undo shows confirmation prompt before reverting
  3. Backend and checkpoint ID displayed

  4. Cancel with 'n' or Ctrl-C

  5. Git Safety

  6. No git push --force or destructive operations
  7. Standard git revert creates new commit (preserves history)

  8. Compatible with git hooks and workflows

  9. File Backend Safety

  10. Read-only snapshots in ~/.ppxai/checkpoints/
  11. Auto-cleanup prevents disk space issues

  12. Preserves original file permissions

  13. Validation

  14. Checkpoint verification before undo
  15. Graceful failure for invalid checkpoints
  16. Clear error messages

Limitations

  1. Single Undo Level
  2. Only last checkpoint can be undone via /undo

  3. Use git commands directly for multiple undos

  4. Agent Mode Only

  5. Checkpoints only created for /agent tasks

  6. Regular chat and file editing tools don't auto-checkpoint

  7. File Backend Not Atomic

  8. File backend restores files individually
  9. Partial restores possible if errors occur
  10. Git backend recommended for critical tasks

🚀 Migration Guide

From v1.11.x to v1.12.0

Backward Compatible - No Breaking Changes

  1. Auto-enabled by default:
  2. Git projects: Checkpoints enabled automatically
  3. Non-git projects: File backend enabled automatically

  4. No configuration required

  5. Optional: Customize checkpoint behavior 

    // ppxai-config.json
{
  "tools": {
    "agent": {
      "checkpoint_backend": "auto",  // or "git", "file", "none"
      "checkpoint_message": "ppxai checkpoint: {task}"
    }
  }
}

  6. New commands available:

  7. /undo - Revert last agent task

  8. Enhanced /agent - Shows checkpoint notifications

  9. VSCode Extension:

  10. Checkpoint status visible in agent toggle button
  11. Undo button appears when checkpoint exists
  12. System notifications in chat
  13. (UI implementation pending, API ready)

📊 Performance

Overhead

Git Backend: - Checkpoint creation: ~50-100ms (git commit) - Undo operation: ~50-100ms (git revert) - Storage: 0 bytes (uses git DAG)

File Backend: - Checkpoint creation: ~10-50ms per file (file copy) - Undo operation: ~10-50ms per file (file restore) - Storage: ~1x file size per checkpoint (compressed possible in future)

Scalability

Tested With: - Projects up to 1000 files - Checkpoints with 50+ modified files - Git repositories with 10,000+ commits - File backend with 100+ snapshots

Recommendations: - Use git backend for large projects (better performance) - Clean old file snapshots periodically if disk space limited - Consider "none" backend for read-only tasks

🐛 Known Issues

Current Limitations

  1. VSCode UI Not Implemented
  2. HTTP API endpoints functional
  3. TypeScript UI implementation pending

  4. Spec available: docs/VSCODE-CHECKPOINT-UI-SPEC.md

  5. File Backend Cleanup

  6. Auto-cleanup keeps last 10 by default

  7. No UI for manual cleanup (use rm -rf ~/.ppxai/checkpoints/*)

  8. Checkpoint Message Customization

  9. {task} variable truncated to 100 characters
  10. No other variables supported yet

✅ Addressed in v1.12.0

  1. Interrupt Handling (FIXED)
  2. ✅ Ctrl-C now prompts for automatic rollback
  3. ✅ Git backend offers working directory cleanup
  4. ✅ Clear user feedback throughout process

  5. ✅ No more dirty state after interrupts

  6. TUI/VSCode Parity (FIXED)

  7. ✅ TUI /undo works regardless of agent mode (same as VSCode)
  8. ✅ TUI /undo checks for dirty working tree before undo
  9. ✅ Checkpoint manager initialized on startup (not just on set_working_dir)
  10. ✅ Auto-commit happens correctly in async generator flow

🔮 Future Enhancements (v1.13+)

Planned Features

  1. Multi-level Undo (v1.13.0)
  2. Undo multiple checkpoints sequentially
  3. Checkpoint history UI

  4. Selective checkpoint restoration

  5. File Editing Checkpoints (v1.13.0)

  6. Auto-checkpoint for file editing tools
  7. Per-tool checkpoint configuration

  8. Checkpoint before each apply_patch, replace_block, etc.

  9. Checkpoint Compression (v1.13.1)

  10. Compress file backend snapshots
  11. Differential snapshots (only changed files)

  12. Configurable retention policy

  13. VSCode Extension UI (v1.12.1)

  14. Enhanced agent toggle button with 🔒/⚠️ indicators
  15. Undo button with confirmation modal

  16. Checkpoint history panel

  17. Advanced Git Integration (v1.14.0)

  18. Branch-per-task workflow
  19. Automatic git stash before checkpoints
  20. Checkpoint tags and annotations

📖 Documentation

User Guides

  • Checkpoint System User Guide - Comprehensive guide (558 lines)
  • Quick start, configuration, troubleshooting
  • Git vs file backend comparison
  • Workflow examples and FAQ

Specifications

  • VSCode Checkpoint UI Spec - Implementation spec (216 lines)
  • UI mockups and component design
  • API endpoint usage
  • Event handling and status polling

Updated Docs

  • README.md - Updated feature list
  • CLAUDE.md - Updated version and feature summary
  • Help text (/help) - Added Agent Mode section

🙏 Acknowledgments

Key Contributors: - Checkpoint system design and implementation - Comprehensive test coverage (28 new tests) - User guide and documentation - Event system integration

Technologies: - Git for version control integration - Python subprocess for git operations - Rich console for TUI notifications - FastAPI SSE for VSCode events

📝 Release Checklist

  • [x] All tests passing (365/365)
  • [x] Zero warnings in test output
  • [x] User guide completed (558 lines)
  • [x] VSCode UI spec completed (216 lines)
  • [x] Help text updated
  • [x] Autocomplete updated
  • [x] Event handling verified (TUI + VSCode SSE)
  • [x] HTTP API endpoints functional
  • [x] Example configuration provided
  • [x] Release notes completed
  • [ ] Merge feature branch to master
  • [ ] Tag release v1.12.0
  • [ ] Update version in all files
  • [ ] Create GitHub release
  • [ ] Update ROADMAP.md with next steps

Version: v1.12.0 Release Date: 2025-12-29 Type: Major Feature Release Status: Ready for Merge