Scito — Code Intent Governance

Track WHY code was changed, not just what changed.

Scito is a completely free VS Code extension that lets you seal critical code blocks with human-readable intent descriptions, AI agent instructions, and change history. Everything is stored locally in .scito/ledger.json and committed to Git — no server required.

Why Scito?

AI coding agents (Copilot, Cursor, Replit Agent) can modify your code — but they don't know why it was written that way. Scito gives them context before they make changes, preventing breaking changes to your most critical logic.

For developers: Document intent, track changes, get review reminders. For AI agents: Read sealed block data before modifying protected code.

Completely Free

All features are available to everyone. No limits, no tiers, no license keys.

How to Use Scito

1. Seal a Code Block

1. Open a project folder in VS Code
2. Select a block of important code
3. Press Ctrl+Shift+S (or Cmd+Shift+S on Mac)
4. Choose a template or write a custom intent description
5. Add AI agent instructions (what should an AI know before changing this?)
6. Optionally set a review reminder date
7. Done — the block is sealed and tracked

2. Browse Your Sealed Blocks

• Dashboard (Scito: Open Dashboard) — Interactive panel showing all sealed blocks organized by file, with status, tags, AI instructions, and quick navigation
• Statistics (Scito: View Statistics) — Risk distribution, file coverage, tag frequency, and recent activity
• Search (Scito: Search Blocks) — Find blocks by intent, file, tag, or owner

3. Track Changes Over Time

• Timeline (Scito: View Block Timeline) — Full history with before/after snapshot diffs
• Change Notes (Scito: Add Change Note) — Document why you modified a block, with risk level and what breaks
• Review Reminders (Scito: Review Reminders) — Get notified when block reviews are overdue

4. Share and Report

• Export / Import (Scito: Export Blocks / Scito: Import Blocks) — Share intent data between projects as JSON
• Audit Reports (Scito: Export Audit Report) — Generate a Markdown report of all sealed blocks

5. Protect Your Code

• Enforcement Mode — Require change notes when editing protected blocks. Enable scito.enforcementMode in settings.
• Git Pre-Commit Hook (Scito: Install Git Pre-Commit Hook) — Warn before committing changes to protected blocks.

Block Templates

8 built-in templates for common patterns. Each includes default intent, AI instructions, risk level, and tags:

How AI Agents Can Use Scito

Scito stores all data in .scito/ledger.json at the project root. AI agents should read this file before modifying any code.

Reading the Ledger

The ledger is a JSON file with this structure:

{
  "version": 1,
  "blocks": [
    {
      "id": "blk_abc123def456",
      "filePath": "src/billing/tax.ts",
      "startLine": 42,
      "endLine": 58,
      "protected": true,
      "intent": "Calculates tax based on region-specific rules",
      "agentInstructions": "Do not simplify — the extra checks handle edge cases for EU VAT compliance",
      "tags": ["billing", "tax", "compliance"],
      "template": "Payment / Billing",
      "reviewBy": "2026-06-01T00:00:00.000Z",
      "lastText": "function calculateTax(...) { ... }",
      "createdAt": "2026-02-14T10:30:00.000Z",
      "history": [
        {
          "timestamp": "2026-02-14T10:30:00.000Z",
          "action": "sealed",
          "note": "Calculates tax based on region-specific rules",
          "snapshotAfter": "function calculateTax(...) { ... }",
          "metadata": {
            "riskLevel": "critical",
            "whatBreaks": "Incorrect tax charges, compliance violations",
            "owner": "@alice"
          }
        }
      ]
    }
  ]
}

What AI Agents Should Do

1. Before modifying a file, check if any blocks in the ledger cover lines in that file
2. Read the intent to understand why the code exists
3. Read agentInstructions for specific guidance on what to preserve
4. Check riskLevel — critical and high-risk blocks should not be modified without explicit user approval
5. Read whatBreaks to understand the consequences of incorrect changes
6. If changes are made, update the ledger with a new history entry documenting what changed and why

Writing to the Ledger

AI agents can add history entries when they modify sealed code:

{
  "timestamp": "2026-02-14T14:00:00.000Z",
  "action": "note_added",
  "note": "Refactored to use new tax API endpoint",
  "snapshotBefore": "// old code...",
  "snapshotAfter": "// new code...",
  "metadata": {
    "riskLevel": "high",
    "whatBreaks": "Tax calculations if API format changes"
  }
}

Cloud API Sync (Optional)

For platforms that want real-time access to Scito data, an optional API sync is available. Configure with Scito: Configure API Connection. This syncs sealed blocks to a cloud endpoint that AI agents can query over HTTP.

All Commands

Keyboard Shortcuts

Settings

How Data Is Stored

Scito creates a .scito/ folder in your project with a ledger.json file. This file stores all sealed blocks, their intents, history, and protection status.

Commit this file to Git. When another developer (or AI agent) clones the repo, they automatically see all sealed blocks, intents, and history — no setup needed.

License

See LICENSE file for details.