🚀 Copilot Token Optimizer

Keep GitHub Copilot focused on the task in front of it

Cut your Copilot working-context footprint by up to 90% by keeping the always-on instructions lean and routing deep documentation only when it is relevant.

The Problem

Teams often let .github/copilot-instructions.md grow into a dump of architecture notes, completed tasks, debugging journals, and one-off decisions. Even when Copilot can technically search the workspace on demand, bloated instruction files and sprawling reference docs still create noisy context, weaker answers, and less room for the code that matters now.

In one real project, the documentation footprint had drifted to 11,000 tokens before any new task-specific context was added.

The Solution

@edixos/copilot-token-optimizer keeps the working set small and intentional:

• One lean .github/copilot-instructions.md file for always-on guidance
• Three high-signal core references in .github/
• Topic files in docs/learnings/ that you pull in only when a task needs them
• Historical material archived out of the default path

Typical result: 11,000 → 1,300 tokens for the docs you keep in active Copilot context. That is roughly a 90% reduction.

Token estimates use a GPT-family tokenizer so the numbers track modern Copilot models much more closely than Claude-specific tooling.

Quick Setup

Option A — no install:

npx @edixos/copilot-token-optimizer init

Option B — one-line install with global cpto:

curl -fsSL https://raw.githubusercontent.com/edixos/copilot-token-optimizer/main/install.sh | bash
cpto init

Option C — npm global:

npm install -g @edixos/copilot-token-optimizer
cpto init

Measure first if you want a before/after estimate:

npx @edixos/copilot-token-optimizer measure
# or
cpto measure

What It Creates

your-project/
├── .github/
│   ├── copilot-instructions.md   # Always-on project instructions
│   ├── COMMON_MISTAKES.md        # Critical failure modes
│   ├── QUICK_START.md            # Commands and daily workflows
│   ├── ARCHITECTURE_MAP.md       # File and feature map
│   ├── instructions/             # Path-specific *.instructions.md files
│   ├── completions/              # Completed task notes
│   ├── sessions/                 # Session logs and snapshots
│   └── templates/                # Reusable doc templates
├── .copilotignore                # Excludes archives and low-signal docs
└── docs/
    ├── INDEX.md                  # Navigation + token guidance
    ├── learnings/                # Deep-dive topics, loaded on demand
    └── archive/                  # Historical docs, never in default context

How It Works

The optimizer is built around one rule: keep the default Copilot context small, and make everything else easy to discover.

Recommended working set:

.github/copilot-instructions.md   ~450 tokens
.github/COMMON_MISTAKES.md       ~350 tokens
.github/QUICK_START.md           ~100 tokens
.github/ARCHITECTURE_MAP.md      ~150 tokens
---------------------------------------------
Default working set               ~800 tokens

Then load only the topic docs you need:

• API work: docs/learnings/api-design.md
• Testing work: docs/learnings/testing-patterns.md
• Performance work: docs/learnings/performance.md

That usually keeps a real task around 1,300 tokens instead of dragging the entire documentation history into every Copilot chat.

Framework-Aware Setup

cpto init auto-detects these frameworks from repo metadata and applies the right ignore patterns:

• express
• nextjs
• vue
• nuxtjs
• angular
• django
• rails
• nestjs
• laravel
• fastapi
• go
• spring-boot
• svelte

Override detection when needed:

cpto init --framework nextjs
cpto init --framework django
cpto init --framework go

Framework-specific setup prompts live in examples/README.md.

Workflow After Setup

1. Keep .github/copilot-instructions.md short. It should explain where deeper knowledge lives, not duplicate it.
2. Put recurring mistakes in .github/COMMON_MISTAKES.md.
3. Put commands and daily workflows in .github/QUICK_START.md.
4. Put file layout and architectural landmarks in .github/ARCHITECTURE_MAP.md.
5. Move durable topic knowledge into docs/learnings/.
6. Archive finished work into .github/completions/, .github/sessions/archive/, and docs/archive/.

CLI Reference

| Command | Description | |---------|-------------| | cpto init | Create the Copilot-optimized documentation structure | | cpto measure | Estimate the current documentation context footprint | | cpto audit | Validate structure, token health, and ignore coverage | | cpto compress | Deterministically reduce .github/copilot-instructions.md size | | cpto prune | Remove stale sections from .github/copilot-instructions.md | | cpto diff | Compare a file against its .bak token backup | | cpto watch | Live token dashboard for the core working set | | cpto hooks | Install and manage helper-script templates | | cpto update | Update the CLI or refresh project content |

Ongoing Maintenance

cpto audit
cpto compress
cpto prune
cpto diff

CI Example

cpto audit --json

Without a global install:

npx @edixos/copilot-token-optimizer audit --json

Helper Scripts

GitHub Copilot does not expose a native CLI hook settings file. Instead, cpto hooks installs optional helper scripts into .github/scripts/copilot-hooks/ and prints a JSON manifest you can wire into VS Code tasks, shell wrappers, or CI.

Available Templates

templates/hooks/
├── pre-tool-token-guard.sh
├── pre-tool-read-guard.sh
├── pre-tool-bash-guard.sh
├── post-write-token-diff.sh
├── session-end-token-report.sh
├── user-prompt-inject-context.sh
├── user-prompt-inject-snapshot.sh
├── user-prompt-validate-copilot-instructions.sh
├── user-prompt-ghost-scanner.sh
├── user-prompt-optimize.sh
├── stop-session-snapshot.sh
├── stop-path-guard.sh
└── notification-token-display.sh

Install Them

cpto hooks install --all
cpto hooks settings

The settings command prints a machine-readable manifest of installed scripts and the bash .github/hooks/... command to run for each event group.

Useful Helper Scripts

• pre-tool-token-guard.sh warns when the measured working set gets too large.
• user-prompt-inject-context.sh matches user prompts to files in docs/learnings/ and prints a lightweight context payload you can pipe into wrappers.
• user-prompt-optimize.sh is an optional prompt compressor for wrapper-based setups. It stays off by default, only runs when CPTO_PROMPT_OPTIMIZER_ENABLED=1, and can emit plain text or JSON depending on CPTO_PROMPT_OPTIMIZER_OUTPUT_FORMAT.
• post-write-token-diff.sh records write sizes in .copilot/sessions/write-log.md.

Optional Prompt Compression

user-prompt-optimize.sh is the only helper script in this package that reaches out to an external model. That makes it useful for teams that want prompt normalization and skill routing, but it should stay disabled unless you explicitly want that tradeoff.

The hook discovers skill candidates dynamically from local skill manifests and workspace signals. You can point it at custom skill files with CPTO_PROMPT_OPTIMIZER_SKILLS_FILE or CPTO_PROMPT_OPTIMIZER_SKILLS_DIRS, and it will fall back to project-derived hints if no manifests are present.

Enable it only when needed:

CPTO_PROMPT_OPTIMIZER_ENABLED=1
CPTO_PROMPT_OPTIMIZER_API_KEY=...

By default it emits plain text so it fits normal prompt-hook pipelines. Set CPTO_PROMPT_OPTIMIZER_OUTPUT_FORMAT=json only if you are wrapping it yourself.

Its logs are compact and structured:

• .copilot-runtime/prompt-optimizer.ndjson stores one record per run with hashes, counts, selected skills, and a Copilot-equivalent AI-credit estimate.
• .copilot-runtime/prompt-optimizer-daily.ndjson keeps the rolling daily aggregate.
• .copilot-runtime/prompt-optimizer-daily.md renders the daily aggregate in a readable table.

The AI-credit estimate uses the official GitHub Copilot model pricing table. Token counts are estimated from the prompt text unless your wrapper provides more precise usage data. Set CPTO_PROMPT_OPTIMIZER_CREDIT_MODEL if you want to estimate against a different Copilot model.

FAQ

Is cpto init safe on an existing repo?

Yes. If .github/copilot-instructions.md already exists, cpto init appends only missing optimizer sections unless you pass --force.

Does this only work with Copilot?

The structure is generic markdown and shell scripts, but the generated instruction file and tokenizer defaults are tuned for GitHub Copilot workflows.

Why .github/copilot-instructions.md instead of COPILOT.md?

Because .github/copilot-instructions.md matches GitHub Copilot’s standard instruction-file convention.

What if my project already has too much documentation?

Run cpto measure, move long-lived knowledge into docs/learnings/, archive historical material, then use cpto compress and cpto prune to keep the main instruction file tight.

Contributing

Framework additions, docs improvements, CLI fixes, and helper-script improvements are all welcome. See CONTRIBUTING.md.

Need Help?

• Bug: open an issue
• Discussion: start a discussion

License

MIT