Getting Started

1Clone the repository

$ git clone https://github.com/bug-ops/zeph

2Navigate to the project

$ cd zeph

3Install dependencies

$ cargo build

4Run the agent

$ cargo run

Or connect to the hosted endpoint: https://bug-ops.github.io/zeph/

README

The AI agent that respects your resources.

Single binary. Minimal hardware. Maximum context efficiency. Every token counts — Zeph makes sure none are wasted.

Why Zeph

Most AI agent frameworks dump every tool description, skill, and raw output into the context window — and bill you for it. Zeph takes the opposite approach: automated context engineering. Only relevant data enters the context. The result — lower costs, faster responses, and an agent that runs on hardware you already have.

Semantic skill selection — embeds skills as vectors, retrieves only top-K relevant per query instead of injecting all
Smart output filtering — command-aware filters strip 70-99% of noise before context injection
Two-tier context pruning — selective eviction + adaptive chunked compaction with parallel summarization keeps the window clean
Proportional budget allocation — context space distributed by purpose, not arrival order

Installation

[!TIP]

curl -fsSL https://github.com/bug-ops/zeph/releases/latest/download/install.sh | sh

cargo install zeph                                        # crates.io
cargo install --git https://github.com/bug-ops/zeph      # from source
docker pull ghcr.io/bug-ops/zeph:latest                  # Docker

Pre-built binaries: GitHub Releases · Docker guide

Quick Start

zeph init          # interactive setup wizard
zeph               # run the agent
zeph --tui         # run with TUI dashboard

Full setup guide → · Configuration reference →

Key Features


Hybrid inference	Ollama, Claude, OpenAI, Candle (GGUF), any OpenAI-compatible API. Multi-model orchestrator with fallback chains. Response cache with blake3 hashing and TTL
Skills-first architecture	YAML+Markdown skill files with semantic matching, self-learning evolution, 4-tier trust model, and compact prompt mode for small-context models
Semantic memory	SQLite + Qdrant (or embedded SQLite vector search) with MMR re-ranking, temporal decay scoring, adaptive chunked compaction, credential scrubbing, cross-session recall, vector retrieval, autosave assistant responses, and snapshot export/import
Multi-channel I/O	CLI, Telegram, Discord, Slack, TUI — all with streaming. Vision and speech-to-text input
Protocols	MCP client (stdio + HTTP), A2A agent-to-agent communication, sub-agent orchestration
Defense-in-depth	Shell sandbox, tool permissions, secret redaction, SSRF protection, skill trust quarantine, audit logging
TUI dashboard	ratatui-based with syntax highlighting, live metrics, file picker, command palette, daemon mode
Single binary	~15 MB, no runtime dependencies, ~50ms startup, ~20 MB idle memory

Architecture → · Feature flags → · Security model →

TUI Demo

TUI guide →

Documentation

bug-ops.github.io/zeph — installation, configuration, guides, architecture, and API reference.

Contributing

See CONTRIBUTING.md for development workflow and guidelines.

Security

Found a vulnerability? Please use GitHub Security Advisories for responsible disclosure.

License

MIT

Capabilities

StreamingPush NotificationsMulti-TurnAuth: none

View on GitHub