Purpose
SAGE (Smart Agent Guidance Engine) is a local-first command wrapper designed specifically for AI coding agents. When AI coding agents handle repetitive logs, failed test output, installation noise, stack traces, and build screen spam, they consume a large amount of context. SAGE sits between the command and the agent, keeping the complete terminal output on the user's machine, sending only a clean, compressed summary to the agent, and tracking verifiable savings metrics, without uploading raw logs.
Main Capabilities
- Compresses terminal output, reducing context noise sent to AI agents, thereby saving AI coding tokens.
- Keeps complete terminal output local; raw logs are not uploaded.
- Tracks real savings metrics (proof metrics).
- Provides locally recorded metrics (Recorded Local Metrics).
- Supports Natural shortcuts, which are handled in a specific way.
- Does not automatically enable MCP; MCP is optional and requires manual configuration, for users who need it.
- The npm package delegates to the Python implementation, so both installation paths use the same local database, telemetry rules, compression logic, and command behavior.
Usage
- Install SAGE. The package installation itself is passive (for package registry security reasons).
- After installation, run once
sage install, to activate SAGE for supported local AI agents. - Use once
sage run -- python -m pytest. - After that, any AI agent can be used.
- After installation, restart any open AI agent sessions. New sessions should automatically read the SAGE instructions and route terminal commands to SAGE.
After restarting the AI agent, you can use the Example prompt and Natural shortcuts.
Note: If you do not run install or PYTEST with SAGE, SAGE will not be activated in the local environment.
Applicable Scenarios
Can be used with Claude Code, Codex, Cursor, Windsurf, OpenCode, Cline, custom agents, CI scripts, and ordinary terminal workflows.
Privacy and Data
SAGE's design goal is: unless the user actively enables features that require sending data, prompts, source code, credentials, raw command output, and project files all remain local.
Installation Sources
- PyPI: pypi.org/project/psycgod-sage
- npm: npmjs.com/package/psycgod-sage
Limitations
Known Limitations are listed in the repository, but the specific content is not provided in the material. MCP is not automatically enabled and requires manual configuration by the user. SAGE will not automatically activate in a local environment where install or PYTEST has not been run.
License
MIT. See LICENSE for details.
