sagex 0.2.2

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 (no Python setup needed — the wrapper installs sagex into a private venv during npm install, or on first use via npx)

# Install globally so the `sagex` CLI is on your PATH:
npm i -g sagex-runtime
sagex --version
sagex serve --port 8765

# Or one-shot without installing (must repeat for every call):
npx -p 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

# Authenticate for your chosen provider (one of):
export ANTHROPIC_API_KEY=sk-ant-...   # anthropic_api (default)
export OPENAI_API_KEY=sk-...          # openai_api
claude login                          # claude_code (npm i -g @anthropic-ai/claude-code)
# ollama needs nothing — ensure `ollama serve` is running

# 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 (dollar column reads $0 for claude_code / ollama)
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. The YAML below is an illustrative excerpt of the default config — the authoritative source is src/sagex/cli.py::_CONFIG_TEMPLATE, which is what sagex init actually writes (with additional knowledge:, runner:, and notifications: sections and slightly different formatting). One agent: block drives all four sub-agents (triage, task, meta, security); per-agent token ceilings live on the same block.

name: my-project
repo_root: .

watch:
  paths:
    - "src/**/*.py"
    - "tests/**/*.py"
    - "*.yaml"
    - "*.toml"
  ignore:
    - "**/__pycache__/**"
    - "**/.git/**"
    - "**/*.log"
  debounce_seconds: 2.0

test:
  command: "pytest tests/ -x --tb=short"
  timeout_seconds: 120

agent:
  # Provider selection — override per-run with SAGEX_PROVIDER=<name>
  provider: "anthropic_api"    # anthropic_api | claude_code | openai_api | ollama
  # Leave empty to auto-resolve to the provider's default
  # (anthropic_api/claude_code → claude-sonnet-4-6 + claude-haiku-4-5;
  #  openai_api → gpt-5 + gpt-4o-mini;
  #  ollama → llama3.1:8b + llama3.2:1b).
  model: ""
  triage_model: ""
  max_tokens: 2048             # task agent output ceiling
  triage_max_tokens: 512       # haiku triage classification
  meta_max_tokens: 1024        # reflection JSON
  security_max_tokens: 1024    # security audit JSON
  summariser_max_tokens: 512   # diff pre-summariser (haiku)
  temperature: 0.2
  # triage_temperature: 0.0   # supported but not written by default; add if you want to override
  ollama_base_url: "http://localhost:11434"   # ollama only

budget:
  hourly_token_limit: 50000
  daily_token_limit: 500000
  alert_threshold: 0.8
  content_cache_ttl_minutes: 60
  enable_prompt_caching: true  # Anthropic cache_control, threshold-guarded

agents:
  security:
    enabled: false
    watch_extra:
      - ".env*"
      - "**/*secret*"
      - "**/requirements*.txt"
      - "**/Dockerfile*"
    auto_remediate: false

Cross-provider model settings (e.g. provider: openai_api + model: claude-sonnet-4-6) fail at config-load with a clear error.

---

Requirements

• Python 3.11+
• One provider's auth, depending on your agent.provider choice:
  • anthropic_api — ANTHROPIC_API_KEY env var
  • claude_code — local claude CLI (npm i -g @anthropic-ai/claude-code) + claude login
  • openai_api — OPENAI_API_KEY env var
  • ollama — nothing; ollama serve running locally
• SQLite (bundled with Python)

---

Publishing

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

---

License

MIT — see LICENSE.