{
  "markdown": "# SAGE - Smart Agent Guidance Engine\n\n<!-- mcp-name: io.github.PsYcGoD/sage -->\n\n[![CI](https://github.com/PsYcGoD/sage/actions/workflows/ci.yml/badge.svg)](https://github.com/PsYcGoD/sage/actions/workflows/ci.yml)\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://github.com/PsYcGoD/sage/blob/main/pyproject.toml)\n[![PyPI](https://img.shields.io/pypi/v/psycgod-sage.svg)](https://pypi.org/project/psycgod-sage/)\n[![npm](https://img.shields.io/npm/v/psycgod-sage.svg)](https://www.npmjs.com/package/psycgod-sage)\n[![License](https://img.shields.io/github/license/PsYcGoD/sage.svg)](https://github.com/PsYcGoD/sage/blob/main/LICENSE)\n\nSAGE is a local-first command wrapper for AI coding agents. It keeps full terminal output on your machine, sends agents a clean compressed summary, and tracks proof metrics without uploading your raw logs.\n\nUse it with Claude Code, Codex, Cursor, Windsurf, OpenCode, Cline, custom agents, CI scripts, and normal terminal workflows.\n\n## Start Here: Install SAGE, Use once sage run -- python -m pytest, Then Use Any AI Agent\n\nPackage installation is passive for package-registry safety. After installing, run `sage install` once to connect this machine and activate SAGE for supported local AI agents.\n\n### PyPI / pip\n\n```powershell\npip install psycgod-sage\n# or\npython -m pip install --upgrade psycgod-sage\nsage install\nsage run -- python -m pytest\n```\n\n### npm / npx\n\n```bash\nnpm install -g psycgod-sage\nnpx -y psycgod-sage install\nnpx -y psycgod-sage run -- npm test\n```\n\nAfter install, restart any open AI-agent sessions. New sessions should read the SAGE instructions automatically and route terminal commands through SAGE.\n\nExample prompt after restarting your AI agent:\n\n```text\nPlease help me with my general book in this folder.\n```\n\nNatural shortcuts also work:\n\n```bash\nsage pytest\nsage npm test\nsage git status\n```\n\nThese are treated as:\n\n```bash\nsage run -- pytest\nsage run -- npm test\nsage run -- git status\n```\n\n## What SAGE Does\n\n| Step | Result |\n|---|---|\n| `sage install` | Connects the machine, repairs global/project agent instructions, and verifies activation |\n| `sage run -- <command>` | Runs the command, stores raw output locally, and returns a compact useful summary |\n| Agent memory/hooks | Tell supported AI agents to use SAGE for noisy terminal work |\n| Local database | Keeps command history, compression proof, and retry context on the user's machine |\n| Optional cloud proof | Sends aggregate metrics only when connected proof mode is enabled |\n\nSAGE does not auto-enable MCP. MCP is optional and manual for users who want it.\n\n## Live Proof\n\nLatest pulled stats as of 2026-08-01:\n\n| Metric | Value |\n|---|---:|\n| SAGE telemetry command events | 27,892 |\n| Tokens processed | 799.5M |\n| Tokens saved | 783.7M |\n| Compression rate | 98.02% |\n| Estimated savings | $16,261.90 |\n| Command success rate | 88.3% |\n| PyPI downloads, last 7 days | 632 |\n| npm downloads, last 7 days | 362 |\n| GitHub clones, last 14 days | 574 |\n\nLive dashboard: [sage.api.marketingstudios.in/dashboard](https://sage.api.marketingstudios.in/dashboard)\nInstall page: [sage.api.marketingstudios.in/install](https://sage.api.marketingstudios.in/install)\n\n![SAGE public proof dashboard](docs/assets/sage-live-dashboard.png)\n\n## Why It Helps\n\nAI coding agents burn context on repeated logs, failed test output, install noise, stack traces, and build spam. SAGE sits between the command and the agent.\n\n| Without SAGE | With SAGE |\n|---|---|\n| Agent sees full noisy terminal output | Agent sees the useful summary |\n| Context disappears fast | Context lasts longer |\n| Repeated failures waste tokens | Errors are grouped and explained |\n| Raw logs may enter prompts | Raw logs stay local |\n| Hard to prove savings | SAGE records proof metrics |\n\n## Distribution\n\n| Channel | Package | Status |\n|---|---|---|\n| PyPI | [`psycgod-sage`](https://pypi.org/project/psycgod-sage/) | Canonical Python package |\n| npm / npx | [`psycgod-sage`](https://www.npmjs.com/package/psycgod-sage) | Node launcher for the Python core |\n| MCP Registry | `io.github.PsYcGoD/sage` | Optional/manual MCP entry |\n| Glama | [`PsYcGoD/sage`](https://glama.ai/mcp/servers/PsYcGoD/sage) | Optional/manual hosted MCP listing |\n\nThe npm package delegates to the Python implementation so both install paths use the same local database, telemetry rules, compression, and command behavior.\n\n## Common Commands\n\n```bash\nsage install                       # Activate this machine and AI-agent instructions\nsage doctor --activation           # Verify activation\nnpx -y psycgod-sage doctor --activation\nsage run -- <command>              # Wrap any command\nsage run --cwd /project -- <command> # Explicit workspace for host integrations\nsage pytest                        # Shortcut for: sage run -- pytest\nsage npm test                      # Shortcut for: sage run -- npm test\nsage git status                    # Shortcut for: sage run -- git status\nsage context stats                 # Token savings summary\nsage context report                # Full compression report\nsage history --limit 10            # Recent command history\nsage explain --failed              # Explain the latest failed command\nsage suggest --failed              # Suggest the next fix\nsage fix --apply                   # Try an automatic fix\nsage ml setup                      # Optional ML V2 dependencies\nsage mcp install                   # Optional/manual MCP config\nsage dashboard start               # Local dashboard\n```\n\n## Privacy Modes\n\n| Mode | Requires login? | Sends data? | What leaves the machine? |\n|---|---:|---:|---|\n| Local-only | No | No | Nothing |\n| Connected proof | Machine auth | Yes | Aggregate counters and proof metrics |\n| Debug telemetry | Optional | Opt-in only | Redacted diagnostic summaries |\n\nSAGE is designed to keep prompts, source code, credentials, raw command output, and project files local unless the user deliberately enables a feature that requires sending data.\n\n## Known Limitations\n\n| Limitation | What To Do |\n|---|---|\n| Already-open AI-agent sessions may not reload new instructions | Restart Claude/Codex/Cursor/Windsurf/OpenCode after `sage install` |\n| Locked-down host apps can disable shell tools | SAGE cannot enable tools the host application has blocked |\n| A host starts its shell in the wrong folder | Pass `sage run --cwd <project> -- <command>` or set `SAGE_WORKSPACE_CWD` |\n| npm/PyPI installs cannot safely auto-run activation | Run `sage install` once after package install |\n| MCP can disconnect in some stdio agent sessions | Use normal `sage run -- <command>` by default; enable MCP manually only if needed |\n| Package installs are passive by design | Real activation starts with `sage install` |\n\n## Demos\n\n| Flow | Preview |\n|---|---|\n| PyPI install | ![PyPI install flow](docs/assets/sage-install-pypi.gif) |\n| npm install | ![npm install flow](docs/assets/sage-install-npm.gif) |\n| `sage run --` | ![sage run](https://raw.githubusercontent.com/PsYcGoD/sage/main/docs/assets/sage-run.svg) |\n| CLI run | ![SAGE CLI demo](https://raw.githubusercontent.com/PsYcGoD/sage/main/docs/assets/demo-sage-run.gif) |\n\n## Links\n\n- Landing: [sage.api.marketingstudios.in](https://sage.api.marketingstudios.in/)\n- Dashboard: [sage.api.marketingstudios.in/dashboard](https://sage.api.marketingstudios.in/dashboard)\n- Install guide: [sage.api.marketingstudios.in/install](https://sage.api.marketingstudios.in/install)\n- PyPI: [pypi.org/project/psycgod-sage](https://pypi.org/project/psycgod-sage/)\n- npm: [npmjs.com/package/psycgod-sage](https://www.npmjs.com/package/psycgod-sage)\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 7677,
  "sha": "31bb46aebb5634e508268181219284ab9493f440519103042375bf1c32fdac96",
  "repo_slug": "psycgod/sage",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_psycgod_sage_80a1e0a4/readme"
}