Sókrates Wiki

Claude Code Plugin Scoping and Token Optimization

2 min read

Claude Code Plugin Scoping and Token Optimization

Summary

This architectural decision establishes a “conservative global, opt-in per project” strategy for Claude Code plugins to minimize token consumption. By restricting the global configuration to a barebones set of universally applicable tools and offloading specialized plugins to project-level settings, the system reduces context window overhead by approximately 2.3k to 2.9k tokens per session.

Details

The optimization addresses the issue of “dead weight” skills—plugin-provided capabilities that are loaded into every conversation regardless of their relevance to the current codebase. In a default configuration, loading ~45 skills across 12 plugins consumes nearly 3,000 tokens of the context window before a user even sends a prompt.

Scoping Strategy

The project follows Strategy A: Conservative Global, Opt-in Per Project. This approach layers configuration files to ensure that only necessary tools are active.

Global Configuration (~/.claude/settings.json)

The global settings file is restricted to a “barebones” list of plugins that are useful across all Sokrates development contexts:

  • superpowers: General reasoning and brainstorming.
  • remember: Context persistence.
  • claude-md-management: Documentation and wiki handling.
  • github: Repository interactions.

All other plugins (e.g., astral, plugin-dev, skill-creator, hookify, linear, claude-code-setup) are explicitly disabled at the global level to prevent them from consuming tokens in unrelated projects.

Project-Level Configuration (.claude/settings.local.json)

Specific projects override the global defaults by enabling plugins relevant to their tech stack. For example, the sokrates-website project (a Next.js landing page) enables:

  • frontend-design
  • chrome-devtools-mcp

Plugins like astral (Python-specific) or plugin-dev (used only when building new Claude Code plugins) remain disabled for this project, saving significant token space.

Enforcement and Hooks

To ensure developers maintain this scoping discipline, a SessionStart hook is configured in the global settings. This hook executes a shell script, check-project-plugins.sh, which performs the following:

  1. Checks for the existence of enabledPlugins within the local .claude/settings.local.json.
  2. If missing, it issues a warning to the terminal: “No enabledPlugins in .claude/settings.local.json — using global barebones only.”
  3. Lists available plugins that the user might want to opt into for that specific project.

Token Impact

Analysis of the plugin descriptions revealed that disabling irrelevant plugins provides substantial savings:

  • astral: ~115 tokens (3 skills).
  • plugin-dev: ~1.6k tokens (6 skills + 3 agents).
  • hookify: ~435 tokens (4 skills + 1 agent).
  • skill-creator: ~87 tokens (1 skill).

By moving these to project-specific scopes, the baseline context window for a standard session is significantly expanded, allowing for more complex reasoning and larger code ingestion.

Graph View