sagex-runtime

Self-learning local code agent runtime.

This is the npm wrapper for sagex — a self-hosted code agent that watches your repo, acts on changes via LLM agents, reflects on outcomes, and accumulates a persistent knowledge store that gets smarter with every cycle.

If you already have Python 3.11+, pip install sagex is equivalent and skips the wrapper.

Install

For day-to-day use, install globally so the sagex command is on your PATH:

npm i -g sagex-runtime
sagex --version

npm install runs a postinstall script that creates a private venv at ~/.sagex/venv and pip-installs the real sagex Python package into it. Subsequent invocations of sagex dispatch to that venv via the global sagex-runtime shim — no per-call setup cost. (When invoked via npx instead, the same postinstall step runs inside npx's temporary install cache.)

To try it without a global install, you can one-shot any command via npx -p sagex-runtime sagex <cmd> — note the sagex CLI will not be on PATH afterwards, so you'd need to repeat the npx -p ... prefix for every call. The global install is strictly easier for interactive workflows.

Quick start

Assumes you've done the global install above (npm i -g sagex-runtime).

# 1. Authenticate for one provider (pick one)
export ANTHROPIC_API_KEY=sk-ant-...                     # anthropic_api (default)
# OR: npm i -g @anthropic-ai/claude-code && claude login  # claude_code — $0 with Claude Pro/Max
# OR: export OPENAI_API_KEY=sk-...                        # openai_api
# OR: ollama serve &                                      # ollama — local, free

# 2. Start the runtime
sagex serve --port 8765 &

# 3. In your project repo
sagex init .
# Edit .agents/config.yaml → agent.provider to match step 1 (default is anthropic_api)
sagex register .agents/config.yaml

# 4. Check activity (usage dollar column reads $0 for claude_code / ollama)
sagex status <project-name>
sagex usage <project-name> --last 24h

Requirements

• Node 18+ (for the wrapper)
• Python 3.11+ (auto-detected; sagex runs in a private venv)
• macOS / Linux / Windows

What makes sagex different

• Self-hosted — your code never leaves your laptop
• Self-learning — each event trains a persistent rule store
• Multi-provider — Anthropic API (default), Claude Code passthrough (uses your Claude Pro/Max subscription for $0/call), OpenAI API, or local Ollama.
• Built-in cost controls — budget caps, prompt caching, triage skips

License

MIT