psycgod-sage 2.0.1

Local-first command wrapper for AI coding agents with compressed terminal output and privacy-safe proof metrics.

SAGE

SAGE is a local-first command wrapper for AI coding agents that compresses terminal output, preserves raw logs locally, and proves token savings with privacy-safe metrics.

The public package is CLI-first. The desktop GUI is not included in this public repository yet.

Live Public Proof Dashboard

Live dashboard: https://psyc-god-sage-api.valan-dj.workers.dev/dashboard

Current public proof includes:

• Total commands processed through SAGE
• Tokens processed, compressed, and saved
• Estimated savings by AI agent/provider
• Compression rate and command success rate
• ML prediction scoring from local command history

Latest verified snapshot:

Metric	Value
Commands processed	4,726
Tokens processed	16,870,812
Tokens compressed	1,225,605
Tokens saved	15,645,207
Estimated savings	$46.94
Compression rate	92.74%
Success rate	98.03%

These stats reflect the public CLI proof snapshot after the hosted dashboard went live. Raw commands, outputs, file paths, and logs stay local by default. Public proof uses aggregate counters only.

Install From GitHub Until PyPI Is Live

PyPI publishing is prepared but still blocked by the Trusted Publisher project-name mismatch. Until the PyPI project is live, install the public CLI directly from GitHub:

pip install git+https://github.com/PsYcGoD/sage.git
sage --version

After PyPI is live, the install command will be:

pip install psycgod-sage
sage --version

For local development:

git clone https://github.com/PsYcGoD/sage.git
cd sage
pip install -e .
sage --version

The prepared PyPI distribution is psycgod-sage; the installed CLI command is still sage.

Connect Your Account

Most public API-backed commands require GitHub OAuth:

sage connect
sage whoami
sage api status

SAGE stores the API key in the operating system keyring when available. Local command history and raw outputs remain on your machine.

Bind Agent Instructions

Create local SAGE instructions for terminal agents:

sage init

This writes SAGE.md in the current project. Give that file to your local AI coding agent, or bind the same rule into your AGENTS.md / agent instruction file:

Route every shell command through:

sage run -- <command>

Run Commands Through SAGE

sage run -- python -m pytest
sage run -- npm test
sage run -- git status

SAGE stores full raw command output locally, summarizes noisy output for AI context, tracks compression, and sends only allowed aggregate proof metrics to the dashboard.

Useful CLI Commands

sage context stats
sage context report
sage history --limit 10
sage explain
sage suggest
sage fix
sage fix --apply --confidence 0.9
sage savings --agent claude-sonnet
sage firewall status
sage firewall rules list
sage github-bot comment --kind summary
sage mcp install
sage dashboard start --port 8765

Team View Preview

Team Dashboard is not published yet. It will open by invite after SAGE reaches 100 users.

The planned Team View will show aggregate workspace proof only: tokens saved, success rate, safety events, and protected secrets. It will not publish raw commands, source code, file paths, .env data, or raw logs.

Screenshots

Command	Preview
sage run --
sage context report
sage mcp install
Dashboard proof

Starter demo GIFs:

• demo-sage-run.gif
• demo-sage-savings.gif
• demo-github-bot.gif

GUI Status

The desktop GUI is not available in this public repo right now.

sage gui

This command prints the roadmap status instead of launching a desktop app. The GUI will be released later with AI agents and ML workflows after it is stable enough for public use.

Known Limitations

• The GUI is not public yet and is intentionally absent from the CLI package.
• GitHub OAuth / a SAGE API key is required for most API-backed commands and public proof sync.
• Telemetry level 0 is local-only; higher levels are opt-in and constrained by account/key policy.
• The public dashboard is aggregate-only and does not expose raw commands, raw outputs, file paths, or local logs.
• Local ML and agent features depend on local history volume and optional provider credentials.

Privacy

• Raw commands and full outputs stay local by default.
• Public dashboard data is aggregate proof only.
• API connection is handled through GitHub OAuth.
• Higher telemetry is opt-in.
• API keys are stored in the OS keyring when available.

See PRIVACY.md and SECURITY.md for the detailed data and security model.

Development

python -m pytest -q

The public package is CLI-first. GUI source, GUI tests, and GUI-only dependencies are intentionally not shipped in this repo at this time.