Context Wrangler 🚦

Automated context-length hygiene • Multi-model AI prompt generator • Git-to-Road-map sync

Works with any Git repo – Node ≥18 (ESM).
Optional Python-only runner available (.ctx/python_variant/).
Supports GitHub Actions, GitLab CI, or plain shell hooks.

1 Why & When

Large projects bleed tokens in AI chat sessions:

• long diffs & logs pasted verbatim
• forgotten decisions resurfacing months later
• vague prompts (“remember that thing we did?”)

Context Wrangler enforces a light, machine-curated memory:

2 Installation (5 min)

# 1 — unpack boilerplate
unzip context-boilerplate.zip -d .

# 2 — install the toolkit’s dependencies
pnpm --filter .ctx install     # or:  npm i --workspace=.ctx
# optional Python-only path:
# pip install -r .ctx/python_variant/requirements.txt

# 3 — register Husky hooks (if you want local gating)
npx husky install
echo 'pnpm ctx snapshot' > .husky/post-merge
chmod +x .husky/post-merge

# 4 — export secrets once (or add to CI/CD vars)
# See .env.template for a full list and examples
cp .env.template .env
# Open .env and fill in your API keys

3 CLI Reference

Add --help to any verb for flags.

4 Configuration (.ctx/ctx.config.yaml)

This file is the central hub for configuring Context Wrangler.

Environment variables always override YAML.

# Generic Context Wrangler configuration
PROJECT_SLUG: ${PROJECT_SLUG}
DEFAULT_AI_MODEL: openai:gpt-4o # Default model for commands
SNAPSHOT_TAG_PREFIX: ctx-snap-
TOKEN_LIMIT: 16000
PRUNE_DAYS: 30

MODELS: # Configure AI Providers and their API keys/base URLs
  openai:
    API_KEY_ENV: OPENAI_API_KEY
    BASE_URL: [https://api.openai.com/v1](https://api.openai.com/v1)
  cohere:
    API_KEY_ENV: COHERE_API_KEY
    BASE_URL: [https://api.cohere.ai/v1](https://api.cohere.ai/v1)
  mistral:
    API_KEY_ENV: MISTRAL_API_KEY
    BASE_URL: [https://api.mistral.ai/v1](https://api.mistral.ai/v1)
  gemini:
    API_KEY_ENV: GOOGLE_API_KEY
    # BASE_URL is typically not needed for GoogleGenerativeAI SDK as it's handled internally
  perplexity:
    API_KEY_ENV: PERPLEXITY_API_KEY
    BASE_URL: [https://api.perplexity.ai](https://api.perplexity.ai)
  together:
    API_KEY_ENV: TOGETHER_API_KEY
    BASE_URL: [https://api.together.xyz](https://api.together.xyz)
  grok: # Conceptual integration
    API_KEY_ENV: GROK_API_KEY
    BASE_URL: [https://api.grok.com](https://api.grok.com)
  deepseek: # Conceptual integration
    API_KEY_ENV: DEEPSEEK_API_KEY
    BASE_URL: [https://api.deepseek.com](https://api.deepseek.com)
  anthropic: # Conceptual integration (already had some basic support)
    API_KEY_ENV: ANTHROPIC_API_KEY
    BASE_URL: [https://api.anthropic.com](https://api.anthropic.com)

MODEL_SETTINGS: # Fine-tune AI parameters per model per command
  # OpenAI Models
  openai:gpt-4o:
    snapshot_max_tokens: 700
    snapshot_temperature: 0.15
    prune_max_tokens: 150
    prune_temperature: 0.05
  openai:gpt-4-turbo:
    snapshot_max_tokens: 1000
    snapshot_temperature: 0.1
    prune_max_tokens: 200
    prune_temperature: 0.05
  openai:gpt-3.5-turbo:
    snapshot_max_tokens: 512
    snapshot_temperature: 0.2
    prune_max_tokens: 120
    prune_temperature: 0.1

  # Cohere Models
  cohere:command-r-plus:
    snapshot_max_tokens: 1500
    snapshot_temperature: 0.2
    prune_max_tokens: 250
    prune_temperature: 0.1
  cohere:command-r:
    snapshot_max_tokens: 1000
    snapshot_temperature: 0.3
    prune_max_tokens: 180
    prune_temperature: 0.15
  cohere:command:
    snapshot_max_tokens: 800
    snapshot_temperature: 0.4
    prune_max_tokens: 160
    prune_temperature: 0.2

  # Mistral AI Models
  mistral:mistral-large-latest:
    snapshot_max_tokens: 1000
    snapshot_temperature: 0.2
    prune_max_tokens: 200
    prune_temperature: 0.1
  mistral:mixtral-8x7b-instruct-v0.1:
    snapshot_max_tokens: 700
    snapshot_temperature: 0.3
    prune_max_tokens: 150
    prune_temperature: 0.15
  mistral:mistral-small-latest:
    snapshot_max_tokens: 500
    snapshot_temperature: 0.4
    prune_max_tokens: 100
    prune_temperature: 0.2

  # Google Gemini Models
  gemini:gemini-1.5-flash:
    snapshot_max_tokens: 800
    snapshot_temperature: 0.4
    prune_max_tokens: 160
    prune_temperature: 0.2
  gemini:gemini-1.5-pro:
    snapshot_max_tokens: 1200
    snapshot_temperature: 0.3
    prune_max_tokens: 200
    prune_temperature: 0.15

  # Perplexity AI Models (Conceptual)
  perplexity:llama-2-70b-chat:
    snapshot_max_tokens: 700
    snapshot_temperature: 0.5
    prune_max_tokens: 150
    prune_temperature: 0.25
  perplexity:mixtral-8x7b-instruct:
    snapshot_max_tokens: 700
    snapshot_temperature: 0.5
    prune_max_tokens: 150
    prune_temperature: 0.25

  # Together AI Models (Conceptual, often hosts Llama, Mistral, etc.)
  together:llama-3-8b-instruct:
    snapshot_max_tokens: 700
    snapshot_temperature: 0.5
    prune_max_tokens: 150
    prune_temperature: 0.25
  together:mistral-7b-instruct:
    snapshot_max_tokens: 600
    snapshot_temperature: 0.4
    prune_max_tokens: 120
    prune_temperature: 0.2

  # Grok Models (Conceptual)
  grok:grok-1:
    snapshot_max_tokens: 700
    snapshot_temperature: 0.5
    prune_max_tokens: 180
    prune_temperature: 0.3

  # DeepSeek Models (Conceptual)
  deepseek:deepseek-coder:
    snapshot_max_tokens: 600
    snapshot_temperature: 0.4
    prune_max_tokens: 140
    prune_temperature: 0.2

  # Anthropic Models (Conceptual)
  anthropic:claude-3-sonnet-20240229:
    snapshot_max_tokens: 1024
    snapshot_temperature: 0.3
    prune_max_tokens: 150
    prune_temperature: 0.15

5 Supported AI Models

Context Wrangler is designed to be extensively multi-model. Currently, it has direct integration and configuration for:

• OpenAI: gpt-4o, gpt-4-turbo, gpt-3.5-turbo
• Cohere: command-r-plus, command-r, command
• Mistral AI: mistral-large-latest, mistral-medium-latest, mistral-small-latest, mixtral-8x7b-instruct-v0.1
• Google Gemini: gemini-1.5-flash, gemini-1.5-pro

Conceptual integration (placeholders for future direct SDK integration or routing via platforms like Together AI) exists for:

• Perplexity AI: llama-2-70b-chat, mixtral-8x7b-instruct
• Together AI: llama-3-8b-instruct, mistral-7b-instruct (many other models available via Together)
• Grok: grok-1
• DeepSeek: deepseek-coder
• Anthropic (Claude): claude-3-sonnet-20240229, claude-3-haiku-20240307 (already had basic support, now more explicitly configured)
• Other models: The architecture allows for easy addition of more models from various providers by creating new client classes and updating config.js.

Adding More Models

To add support for other models:

1. Install their SDK: Add the relevant npm package to .ctx/package.json (e.g., @google/generative-ai, perplexity-sdk, together-ai).
2. Create a client file: Create a new file in .ctx/src/lib/aiClients/ (e.g., gemini.js, perplexity.js, together.js) that extends AIClient and implements the getCompletion method using the new SDK.
3. Update .ctx/src/lib/aiClient.js:
   • Import your new client class.
   • Add a case statement in the AIClient.create method to handle your new provider and use the correct API key from process.env.
4. Update .ctx/ctx.config.yaml:
   • Add a new entry under the MODELS section for the new provider, specifying API_KEY_ENV and BASE_URL (if applicable).
   • Add entries under MODEL_SETTINGS for each specific model you want to configure, defining snapshot_max_tokens, snapshot_temperature, prune_max_tokens, prune_temperature, and any other model-specific parameters.
5. Update .env.template: Add a placeholder for the new API key.

6 CI/CD Recipes

GitHub Actions (.github/workflows/context.yml)

name: Context Wrangler

on:
  push:
    branches: [ main ]
  schedule:
    - cron: "0 3 * * *"   # nightly prune

jobs:
  update_context:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with: { version: 8 }
      - name: Install dependencies
        run: pnpm install --filter .ctx
      - name: Build snapshot and sync kanban
        run: |
          pnpm ctx snapshot --model ${{ secrets.SNAPSHOT_MODEL || 'openai:gpt-4o' }}
          pnpm ctx kanban-sync
        env:
          # Ensure all necessary API keys are passed as secrets
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}
          MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}
          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
          PERPLEXITY_API_KEY: ${{ secrets.PERPLEXITY_API_KEY }}
          TOGETHER_API_KEY: ${{ secrets.TOGETHER_API_KEY }}
          GROK_API_KEY: ${{ secrets.GROK_API_KEY }}
          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GH_TOKEN: ${{ secrets.GH_TOKEN }}
          GH_OWNER: your-org
          GH_REPO:  your-repo
          PROJECT_SLUG: your-project-slug # Ensure this is set
      - name: Prune old chat logs
        run: pnpm ctx prune --model ${{ secrets.PRUNE_MODEL || 'openai:gpt-4o' }} --days 60
        env:
          # Ensure all necessary API keys are passed as secrets
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}
          MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}
          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
          PERPLEXITY_API_KEY: ${{ secrets.PERPLEXITY_API_KEY }}
          TOGETHER_API_KEY: ${{ secrets.TOGETHER_API_KEY }}
          GROK_API_KEY: ${{ secrets.GROK_API_KEY }}
          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      - name: Commit and Push changes
        run: |
          git config user.name  "context-bot"
          git config user.email "bot@users.noreply.github.com"
          git add docs/. chat-archive/. # Include chat-archive if pruning changes it
          git commit -m "chore: automated context update" || echo "No changes to commit"
          git push

GitLab CI (.gitlab-ci.yml)

stages:
  - snapshot
  - prune

.install_deps:
  before_script:
    - pnpm --filter .ctx install

snapshot:
  stage: snapshot
  extends: .install_deps
  script:
    - pnpm ctx snapshot --model ${SNAPSHOT_MODEL:-openai:gpt-4o}
    - git add docs/
    - git commit -m "ci: ctx snapshot" || true
    - git push
  variables:
    # Ensure all necessary API keys are passed as variables
    OPENAI_API_KEY: $OPENAI_API_KEY
    COHERE_API_KEY: $COHERE_API_KEY
    MISTRAL_API_KEY: $MISTRAL_API_KEY
    GOOGLE_API_KEY: $GOOGLE_API_KEY
    PERPLEXITY_API_KEY: $PERPLEXITY_API_KEY
    TOGETHER_API_KEY: $TOGETHER_API_KEY
    GROK_API_KEY: $GROK_API_KEY
    DEEPSEEK_API_KEY: $DEEPSEEK_API_KEY
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
    PROJECT_SLUG: $CI_PROJECT_NAME # Example, adjust as needed

prune:
  stage: prune
  extends: .install_deps
  rules:
    - when: schedule # Run only on schedule (e.g., nightly)
  script:
    - pnpm ctx prune --days 60 --model ${PRUNE_MODEL:-openai:gpt-4o}
    - git add chat-archive/
    - git commit -m "ci: prune chats" || true
    - git push
  variables:
    # Ensure all necessary API keys are passed as variables
    OPENAI_API_KEY: $OPENAI_API_KEY
    COHERE_API_KEY: $COHERE_API_KEY
    MISTRAL_API_KEY: $MISTRAL_API_KEY
    GOOGLE_API_KEY: $GOOGLE_API_KEY
    PERPLEXITY_API_KEY: $PERPLEXITY_API_KEY
    TOGETHER_API_KEY: $TOGETHER_API_KEY
    GROK_API_KEY: $GROK_API_KEY
    DEEPSEEK_API_KEY: $DEEPSEEK_API_KEY
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY

7 Python-Only Variant (Optional)

Some teams dislike Node.js in tooling chains.

A drop-in port lives in .ctx/python_variant/:
snapshot_builder.py, prompt_gen.py, prune.py
identical CLI via python -m ctx snapshot ...
deps: openai, pyyaml, argparse, gitpython, anthropic, google-generative-ai, cohere, mistralai (if implemented in Python)

Toggle by pointing your hooks to the Python entrypoints. This variant would need similar multi-model updates if full parity is desired.

8 Best Practices

• Keep prompts short – always run ctx prompt, never paste full diffs.
• Tag commits & PRs with the same slugs you feed AI ([CLI], [WEB], etc.).
• Lock sections: When an AI delivers a design you accept, reply “Lock section X” so the assistant (if configured) will condense it in future snapshots (this is a conceptual feature for advanced AI agents).
• Prune aggressively – 30-60 days is ample; real decisions should already be in code or docs. Adjust PRUNE_DAYS in .ctx/ctx.config.yaml.
• Single source of truth – treat docs/context-snapshot.md as gospel for “what changed & why” between releases.
• Choose the right model: Experiment with MODEL_SETTINGS for snapshot_max_tokens, prune_max_tokens, snapshot_temperature, and prune_temperature to find the best balance of cost, speed, and quality for your project’s needs. Use --model for ad-hoc testing.

9 Troubleshooting

10 License

MIT – do whatever you want, just don’t remove attributions in file headers.
Happy token-saving! 🐰