# PsYcGoD/sage [Health: Active]

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/PsYcGoD/sage  
**GitHub Stars:** 11  
**npm Downloads (last month):** 292  
**Views:** 6  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/psycgod-sage

## Description
Local-first CLI and MCP wrapper for AI coding agents. Routes shell commands through sage run --, stores command history locally, and returns compressed terminal output to reduce context noise.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "sage": {
    "command": "npx",
    "args": ["-y","psycgod-sage"]
  }
}
```

## Documentation

## What PsYcGoD/sage does

PsYcGoD/sage is a local-first command wrapper for AI coding workflows. It places SAGE between an agent and the shell: commands run locally, complete terminal output is retained locally, and the agent receives a compressed result intended to emphasize useful output over repetitive logs. The project also records command history, compression evidence, retry context, and related local metrics.

The package can be used from ordinary terminal sessions, CI scripts, or supported coding agents. It is distributed through both PyPI and npm; the npm package launches the Python implementation, so both installation routes use the same local behavior and database.

## How it works

Install the package, then run `sage install` once. That activation step updates or repairs supported local agent instructions and checks whether activation succeeded. New agent sessions can then be directed to route terminal work through SAGE. Existing sessions should be restarted so they reload the instructions.

The primary execution form is:

```text
sage run -- <command>
```

SAGE executes the command, saves its raw output locally, and returns a shorter summary. Shortcuts such as `sage pytest`, `sage npm test`, and `sage git status` map to the same wrapper. When the host starts in the wrong directory, `sage run --cwd /project -- <command>` supplies an explicit workspace.

MCP support is optional and manual rather than automatically enabled by package installation. The project includes an `sage mcp install` command for MCP configuration, while normal CLI execution remains the default path.

## Setup and configuration

Install with either package manager:

```bash
pip install psycgod-sage
sage install
```

or:

```bash
npm install -g psycgod-sage
npx -y psycgod-sage install
```

After activation, verify the setup with `sage doctor --activation`. Useful commands include `sage context stats` for a savings summary, `sage context report` for a fuller compression report, and `sage history --limit 10` for recent commands.

The `SAGE_WORKSPACE_CWD` setting can define the workspace directory for host integrations. An explicit `--cwd` argument is available when a single invocation needs a different project location.

## Tools and capabilities

- Execute arbitrary shell commands through `sage run --`.
- Keep raw terminal output and command history on the local machine.
- Return compressed terminal summaries to reduce repeated log context.
- Report context and compression statistics.
- Explain the latest failed command and suggest a next fix.
- Attempt an automatic fix with `sage fix --apply`.

## Limitations and notes

Package installation does not activate SAGE automatically; `sage install` is required. Host applications that disable shell tools prevent SAGE from enabling them. MCP may disconnect in some stdio agent sessions, so the regular CLI wrapper is the recommended default when that occurs.

Local-only mode sends nothing away from the machine. Optional debug telemetry can send redacted diagnostic summaries only when explicitly enabled. The project is licensed under MIT.

_Full upstream README: https://allmcps.com/mcp/psycgod-sage/readme_