copilot-token-optimizer

Token-optimized GitHub Copilot setup for multi-language projects (Node.js, Python, Java).

GitHub Copilot uses usage-based billing. This package scaffolds files, rules, and VS Code settings to help manage token consumption based on best practices and common optimization strategies.

⚡ Evolving Module — This package is under active development. Always use the latest version for bug fixes, new features, and improved token optimization strategies.

Check for updates: npm outdated -g copilot-token-optimizer or run npm install -g copilot-token-optimizer@latest

Problem

• Input context is a major cost driver — every Copilot request sends your open files as context
• Long chat sessions accumulate tokens — chat history grows with each exchange
• Most developers don't track token consumption — they discover costs in their bill
• No standard tooling exists for optimization — until now

Solution

This package scaffolds a token-optimized setup in one command:

npx copilot-token-optimizer init

Creates:

• ✅ .copilotignore — excludes node_modules, dist, *.lock, etc.
• ✅ .github/copilot-instructions.md — coding conventions (≤500 tokens)
• ✅ COPILOT.md — team guide with session rules & billing strategies
• ✅ .vscode/settings.json — model routing, context limits, cost controls

Result: Helps reduce token consumption through structured best practices.

Quick Start

Installation

npm install -g copilot-token-optimizer
# or
npx copilot-token-optimizer

Initialize a Project

cd my-project
npx copilot-token-optimizer init

Scaffolds token-optimized setup in .github/, creates .copilotignore, and configures VS Code.

Audit Your Setup

npx copilot-token-optimizer audit

Scores your project 0–100 and suggests improvements.

Manual Setup (if not using npm)

Copy the files from this repository into your project:

• .github/copilot-instructions.md → your project's .github/
• .copilotignore → project root
• COPILOT.md → project root
• .vscode/settings.json (merge the settings) → your project

Commands

init

Scaffold token-optimized setup.

npx copilot-token-optimizer init
npx copilot-token-optimizer init --agents          # Include AGENTS.md for agentic task routing
npx copilot-token-optimizer init --yes             # One-click non-interactive mode
npx copilot-token-optimizer init --dry-run         # Preview without writing
npx copilot-token-optimizer init --force           # Overwrite existing files

Supported stacks: nextjs, express-ts, nestjs, vite-react, python, java

Output:

• .copilotignore — Context exclusions
• .github/copilot-instructions.md — Repo-wide conventions
• COPILOT.md — Team guide
• .vscode/settings.json — Token-optimized settings (merged, not overwritten)

audit

Score your project's token efficiency.

npx copilot-token-optimizer audit
npx copilot-token-optimizer audit --fail-threshold=85    # Custom exit threshold for CI

Scoring rubric (0–100):

• +20 pts: .copilotignore present
• +15 pts: Standard ignores (node_modules, dist, *.lock)
• +20 pts: copilot-instructions.md ≤ 500 tokens
• +15 pts: .vscode/settings.json configured
• +10 pts: Output constraints in instructions (concise, brief, max N lines)
• +10 pts: MCP servers ≤ 3 enabled, no generic tools detected
• +5 pts: Instructions written in English
• +5 pts: COPILOT.md present

Exit code: 0 if score meets threshold (default: 70), 1 if below (useful for CI). Use --fail-threshold=N to customize the pass threshold.

compress

Compress markdown instruction files (prompts, conventions) to reduce token cost.

npx copilot-token-optimizer compress --file=.github/copilot-instructions.md
npx copilot-token-optimizer compress --file=.github/prompts/new-feature.prompt.md --level=full
npx copilot-token-optimizer compress --file=COPILOT.md --out=preview.md          # Preview only
npx copilot-token-optimizer compress --file=.github/prompts/debug.prompt.md --apply  # Apply

Compression levels:

• lite — Conservative compression (removes obvious filler, keeps professional tone)
• full — Standard compression (default; removes structure words, compresses descriptions)
• ultra — Aggressive compression (converts prose to pseudo-code, may reduce clarity)

Modes:

• Default (no flags) → Preview first 500 chars in console
• --out=file.md → Write compressed version to separate file for review
• --apply → Overwrite original file with compressed version

What it does:

• Removes ~40 filler word patterns per level (and, but, or, the, a, etc.)
• Converts passive voice → active voice ("is written by X" → "X writes")
• Converts descriptions → type signatures ("takes userId and returns User" → "userId → User")
• Preserves YAML frontmatter (applyTo, description metadata)
• Estimates token reduction: (original_length - compressed_length) / 4

Example usage:

.github/copilot-instructions.md:
  Before: 500 tokens → After: 350 tokens

.github/prompts/new-feature.prompt.md:
  Before: 200 tokens → After: 100 tokens

Typical workflow:

# 1. Audit current score
npx copilot-token-optimizer audit

# 2. Preview compression of a file
npx copilot-token-optimizer compress --file=.github/prompts/new-feature.prompt.md

# 3. Review the preview, then apply if satisfied
npx copilot-token-optimizer compress --file=.github/prompts/new-feature.prompt.md --apply

# 4. Verify score improved
npx copilot-token-optimizer audit

rollback

Restore Copilot files from a backup.

npx copilot-token-optimizer rollback --list          # Show available backups
npx copilot-token-optimizer rollback --timestamp=... # Restore from backup

Output:

Found 3 backup(s):

1. Timestamp: 2026-06-08T14-50-26-121
   Reason: 💾 Before merge
   Created: 6/8/2026, 2:50:26 PM
   Files: .copilotignore, .github/copilot-instructions.md, .vscode/settings.json

2. Timestamp: 2026-06-08T14-49-15-498
   Reason: 🔄 Safety backup (before restore)
   Created: 6/8/2026, 2:49:15 PM
   Files: .copilotignore, .github/copilot-instructions.md, .vscode/settings.json

End-User Guide: Token Optimization Best Practices

The Problem

GitHub Copilot charges per token. Common cost drivers include:

• Large files sent as context with every request
• Chat history accumulation over long sessions
• Unused features consuming tokens silently

Token Optimization Strategies

1. Exclude Large Files

Every open file is sent with every Copilot request.

❌ WITHOUT optimization:
   node_modules/ (50,000+ files)
   dist/ (compiled code)
   *.lock files (1,000+ lines each)
   → Large context sent with every request

✅ WITH .copilotignore:
   Same files SKIPPED
   → Smaller context per request

2. Path-Specific Instructions

Load rules only when editing relevant code.

✅ Base instructions sent always
✅ frontend.instructions.md loaded ONLY in src/components/
✅ api.instructions.md loaded ONLY in src/api/
= Reduced context when focused on specific code areas

3. Session Discipline

Structured interactions can be more efficient than long chat histories.

❌ Long chat sessions:
   - History grows with each exchange
   - Context expands exponentially
   - Tokens consumed throughout session

✅ Structured prompts:
   1. Copy template: new-feature.prompt.md
   2. Fill [SLOTS]: requirements, acceptance criteria
   3. Paste into Copilot (single request)
   = Self-contained, predictable token usage

Quick Start (5 Minutes)

# 1. Initialize your project
cd my-project
npx copilot-token-optimizer init

# 2. Verify setup
npx copilot-token-optimizer audit

# 3. Commit and share with team
git add .copilotignore .github/ COPILOT.md .vscode/settings.json
git commit -m "chore: add token-optimized Copilot setup"
git push

What gets created:

• ✅ .copilotignore — excludes node_modules, dist, locks
• ✅ .github/copilot-instructions.md — project conventions (≤500 tokens)
• ✅ COPILOT.md — team guide with best practices
• ✅ .vscode/settings.json — Copilot configuration

Measuring Impact

Use the audit command to score your setup (0–100):

npx copilot-token-optimizer audit

The audit checks whether you have in place:

Daily Habits for Efficient Token Use

✅ DO THIS:

• Use Ctrl+I (inline edit) for small changes instead of chat
• Close chat periodically (prevents history accumulation)
• One topic per chat session (focused conversations)
• Review .copilotignore regularly for stale patterns
• Use efficient models for different tasks
• Scope selection carefully (fewer open files = smaller context)

❌ AVOID THIS:

• Keeping chat open continuously
• Using the same model for all tasks
• Keeping many editor tabs open
• Rambling, unfocused chat sessions

Weekly Checklist

# Check your setup hasn't drifted
npx copilot-token-optimizer audit

# Check GitHub billing
# Visit: github.com → Settings → Billing → Copilot Usage

Monthly Checklist

• ☐ Audit copilot-instructions.md for stale rules (should be <500 tokens)
• ☐ Review Copilot settings and disable unused features
• ☐ Disable unused MCP servers from Copilot CLI config
• ☐ Run npx copilot-token-optimizer audit (track score trends)

Rollback If Needed

# See all backups
npx copilot-token-optimizer rollback --list

# Restore from a backup
npx copilot-token-optimizer rollback --timestamp=2026-06-08T14-50-26-121

Files Scaffolded

.copilotignore

Excludes large and noisy files from Copilot context:

node_modules/
dist/
build/
.next/
*.lock
*.min.js
coverage/
generated/

Why: Large files sent as input with every request add significant context overhead.

.github/copilot-instructions.md

Project-wide coding conventions (≤500 tokens). Injected into every Copilot request.

Includes:

• Naming conventions (camelCase, PascalCase, UPPER_SNAKE_CASE)
• Code style (arrow functions, const/let, JSDoc)
• What NOT to generate (secrets, raw SQL, hardcoding)
• Testing requirements
• Git conventions

Why: Keeping this file lean prevents context bloat.

COPILOT.md

Team guide (NOT loaded by Copilot — for humans). Includes:

• Session discipline rules (one topic, close every 25 min, max 8 exchanges)
• Model routing (use mini for simple tasks, GPT-4o for complex, o3 for hard problems)
• Monthly billing checklist
• Troubleshooting guide
• Weekly & monthly maintenance tasks

.vscode/settings.json

Token-optimized VS Code settings (merged without overwriting user keys):

{
  "github.copilot.advanced.length": 4000,
  "github.copilot.chat.indexing.enabled": false,
  "github.copilot.chat.scopeSelection": true,
  "github.copilot.chat.useProjectTemplates": false,
  "github.copilot.chat.followUps": "never",
  "github.copilot.renameSuggestions.triggerAutomatically": false,
  "github.copilot.chat.reviewSelection.enabled": false,
  "github.copilot.enable": {
    "*": true,
    "markdown": false,
    "plaintext": false,
    "yaml": false,
    "json": false
  }
}

Why:

• Limits context to 4,000 tokens (prevents bloat)
• Disables chat indexing (saves storage & costs)
• Enables scoped selection (better context targeting)
• Disables auto templates (prevents unnecessary context)
• Disables auto follow-up questions (they re-load context)
• Disables rename suggestions auto-trigger (saves AI Credits)
• Disables code review auto-trigger (saves AI Credits)
• Excludes non-code files (markdown, JSON, YAML have no Copilot value)

Developer choice: Model selection (chat vs. inline) is left to you per task — see COPILOT.md for guidance on which model to use when.

How This Package Works

This package provides automation, best practices, and auditing tools. The actual token consumption will depend on your project structure and team practices.

Provides:

• Automated scaffolding of optimization files
• Audit scoring based on best practices (0–100)
• Compression tooling for markdown files
• Templates and examples

Does NOT provide:

• Automatic token accounting or billing management
• Enforcement of team habits (e.g., chat session limits)
• Modifications to Copilot's built-in behaviors beyond settings
• Guaranteed cost reductions (depends on actual usage patterns)

Usage Examples

Example 1: Start a New Next.js Project

# Create Next.js app
npx create-next-app my-app
cd my-app

# Initialize Copilot setup
npx copilot-token-optimizer init

# Verify
ls -la .github/          # Should have copilot-instructions.md, instructions/
cat .copilotignore      # Standard ignores
cat COPILOT.md          # Team guide

Example 2: Audit an Existing Express + TypeScript Project

cd my-api
npx copilot-token-optimizer audit

# Output:
# Score: 45/100
# ❌ .copilotignore: missing
# ✅ copilot-instructions.md: present (250 tokens)
# ✅ VS Code settings: configured
# ❌ COPILOT.md: missing
#
# Recommended fixes:
# 1. Run: npx copilot-token-optimizer init --force

Manual Setup Checklist

One-Time Setup

• [ ] Run npx copilot-token-optimizer init or manually copy files
• [ ] Apply VS Code settings from Section 6 of plan.md
• [ ] Go to github.com → Settings → Billing → Copilot → set monthly spending cap
• [ ] Disable auto code review on PR (if enabled)
• [ ] Share COPILOT.md with your team in the next standup

Daily Habits

• [ ] One topic per Copilot chat session
• [ ] Close and reopen chat every ~25 minutes
• [ ] Keep max 5 editor tabs open
• [ ] Choose the cheapest model that can answer your question
• [ ] Use Ctrl+I (inline edit) for small changes instead of chat

Weekly Habits

• [ ] Check GitHub billing dashboard for per-model breakdown
• [ ] Disable any MCP servers not actively in use
• [ ] Run npx copilot-token-optimizer audit — check your score

Monthly Habits

• [ ] Audit copilot-instructions.md — trim anything over 500 tokens
• [ ] Run npx copilot-token-optimizer update — pull latest templates
• [ ] Review .copilotignore — add any new generated directories

Requirements

• Node.js: 18.x or higher (uses native fetch, fs/promises)
• npm: 7.x or higher (or yarn, pnpm)

Roadmap

| Phase | Version | Status | Deliverables | |---|---|---|---| | Phase 1 | v0.1 | ✅ Released | Init command, base templates, .copilotignore, settings writer | | Phase 2 | v0.1.1 | ✅ Released | Stack auto-detect and overrides for Node, Python, Java | | Phase 3 | v0.1.1 | ✅ Released | Audit command, token counter, bloat detector, scoring gate | | Phase 4 | v0.1.1 | ✅ Released | Update command, CI audit integration, AGENTS.md support |

FAQ

Q: Will this work on existing projects? A: Yes. Run npx copilot-token-optimizer init --force to overwrite existing files. Back up customizations first.

Q: Can I modify the instruction files after init? A: Yes. They're just markdown files in your repo. Copilot will use your customized versions.

Q: Does this guarantee lower costs? A: No. This sets up the right defaults and best practices, but developers must also follow session discipline rules in COPILOT.md. The audit tool helps measure your setup quality.

Q: What if my stack isn't detected? A: Pass --stack=stackname to force it. In non-interactive mode, use --yes to skip prompts and apply base setup automatically.

Q: Can I use this with GitHub Copilot for Business / Enterprise? A: Yes. The same token optimization rules apply at the account level.

Q: What about team collaboration? Can we share instructions? A: Yes. Commit .github/copilot-instructions.md and instruction files to your repo. They apply to all developers on the project.

Contributing

See CONTRIBUTING.md for development setup and testing.

License

MIT — see LICENSE for details.

Changelog

See CHANGELOG.md for release notes.

Support

• 📖 Documentation: See COPILOT.md in your project after running init
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Made with ❤️ to help developers control AI costs.

Last Updated: June 2026