Back to Home

Context Wrangler 🚦

2025-05-27
KBS
Web DevelopmentLinuxNetworkingMusicAI/ML

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:

Need Wrangler Feature
Quick “state of the project” blurb ctx snapshot ⇒ docs/context-snapshot.md
AI prompt that fits the 16 k-token envelope ctx prompt …
Automatically compress ancient chat logs ctx prune
Kanban source of truth synced to Issues/Projects ctx kanban-sync (GitHub) or .gitlab_ci.yml job

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

Command Purpose Typical Use
pnpm ctx snapshot Append a bullet-point summary of the git diff since last snapshot to docs/context-snapshot.md and retag ctx-snap-${PROJECT_SLUG}. Run post-merge so every pull request leaves a breadcrumb. Can specify --model to use a different AI for summarization (e.g., pnpm ctx snapshot --model cohere:command-r-plus).
pnpm ctx prompt … Print a ready-to-paste prompt block containing just the first 40 lines of the diff plus your goal. Generate AI queries that never overflow. Example: pnpm ctx prompt --goal "refactor X" --tag FEATURE-123 --diff patches/feat.patch. The --model flag here is for validation of your chosen model only.
pnpm ctx prune … Replace chat logs older than N days in chat-archive/ with one-line bullet digests. Nightly job. Can specify --days N (e.g., pnpm ctx prune --days 45) and --model to use a different AI for summarization (e.g., pnpm ctx prune --model mistral:mistral-small-latest).
pnpm ctx kanban-sync Mirror GitHub Issues → docs/roadmap.md (checkbox list). On every Issue open/close event. (Note: kanbanSync.mjs is a placeholder in this boilerplate and would need to be implemented for full functionality).

Add --help to any verb for flags.

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

This file is the central hub for configuring Context Wrangler.

Key Description Example Value
PROJECT_SLUG Text used in snapshot Git tag (ctx-snap-<slug>). ultimate-tab
DEFAULT_AI_MODEL The AI model used by default for snapshot and prune if not specified via CLI. openai:gpt-4o
SNAPSHOT_TAG_PREFIX Prefix for the Git tag used for snapshots. ctx-snap-
TOKEN_LIMIT Soft cap used by internal scripts (not hard-enforced). 16000
PRUNE_DAYS Age threshold for log compression in days. 30
MODELS Defines available AI providers and their API key environment variables/base URLs. Each key under MODELS (e.g., openai, cohere) represents a provider. See example below
MODEL_SETTINGS Fine-tunes parameters (max_tokens, temperature, etc.) for specific AI models based on the command. This allows you to set different summary lengths or creativity levels for snapshot versus prune. See example below

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

Symptom Fix
Error: API key missing Ensure the correct API key environment variable (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, COHERE_API_KEY, MISTRAL_API_KEY) is set.
AI model 'model-name' not configured Check DEFAULT_AI_MODEL in .ctx/ctx.config.yaml or the --model CLI argument. Ensure the model is listed under MODELS or MODEL_SETTINGS.
No changes since last snapshot. You haven’t committed anything new – normal.
Tag conflict ctx-snap-xyz already exists Someone rewound history; delete & recreate the tag or git pull --tags.
GitHub Action fails on road-map sync Ensure GH_OWNER and GH_REPO env vars are set in the job (and kanbanSync.mjs is implemented).
Error during AI API call: ... Check your internet connection, API key validity, and model availability. The error message should provide more details.

10 License

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

Previous
Vibe Coding with Llm Agents
Next
Books