sagex 0.2.1

Self-learning local code agent runtime

sagex

Self-learning local code agent that watches your codebase, acts autonomously, and gets smarter with every cycle.

The agent that learns your codebase so you don't have to explain it twice.

---

What it does

Sagex runs alongside your project. It watches for file changes, reasons about what matters, takes action via LLM agents, and reflects on outcomes — storing lessons in a local SQLite knowledge base that improves every cycle.

File change detected
       ↓
Triage agent  →  is this worth acting on?
       ↓
Task agent    →  plan and apply edits
       ↓
Meta agent    →  what did we learn?
       ↓
Rules DB      →  store lesson for next time

---

Install

Python (PyPI)

pip install sagex

Node (npx — no Python setup needed)

npx sagex-runtime serve --port 8765
# After install, the CLI is exposed as `sagex` (not `sagex-runtime`):
sagex --version

---

Choose a provider (v0.2.0+)

Sagex talks to four LLM providers behind the same interface. Pick one in .agents/config.yaml under agent.provider::

Provider	Auth	Cost	Best for
anthropic_api (default)	ANTHROPIC_API_KEY env	Pay-per-token (Anthropic)	Teams, predictable spend
claude_code	Local claude login	$0 (Claude Pro/Max subscription)	Solo devs already paying for Claude Max
openai_api	OPENAI_API_KEY env	Pay-per-token (OpenAI)	OpenAI customers / GPT-5 preference
ollama	None	$0 (local hardware)	Privacy, offline, hobbyists

For a one-off run without editing the config, override with SAGEX_PROVIDER=ollama sagex serve .... See docs/PROVIDERS.md for quality expectations, hardware guidance, and known caveats per provider.

---

Quick start

# Set your Anthropic API key
export ANTHROPIC_API_KEY=sk-ant-...

# Start the runtime
sagex serve --port 8765

# In your project repo (separate terminal)
sagex init .
sagex register .agents/config.yaml

# Check status
sagex status my-project

# Review token spend
sagex usage my-project --last 24h

# Dry-run a manual cycle (safe to test)
sagex trigger my-project --dry-run

---

Configuration

sagex init . creates .agents/config.yaml in your project:

project:
  name: my-project
  watch_paths: ["src/", "tests/"]
  test_command: "pytest tests/ -q"

agents:
  triage:
    model: claude-haiku-4-5
    severity_threshold: medium
  task:
    model: claude-sonnet-4-5
    max_tokens: 4096
  meta:
    model: claude-sonnet-4-5
  security:
    model: claude-sonnet-4-5
    auto_remediate: false

budget:
  hourly_token_limit: 50000
  daily_token_limit: 500000
  alert_threshold: 0.8

---

Requirements

• Python 3.11+
• ANTHROPIC_API_KEY environment variable
• SQLite (bundled with Python)

---

Publishing

See PUBLISHING.md for instructions on releasing to PyPI and npm.

---

License

MIT — see LICENSE.