Context - ProcessWire Module

Export your ProcessWire site structure as AI-optimized context for ChatGPT, Claude, and other AI assistants.

Author: Maxim Semenov
Website: smnv.org
Email: maxim@smnv.org

If this project helps your work, consider supporting future development: GitHub Sponsors or smnv.org/sponsor.

Context automatically generates comprehensive documentation of your ProcessWire site in formats optimized for AI assistants. Export in both JSON (standard) and TOON (AI-optimized) formats.

Perfect for:

• Working with AI coding assistants (Claude, ChatGPT, Copilot)
• Reducing AI API costs with token-efficient TOON format
• Onboarding new developers
• Site migrations and documentation
• Rapid development with AI pair programming
• Maintaining consistent code standards

• JSON Format - Standard format for APIs, development tools, and compatibility
• TOON Format - Token-Oriented Object Notation for AI assistants
  • 30-60% fewer tokens than JSON
  • Significantly reduces API costs for Claude, ChatGPT, etc.
  • Better for large datasets in AI prompts
  • Lossless conversion - same data, smaller size

• Site Structure - JSON/TOON and ASCII tree visualization of entire page hierarchy
• Templates & Fields - Complete template definitions with field types, options, and configurations
• Configuration - ProcessWire version, PHP settings, installed modules
• Custom Classes - Automatic detection of custom Page classes from /site/classes/
• Frontend Stack - Auto-detects Alpine.js, Tailwind CSS, UIkit, and other frameworks
• ProFields Support - Special handling for Repeater Matrix field types (if installed)

• Content Samples - Export real page examples for each template (JSON + TOON)
• API Documentation - Generate JSON schemas for REST API development
• Code Snippets - Customized selector patterns and helper functions
• AI Prompts - Ready-to-use context prompts for AI assistants
• Performance Metrics - Site statistics and performance data
• IDE Integration - Generate .cursorrules and .claudecode.json files

Code snippets are automatically customized for your site type:

• Generic / Mixed Content - General purpose patterns
• Blog / News / Magazine - Posts, authors, categories, archives
• E-commerce / Online Store - Products, cart, orders, inventory
• Business / Portfolio / Agency - Services, team, projects, testimonials
• Catalog / Directory / Listings - Brands, categories, hierarchical data

• ProcessWire 3.0 or higher
• PHP 8.2 or higher
• Write permissions for /site/assets/cache/context/ directory, or for your configured export path
• No external dependencies required - pure PHP implementation

• Squad integration — reuse Squad's encrypted provider keys, default provider, and selected model without duplicating credentials
• Direct-provider fallback — retain OpenRouter, OpenAI, and custom OpenAI-compatible connections for sites that do not use Squad
• Shared gateway — any ProcessWire module can use the AI connection via wire('context')->ai()
• Simple API — $ai->complete($prompt) for quick calls, $ai->chat($options) for full control
• Global system prompt — set once in module settings, applied to all AI requests
• OpenAI-compatible — works with OpenAI directly or any compatible self-hosted endpoint

cd /site/modules/
git clone https://github.com/mxmsmnv/Context.git

Then refresh modules in admin and install.

1. Download the module from the ProcessWire Modules Directory
2. Place files in /site/modules/Context/
3. In ProcessWire admin: Modules → Refresh
4. Click Install next to "Context"

Setup → Modules → Context → Configure

1. Choose your site type (Blog, E-commerce, Business, Catalog, or Generic)
2. Enable TOON format - Export TOON Format (AI-Optimized) - Recommended!
3. Enable optional features you need:
   • Export Content Samples
   • Generate API Documentation
   • Create Code Snippets
   • Create AI Prompts
4. Set samples per template (1-10)
5. Enable auto-update if you want automatic exports on template/field changes

Click "Re-Export Context for AI" or visit:

/processwire/module/?name=Context

Files are generated in: /site/assets/cache/context/ by default.

Upload these files to your AI assistant:

For AI Development (Recommended - Use TOON):

• structure.toon - Complete page hierarchy (30-60% smaller!)
• templates.toon - All templates and fields (optimized)
• config.toon - Site configuration
• prompts/project-context.md - Complete project overview

For Development Tools (Use JSON):

• structure.json - Standard JSON format
• templates.json - For IDE plugins
• classes.json - Custom Page classes

Example prompt:

I've uploaded my ProcessWire site context in TOON format. 
Please help me create a new template for blog posts with 
title, body, author, and categories fields. Follow the 
existing patterns in templates.toon.

/site/assets/cache/context/
├── README.md                      # Documentation with format guide
├── SKILL.md                       # AI agent skill definition (for Cline, Junie, etc.)
├── tree.json                      # Complete site structure (templates + fields + pages)
├── tree.toon                      # Complete site structure (TOON - AI optimized!)
├── structure.json                 # Page tree (JSON)
├── structure.toon                 # Page tree (TOON - AI optimized!)
├── structure.txt                  # ASCII tree visualization
├── templates.json                 # Templates (JSON)
├── templates.toon                 # Templates (TOON - AI optimized!)
├── templates.csv                  # Templates in CSV
├── matrix-templates.json          # Repeater Matrix types (ProFields) - if installed
├── matrix-templates.toon          # Repeater Matrix types (TOON) - if installed
├── config.json                    # Configuration (JSON)
├── config.toon                    # Configuration (TOON)
├── modules.json                   # Installed modules (JSON)
├── modules.toon                   # Installed modules (TOON)
├── classes.json                   # Custom page classes (JSON)
├── classes.toon                   # Custom page classes (TOON)
│
├── samples/                       # Content examples (optional)
│   ├── product-samples.json
│   └── product-samples.toon       # AI-optimized samples!
├── api/                           # API schemas (optional)
├── snippets/                      # Code library (optional)
├── prompts/                       # Prompt templates for manual use (optional)
│   ├── project-context.md         # Main project prompt
│   ├── create-template.md         # Template creation guide
│   ├── create-api.md              # API creation guide
│   ├── debug-issue.md             # Debugging helper
│   └── project-summary.md         # Session continuity template
└── metadata/                      # Technical data (optional)

Tip: When uploading to AI, use .toon files to save tokens and reduce API costs!

TOON (Token-Oriented Object Notation) is a compact, human-readable format designed specifically for AI prompts. It represents the same data as JSON but uses 30-60% fewer tokens.

JSON (120 tokens):

{
  "products": [
    {
      "id": 1045,
      "title": "Dark Chocolate 70%",
      "price": 12.99,
      "category": "Dark"
    },
    {
      "id": 1046,
      "title": "Milk Hazelnut",
      "price": 9.99,
      "category": "Milk"
    }
  ]
}

TOON (65 tokens - 46% savings!):

products[2]{id,title,price,category}:
1045,Dark Chocolate 70%,12.99,Dark
1046,Milk Hazelnut,9.99,Milk

Use TOON (.toon) for:

• Uploading to Claude, ChatGPT, or other AI assistants
• Large datasets in AI prompts
• Reducing API costs
• AI code generation

Use JSON (.json) for:

• API endpoints
• Development tools (PhpStorm, VSCode plugins)
• Third-party integrations
• Standard ProcessWire development

• VS Code / Cursor: Install "TOON Language Support" extension for syntax highlighting
• PhpStorm: Use YAML syntax highlighting (similar appearance)
• AI Assistants: Upload directly - they understand TOON natively
• Text Editors: Plain text - fully readable by humans

# Upload to Claude/ChatGPT (TOON format):
- structure.toon
- templates.toon
- samples/product-samples.toon

# Then ask:
"Create a product filter with price range, category, and brand 
using the patterns from my site structure"

Result: Same quality response, but using 40% fewer tokens!

Share the exported context folder with new team members. By default this is /site/assets/cache/context/. They get:

• Complete site structure overview (both formats)
• All templates and field definitions
• Code examples and patterns
• Custom Page classes documentation

# Upload (JSON format for technical work):
- api/schemas/product-schema.json
- snippets/api-examples.php

# Ask:
"Create a REST API endpoint for products with search and filtering"

# For big projects with lots of data:
- Use TOON format to fit more context in AI's window
- 100 products in JSON = ~15,000 tokens
- 100 products in TOON = ~7,000 tokens
- Difference: You can include 2x more examples!

Real savings example:

Your site: 50 templates, 500 pages to document

JSON export: ~85,000 tokens
TOON export: ~42,000 tokens
Savings: 43,000 tokens per prompt

With Claude Sonnet ($3 per million input tokens):
- JSON cost: $0.255 per prompt
- TOON cost: $0.126 per prompt
- Savings: $0.129 per prompt

If you use 100 prompts/month: Save ~$13/month
If you use 1000 prompts/month: Save ~$130/month

Enable Auto-Update on Changes to automatically regenerate context when you:

• Create or modify templates
• Add or modify fields
• Change template-field assignments

Hooks into:

• Templates::saved
• Fields::saved
• Fieldgroups::saveReady

Auto-update exports both JSON and TOON formats if TOON export is enabled.

1. Always include prompts/project-context.md - contains system instructions
2. For token efficiency - use .toon files instead of .json
3. For field questions - include templates.toon
4. For site structure - include structure.toon or structure.txt
5. For coding - include snippets/selectors.php
6. For debugging - include relevant samples/*-samples.toon

• Small tasks (1-3 files): Upload .toon files to chat directly
• Medium tasks (3-10 files): Core .toon files + specific sections
• Large projects: Use Claude Projects with entire /context/ folder
• Development tools: Use .json files with IDEs and APIs

• After adding/modifying templates
• After adding/modifying fields
• After changing site structure
• After changing Site Type setting
• Before major development sessions
• When you want to update TOON files with latest data

• Export TOON Format (AI-Optimized) - Generate .toon files alongside .json

  • Enabled by default
  • Saves 30-60% tokens
  • Perfect for AI development

• Generate SKILL.md for AI Agents - Auto-create skill definition file

  • Enabled by default
  • For Cline, Junie, and other AI coding agents
  • Describes available resources and usage examples
  • Follows Cline/MCP skill format specification

Choose your site type to get customized code snippets:

• Generic / Mixed Content
• Blog / News / Magazine
• E-commerce / Online Store
• Business / Portfolio / Agency
• Catalog / Directory / Listings

• Export Content Samples - Include real page examples (JSON + TOON)
• Samples Per Template - How many examples (1-10)
• Generate API Documentation - Create JSON schemas
• Export URL Routes - URL segment configurations
• Export Performance Metrics - Site statistics
• Create Code Snippets - PHP examples customized for site type
• Create AI Prompts - Ready-to-use prompts

• Maximum Tree Depth - Page tree depth limit (3-20)
• JSON Children Limit - Max children per page (5-100)
• Compact Mode - Collapse large lists
• Auto-Update on Changes - Auto-export on template/field save
• Create IDE Integration Files - .cursorrules, .claudecode.json
• Custom AI Instructions - Project-specific AI instructions

• ProcessWire 3.x
• PHP 8.1 or higher
• Write permissions for /site/assets/cache/context/, or for your configured export path

• Export typically takes 1-3 seconds
• TOON conversion adds < 0.5s overhead
• Uses ProcessWire's caching where possible
• Auto-update hooks are lightweight (< 50ms)

• Default path protected by ProcessWire - site/assets/cache/context/ blocked in root .htaccess (Apache)
• Absolute paths supported - Use /home/user/context-exports/ to store files outside web root (recommended for Nginx)
• Triple protection system:
  1. ProcessWire native protection for /site/assets/cache/ (Apache only)
  2. Local .htaccess auto-created as backup (Apache only)
  3. Absolute paths outside web root (works on both Apache and Nginx)
• Configurable export path - Set custom location in module settings
• No sensitive data exported - No passwords, API keys, or credentials
• Restricted admin access - Module actions require superuser access or the dedicated context-admin permission

Server-Specific Setup:

Apache (HestiaCP, cPanel, etc.):

• Default path site/assets/cache/context/ works out of the box
• ProcessWire .htaccess + local .htaccess provide protection

Nginx (CloudPanel, etc.):

• Use absolute path outside web root: /home/user/context-exports/
• Or add to nginx config:

  location ~ ^/site/assets/cache/context/ {
      deny all;
      return 403;
  }

Important: Update to v1.1.6+ for proper security. Versions < 1.1.6 used unprotected site/assets/context/ path.

• Pure PHP implementation - no external dependencies
• Lossless conversion - no data loss
• Deterministic output - same input = same output
• Handles all JSON data types
• Special optimization for uniform arrays (tables)

• Module: /site/modules/Context/
• Exports (default): /site/assets/cache/context/ (ProcessWire protected, Apache only)
• Exports (Nginx): /home/user/context-exports/ (absolute path, outside web root - recommended)
• Protection: ProcessWire root .htaccess + local .htaccess (Apache) OR absolute path (Nginx)
• Snippets Library: /site/modules/Context/src/ContextSnippets.php
• TOON Serializer: /site/modules/Context/src/ContextToon.php
• Sample Serializer: /site/modules/Context/src/ContextSampleSerializer.php
• Sample Exporter: /site/modules/Context/src/ContextSampleExporter.php
• API Exporter: /site/modules/Context/src/ContextApiExporter.php
• Metadata Exporter: /site/modules/Context/src/ContextMetadataExporter.php
• Prompt Exporter: /site/modules/Context/src/ContextPromptExporter.php
• Prompt Templates: /site/modules/Context/src/ContextPromptTemplates.php
• Integration Exporter: /site/modules/Context/src/ContextIntegrationExporter.php
• System Exporter: /site/modules/Context/src/ContextSystemExporter.php
• Docs Exporter: /site/modules/Context/src/ContextDocsExporter.php
• Archive Downloader: /site/modules/Context/src/ContextArchiveDownloader.php
• Admin Actions: /site/modules/Context/src/ContextAdminActions.php
• AI Test Action: /site/modules/Context/src/ContextAiTestAction.php
• Export Format Helper: /site/modules/Context/src/ContextExportFormats.php
• Frontend Detector: /site/modules/Context/src/ContextFrontendDetector.php
• Site Inspector: /site/modules/Context/src/ContextSiteInspector.php
• Web Helper: /site/modules/Context/src/ContextWebHelper.php
• CLI Runner: /site/modules/Context/src/ContextCli.php
• Auto Updater: /site/modules/Context/src/ContextAutoUpdater.php
• Filesystem Helper: /site/modules/Context/src/ContextFilesystem.php
• Structure Exporter: /site/modules/Context/src/ContextStructureExporter.php
• Template Exporter: /site/modules/Context/src/ContextTemplateExporter.php
• Custom paths: Configure in Setup → Modules → Context → Export Path
  • site/assets/cache/context/ - default, ProcessWire protected (Apache)
  • /home/user/context-exports/ - absolute path outside web root (Apache + Nginx)
  • .junie/skills/docs - for Junie AI integration
  • ../../context-exports/ - relative path (two levels up)
  • Unsafe targets such as the site root, assets root, cache root, templates folder, and module folder are blocked.

When TOON export is enabled, the module admin page shows a comparison table:

This helps you see the actual token/cost savings for your specific site!

Q: Do I need to install any external libraries for TOON support?
A: No! TOON conversion is built-in with pure PHP. No Composer packages or external dependencies required.

Q: Is TOON format lossless?
A: Yes! TOON contains exactly the same data as JSON, just in a more compact format. You can convert back and forth without any data loss.

Q: Which AI assistants support TOON?
A: Claude, ChatGPT, and most modern LLMs understand TOON natively. Just upload the .toon file as you would a .json file.

Q: Can I use both JSON and TOON formats?
A: Absolutely! Both formats are generated simultaneously. Use JSON for development tools and APIs, TOON for AI assistants.

Q: How much does TOON actually save?
A: Typically 30-60% fewer tokens. The exact savings depend on your data structure - uniform arrays see the biggest gains (up to 60%).

Q: Does TOON export slow down my site?
A: No. Export happens on-demand when you click the button, not on every page load. The TOON conversion adds < 0.5s to the export time.

Q: What if I disable TOON format later?
A: No problem! Simply uncheck "Export TOON Format" in settings. Your next export will only generate JSON files.

Q: Can I edit TOON files manually?
A: Yes, TOON files are plain text and human-readable. However, it's easier to make changes in ProcessWire and re-export.

Q: Are there any file size limits?
A: TOON files follow the same limits as JSON. Both are text files with no artificial size restrictions.

Q: How do I view TOON files?
A: TOON files are plain text. Use any text editor. For syntax highlighting: VS Code/Cursor (install "TOON Language Support" extension) or PhpStorm (use YAML highlighting).

Q: Export failed with "permission denied"
A: Ensure /site/assets/ directory is writable by your web server user. Check file permissions (755 or 775).

Q: TOON files not being created
A: Check that "Export TOON Format" is enabled in module settings and you've clicked "Re-Export Context for AI" after enabling it.

Q: AI assistant doesn't understand my TOON file
A: TOON is plain text - just upload it as you would any text file. Make sure the file has a .toon extension.

SKILL.md Auto-Generation

The module automatically generates SKILL.md for AI coding agents. This file helps agents understand how to use your ProcessWire context.

Setup for Cline (PHPStorm/VSCode):

1. Set export path to .agents/skills/context/
2. Enable "Generate SKILL.md for AI Agents"
3. Re-export Context
4. Cline will auto-discover the skill

Setup for Junie (PHPStorm):

1. Set export path to .junie/skills/docs/
2. Enable "Generate SKILL.md for AI Agents"
3. Re-export Context
4. Junie will use the context in your coding sessions

Problem: AI agents don't remember previous sessions. Each new session starts from scratch.

Solution: Create a project checkpoint file at the end of each coding session.

Prompt template (suggested by @psy):

Create a structured project checkpoint summary.

Output MUST follow this exact format and headings. Use short bullet points only. No paragraphs.

## Project
(one line description)

## Current State
- ...

## Decisions Made
- ...

## Known Issues
- ...

## What We Tried
- ...

## Constraints
- ...

## Next Steps
1.
2.
3.

## Do NOT Do
- ...

Rules:
- Be concise and factual
- Do not explain reasoning unless critical
- Do not invent anything not discussed
- Prefer clarity over completeness

Save this as: [your-export-path]/prompts/project-summary.md
Overwrite the file.
Do not add any extra commentary outside the file contents.

Workflow:

1. Work on your project with AI agent
2. Before closing: Ask AI to create checkpoint using the template above
3. AI saves prompts/project-summary.md
4. Next session: AI reads Context exports + project-summary.md
5. AI understands where you left off and continues seamlessly

Why this works:

• Context module provides site structure
• project-summary.md provides session context
• Together they give AI complete picture of your project state

When working with AI assistants:

• Upload .toon files instead of .json for 30-60% token savings
• Upload SKILL.md first so AI understands available resources
• Upload specific files as needed (templates.toon, structure.toon, etc.)
• Include project-summary.md for session continuity

MIT License - see LICENSE file for details

Maxim Semenov

• Website: smnv.org
• Email: maxim@smnv.org
• GitHub: @mxmsmnv