{"id":49219811,"url":"https://github.com/alohaninja/shift","last_synced_at":"2026-04-29T19:00:43.377Z","repository":{"id":353414845,"uuid":"1218373005","full_name":"alohaninja/shift","owner":"alohaninja","description":"SHIFT (Smart Hybrid Input Filtering \u0026 Transformation)","archived":false,"fork":false,"pushed_at":"2026-04-28T16:45:20.000Z","size":2842,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T18:33:44.605Z","etag":null,"topics":["agentic-coding","ai-coding","anthropic","claude-code","cli","command-line-tool","cost-reduction","developer-tools","llm","open-code","open-source","productivity","rust","token-optimization"],"latest_commit_sha":null,"homepage":"https://shift-ai.dev/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alohaninja.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-22T20:10:40.000Z","updated_at":"2026-04-28T16:41:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alohaninja/shift","commit_stats":null,"previous_names":["alohaninja/shift"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/alohaninja/shift","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alohaninja%2Fshift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alohaninja%2Fshift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alohaninja%2Fshift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alohaninja%2Fshift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alohaninja","download_url":"https://codeload.github.com/alohaninja/shift/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alohaninja%2Fshift/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32439301,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T18:12:22.909Z","status":"ssl_error","status_checked_at":"2026-04-29T18:11:33.322Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-coding","ai-coding","anthropic","claude-code","cli","command-line-tool","cost-reduction","developer-tools","llm","open-code","open-source","productivity","rust","token-optimization"],"created_at":"2026-04-24T02:04:24.992Z","updated_at":"2026-04-29T19:00:43.345Z","avatar_url":"https://github.com/alohaninja.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/alohaninja/shift/main/assets/shift-icon.png\" alt=\"SHIFT\" width=\"200\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eSHIFT\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eSmart Hybrid Input Filtering \u0026 Transformation\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  A multimodal preflight layer that automatically adapts inputs before they reach an AI model.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/alohaninja/shift/actions\"\u003e\u003cimg src=\"https://github.com/alohaninja/shift/workflows/CI/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/alohaninja/shift/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/alohaninja/shift\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://crates.io/crates/shift-preflight-cli\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/shift-preflight-cli\" alt=\"crates.io\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@shift-preflight/runtime\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@shift-preflight/runtime?label=runtime\" alt=\"npm runtime\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@shift-preflight/opencode-plugin\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@shift-preflight/opencode-plugin?label=opencode-plugin\" alt=\"npm opencode-plugin\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/Apache-2.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache_2.0-blue.svg\" alt=\"License: Apache-2.0\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://shift-ai.dev\"\u003eWebsite\u003c/a\u003e \u0026bull;\n  \u003ca href=\"https://shift-ai.dev/guide/\"\u003eGuide\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#install\"\u003eInstall\u003c/a\u003e \u0026bull;\n  \u003ca href=\"https://github.com/alohaninja/shift/blob/main/CHANGELOG.md\"\u003eChangelog\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What it does\n\nSHIFT sits between your application and the model API. Every request passes through a pipeline that **inspects**, **evaluates**, and **transforms** media inputs so they conform to provider constraints.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/alohaninja/shift/main/assets/flow.svg\" alt=\"SHIFT pipeline flow\" width=\"900\" /\u003e\n\u003c/p\u003e\n\n**Before SHIFT:** oversized images, unsupported formats, and bloated payloads cause hard failures (400 errors, token waste, session crashes).\n\n**After SHIFT:** every request is valid, optimized, and tuned to your cost/quality preference.\n\n## Token savings\n\nSHIFT estimates per-provider token savings for every run. Both OpenAI and Anthropic charge tokens based on image dimensions — resizing images before they hit the API reduces cost.\n\n| Scenario | Before | After | OpenAI tokens | Anthropic tokens |\n|---|---|---|---|---|\n| 4000×3000 hero image (balanced) | 4000×3000 | 2048×1536 | 765 → 765 | 1,568 → 1,568 |\n| 4000×3000 hero image (economy) | 4000×3000 | 1024×768 | 765 → 765 | 1,568 → 1,082 (−31%) |\n| 1254×1254 app icon (economy) | 1254×1254 | 1024×1024 | 765 → 765 | 1,568 → 1,405 (−10%) |\n| SVG diagram → rasterized PNG | SVG | 512×256 PNG | 255 → 255 | 0 → 98 |\n\n*Token estimates based on published provider formulas. OpenAI uses tile-based counting (GPT-4o/4.1 family, 512×512 tiles); Anthropic uses pixel-based (`w×h/750`, 1568px long-edge cap for standard models). Actual billing may vary by model — newer OpenAI models use patch-based counting, and Anthropic Opus 4.7 supports higher resolution (2576px, 4784 max tokens).*\n\n### Sample report\n\n```\n$ cat request.json | shift-ai -m economy -o report\n\n=== SHIFT Report ===\nImages found:      1\nImages modified:   1\nImages dropped:    0\nOriginal size:     42262 bytes\nTransformed size:  17018 bytes\nSize reduction:    59.7%\n\nToken Savings (estimated):\n  OpenAI:    765 -\u003e 765 tokens  (0.0% saved)\n  Anthropic: 1,568 -\u003e 1,082 tokens  (31.0% saved)\n\nPer-image breakdown:\n  [0] 4000x3000 -\u003e 1024x768  (OpenAI: 765 -\u003e 765, Anthropic: 1,568 -\u003e 1,082)\n\nActions:\n  [image 0] resize — 4000x3000 -\u003e 1024x768\n```\n\n### Cumulative tracking\n\nSHIFT automatically records run statistics to `~/.shift/stats.jsonl`. View cumulative savings with `shift-ai gain`:\n\n```\n$ shift-ai gain\n\n=== SHIFT Cumulative Savings ===\n\nRuns:     42\nImages:   156 processed, 89 modified\nBytes:    247.3 MB saved\n\nToken Savings (estimated):\n  OpenAI:    52,400 -\u003e 12,300 tokens  (76.5% saved)\n  Anthropic: 84,200 -\u003e 28,100 tokens  (66.6% saved)\n```\n\n```\n$ shift-ai gain --daily\n\n=== SHIFT Daily Token Savings ===\n\nDate          Runs  Images    OpenAI saved Anthropic saved\n----------------------------------------------------------\n2026-04-20       8      24           3,200           5,400\n2026-04-21      12      42           4,800           8,200\n2026-04-22      22      90          12,100          18,500\n```\n\nUse `shift-ai gain --format json` for machine-readable output.\n\n## Runtime: AI SDK Middleware + HTTP Proxy\n\nThe `@shift-preflight/runtime` package (`runtime/` directory) provides two ways to integrate SHIFT into any AI agent or application:\n\n**AI SDK Middleware** — transparent, in-process optimization for any [Vercel AI SDK](https://sdk.vercel.ai) app:\n\n```typescript\nimport { shiftMiddleware } from \"@shift-preflight/runtime\";\nimport { wrapLanguageModel } from \"ai\";\n\nconst model = wrapLanguageModel({\n  model: anthropic(\"claude-sonnet-4-20250514\"),\n  middleware: shiftMiddleware({ mode: \"balanced\" }),\n});\n```\n\n**HTTP Proxy** — transparent reverse proxy for any agent in any language:\n\n```bash\nnpx @shift-preflight/runtime proxy --port 8787 --mode balanced\n\n# Point any agent at the proxy:\nexport ANTHROPIC_BASE_URL=http://localhost:8787   # Claude Code\nexport OPENAI_BASE_URL=http://localhost:8787       # Codex CLI\nexport GEMINI_API_BASE=http://localhost:8787        # Gemini CLI\n```\n\nSee [`runtime/README.md`](runtime/README.md) for full documentation.\n\n**OpenCode Plugin** — auto-starts the proxy on [OpenCode](https://opencode.ai) launch:\n\n```json\n{\n  \"plugin\": [\"@shift-preflight/opencode-plugin\"],\n  \"provider\": {\n    \"anthropic\": {\n      \"options\": {\n        \"baseURL\": \"http://localhost:8787\"\n      }\n    }\n  }\n}\n```\n\nSee [`opencode-plugin/README.md`](opencode-plugin/README.md) for setup details.\n\n## Agent integrations\n\nThe fastest way to configure all your agents at once:\n\n```bash\nshift-ai setup\n```\n\nThis detects installed agents, configures each one, and optionally installs a\nmacOS LaunchAgent to keep the proxy running.\n\n| Agent | Method | Setup |\n|-------|--------|-------|\n| **Any agent** | [Interactive setup](#setup) | `shift-ai setup` (auto-detects + configures) |\n| [OpenCode](https://opencode.ai) | [Plugin](opencode-plugin/) (auto) | Plugin auto-starts proxy and sets `baseURL` |\n| [Claude Code](https://claude.ai/code) | [`settings.json`](claude-code-hook/) | Writes `ANTHROPIC_BASE_URL` to `~/.claude/settings.json` |\n| [Codex CLI](https://github.com/openai/codex) | [`config.toml`](codex-plugin/) | Writes `openai_base_url` to `~/.codex/config.toml` |\n| Cursor | Settings UI (manual) | Paste URL into Settings \u003e Models \u003e Override OpenAI Base URL |\n| AI SDK apps | Middleware (in-process) | `wrapLanguageModel({ middleware: shiftMiddleware() })` |\n\n\u003e **Gemini CLI** does not support API base URL overrides and is not currently supported.\n\n### Quick per-agent setup\n\n```bash\n# Claude Code — env var (add to ~/.zshrc)\neval \"$(shift-ai env claude-code)\"\n\n# Codex CLI — prints TOML snippet for ~/.codex/config.toml\nshift-ai env codex\n\n# List all agents and their config methods\nshift-ai env --list\n```\n\nAll agents share the same proxy on port 8787 — start it once and every agent benefits.\n\n## Install\n\n### Homebrew (macOS/Linux)\n\n```bash\nbrew tap alohaninja/shift\nbrew install shift-ai\n```\n\n### Quick install script\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/alohaninja/shift/main/install.sh | sh\n```\n\nInstalls to `~/.local/bin`. Detects OS/arch automatically (macOS x86/arm, Linux x86/arm).\n\n### From crates.io\n\n```bash\ncargo install shift-preflight-cli\n```\n\n### Pre-built binaries\n\nDownload from [GitHub Releases](https://github.com/alohaninja/shift/releases) — macOS (x86/arm) and Linux (x86/arm).\n\n### From source\n\n```bash\ngit clone https://github.com/alohaninja/shift.git \u0026\u0026 cd shift\ncargo install --path shift-cli\n```\n\n### AI Agent Skill\n\nIf you use an AI coding agent (Claude Code, Cursor, Copilot, Windsurf, etc.):\n\n```bash\nnpx skills add alohaninja/shift\n```\n\nThis installs the `shift-ai-preflight` skill, which teaches your agent when and how to use SHIFT to optimize image payloads.\n\n### Verify installation\n\n```bash\nshift-ai --version\nshift-ai --help\n\n# Quick validation — transform a sample payload\necho '{\"model\":\"gpt-4o\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}' | shift-ai\n\n# Check stats tracking\nshift-ai gain\n```\n\n## Quick start\n\n```bash\n# Transform an OpenAI request (stdin/stdout pipe)\ncat request.json | shift-ai -p openai -m balanced \u003e safe_request.json\n\n# Transform an Anthropic request from a file\nshift-ai request.json -p anthropic -m economy \u003e safe_request.json\n\n# See what would change without modifying anything\nshift-ai request.json --dry-run -o report\n\n# Compose with curl\nshift-ai request.json -p openai | curl -s -X POST \\\n  https://api.openai.com/v1/chat/completions \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d @-\n```\n\n## Options\n\n```\nshift-ai [OPTIONS] [FILE]\n\nArguments:\n  [FILE]  Input file (JSON request payload). Reads stdin if omitted.\n\nOptions:\n  -p, --provider \u003cPROVIDER\u003e  Target provider [default: openai]\n                              [openai, anthropic, claude]\n  -m, --mode \u003cMODE\u003e          Drive mode [default: balanced]\n                              [performance, balanced, economy]\n      --svg-mode \u003cMODE\u003e      SVG handling [default: raster]\n                              [raster, source, hybrid]\n  -o, --output \u003cFORMAT\u003e      Output format [default: json]\n                              [json, report, json-report, both]\n      --dry-run              Show what would change without modifying\n      --profile \u003cFILE\u003e       Custom provider profile JSON\n      --model \u003cMODEL\u003e        Target model (overrides model in payload)\n      --no-stats             Disable saving run statistics\n  -v, --verbose              Verbose output\n\nCommands:\n  shift-ai gain                 Show cumulative token savings\n  shift-ai gain --daily         Day-by-day breakdown\n  shift-ai gain --format json   Machine-readable output for dashboards\n  shift-ai proxy start          Start the proxy daemon\n  shift-ai proxy stop           Stop the proxy daemon\n  shift-ai proxy status         Show proxy status\n  shift-ai proxy ensure         Start if needed, no-op if healthy\n  shift-ai env \u003cagent\u003e          Output config for an agent\n  shift-ai env --list           List all supported agents and methods\n  shift-ai env --all            Output config for all agents\n  shift-ai setup                Interactive multi-agent setup\n```\n\n## Drive modes\n\n| Mode | What it does |\n|---|---|\n| **performance** | Minimal transforms. Only enforce hard provider limits (max dimension, max file size). Preserve original fidelity. |\n| **balanced** | Moderate optimization. Resize oversized images, recompress bloated files. Remove obvious waste. **Default.** |\n| **economy** | Aggressive optimization. Downscale everything to 1024px, drop excess images beyond provider limits, minimize token usage. |\n\n## SVG handling\n\nMost AI model APIs reject SVG. SHIFT detects SVG inputs and handles them based on `--svg-mode`:\n\n| Mode | Behavior |\n|---|---|\n| **raster** | Rasterize SVG to PNG via `resvg` (default, provider-safe) |\n| **source** | Replace the image with SVG XML as a text content block |\n| **hybrid** | Rasterize to PNG and retain SVG source as text |\n\n## Supported formats\n\n**Detected and processed:**\n\n| Category | Formats |\n|---|---|\n| Raster images | PNG, JPEG, GIF, WebP, BMP, TIFF |\n| Vector images | SVG (auto-rasterized to PNG) |\n| Encodings | base64 data URIs, raw base64, URL references |\n\nBMP and TIFF are auto-converted to PNG. SVGs are rasterized. Everything else passes through if it meets provider constraints.\n\n## Provider profiles\n\nBuilt-in constraints for the two major multimodal providers:\n\n| Provider | Max images | Max dimension | Max file size | Megapixel limit |\n|---|---|---|---|---|\n| **OpenAI** | 10 | 2048 px | 20 MB | -- |\n| **Anthropic** | 20 | 8000 px | 5 MB | 1.15 MP |\n\nProfiles include per-model overrides (gpt-4o, gpt-4.1, claude-sonnet-4, etc.) and fall back to provider defaults for unknown models.\n\nCustom profiles can be loaded with `--profile custom.json`.\n\n## Library usage\n\nSHIFT is split into two crates: `shift-preflight` (library) and `shift-preflight-cli` (binary, installs as `shift-ai`). The library can be used directly in Rust applications:\n\n```toml\n# Cargo.toml\n[dependencies]\nshift-preflight = \"0.1\"\n```\n\n```rust\nuse shift_preflight::{pipeline, ShiftConfig, DriveMode};\nuse serde_json::json;\n\nlet payload = json!({\n    \"model\": \"gpt-4o\",\n    \"messages\": [{\n        \"role\": \"user\",\n        \"content\": [{\n            \"type\": \"image_url\",\n            \"image_url\": {\"url\": \"data:image/png;base64,...\"}\n        }]\n    }]\n});\n\nlet config = ShiftConfig {\n    mode: DriveMode::Balanced,\n    provider: \"openai\".to_string(),\n    ..Default::default()\n};\n\nlet (safe_payload, report) = pipeline::process(\u0026payload, \u0026config).unwrap();\neprintln!(\"{}\", report); // what changed and why\n```\n\n## How it works\n\n1. **Inspect** -- Detect every image in the request payload. Extract format (via magic bytes), dimensions, file size, encoding type. Handles base64 data URIs, raw base64, and URL references (fetched automatically).\n\n2. **Evaluate** -- Load the provider profile for the target API. Compare each image's metadata against the constraints. Apply mode-specific rules to determine what actions are needed (resize, recompress, convert, rasterize, drop).\n\n3. **Transform** -- Execute the actions. Resize preserves aspect ratio using Lanczos3 filtering. SVGs are rasterized with `resvg` (supports gradients, text, viewBox). BMP/TIFF are converted to PNG. JPEG recompression uses mode-tuned quality levels.\n\n4. **Reconstruct** -- Rebuild the original payload with transformed images slotted back in. Output is a valid JSON request ready to send to the API.\n\n## Project structure\n\n```\nshift/\n├── shift-core/          Library crate: shift-preflight (all processing logic)\n│   └── src/\n│       ├── inspector/   Format detection, metadata extraction\n│       ├── policy/      Provider profiles, constraint evaluation, rules\n│       ├── transformer/ Image resize, recompress, SVG rasterize, convert\n│       ├── payload/     OpenAI + Anthropic message format parse/reconstruct\n│       ├── pipeline.rs  Orchestrator: inspect -\u003e policy -\u003e transform\n│       ├── cost.rs      Token estimation (OpenAI tile, Anthropic pixel)\n│       ├── stats.rs     Persistent run statistics, gain summaries\n│       ├── report.rs    Transformation report with token savings\n│       └── mode.rs      DriveMode, SvgMode, ShiftConfig\n├── shift-cli/           Binary crate: shift-preflight-cli → shift-ai\n│   └── src/\n│       ├── main.rs      CLI entry point + existing commands\n│       ├── proxy.rs     Proxy daemon lifecycle (start/stop/ensure)\n│       ├── env.rs       Agent env var generation\n│       └── setup.rs     Interactive multi-agent setup\n├── runtime/             @shift-preflight/runtime (TS middleware + proxy)\n├── opencode-plugin/     @shift-preflight/opencode-plugin (OpenCode)\n├── claude-code-hook/    Claude Code integration (settings + installer)\n├── codex-plugin/        Codex CLI integration (env var + installer)\n├── launchagent/         macOS LaunchAgent plist for auto-start\n├── profiles/            Provider constraint JSON (embedded at compile time)\n├── tests/\n│   ├── fixtures/        Test images and sample payloads\n│   └── docker/          Dockerfiles for cross-distro CI (Ubuntu, Arch)\n└── .github/workflows/   CI + Linux distro tests\n```\n\n## Roadmap (v2+)\n\n- **Video**: frame sampling, keyframe extraction, resolution downscale\n- **Audio**: compression, transcription to text\n- **Documents**: chunking, summarization, text extraction\n- **Smart image selection**: near-duplicate detection, keep most informative\n- **Caption fallback**: replace low-value images with text descriptions\n- **Adaptive policies**: dynamic adjustment based on request size and latency targets\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falohaninja%2Fshift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falohaninja%2Fshift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falohaninja%2Fshift/lists"}