Eidos is an open, Git-native, agent-agnostic development framework designed to unify product definition, architectural invariants, and autonomous coding agents under executable living specifications.
This repository dogfoods the Eidos Specification Standard to define Eidos itself.
When working with AI coding agents (Claude Code, Cursor, Antigravity, Copilot, Aider, Cline) on growing codebases, static instruction files like CLAUDE.md get large and hard to maintain, traditional ADRs go out of date, and architectural boundaries can silently drift.
Eidos takes an opinionated approach built on Spec-Driven Development, Domain-Driven Design (DDD), Arc42 & the C4 Model, TDD, and a Kanban SpecDelta lifecycle—with Git as the single source of truth and 100% local execution (zero API keys or external LLM calls required):
- Living Architecture in Git (DDD + Arc42/C4 + Kanban): Codifies bounded domains (
DOM-*), capabilities (CAP-*), C4 architecture (CNT-*,CMP-*,CTR-*), and in-place design decisions (DEC-*) as AsciiDoc with YAML frontmatter, tracking architectural transitions via SpecDeltas (DLT-*) across a Kanban lifecycle. - Local SQLite + AST + Hybrid Semantic Knowledge Graph: Indexes code symbols, spec hierarchies, and
x-eidos-reflinks locally (eidos/.cache/index.db)—combining SQLite FTS5 BM25 search, recursive graph traversal, and optional local ONNX semantic embeddings (Hybrid RRF) to serve token-budgeted context slices (eidos context), structural repo maps, and transitive blast-radius queries (eidos index blast-radius) offline with no API keys. - Test-Bound Invariants (TDD +
eidos drift): Binds capability and policy invariants (INV-*) directly to automated tests (file::func) across Python, TypeScript/JS, Go, Rust, Java, and Kotlin, checking for spec-to-code drift in CI or via an agentStophook. - Static C4 Architecture & Kanban Portal: Generates a self-contained web viewer (
eidos portal serve) to browse containers, components, contracts, blast radius, and the SpecDelta Kanban board—View Eidos's Portal
┌───────────────────────────────────┐
│ Living Specifications (eidos/) │
│ CNT-* │ CMP-* │ CTR-* │ CAP/INV │
└─────────────────┬─────────────────┘
│
┌───────────────┴───────────────┐
▼ (SQLite + AST Graph) ▼ (eidos portal)
┌───────────────────┐ ┌───────────────────┐
│ AI Coding Agents │ │ Human Engineers │
│ (eidos context & │ │ (C4 Explorer │
│ Agent Skills) │ │ & Blast Radius) │
└─────────┬─────────┘ └─────────┬─────────┘
│ │
└───────────────┬───────────────┘
▼
┌───────────────────────────────────┐
│ Codebase & Polyglot Test Suite │
│ Checked by: eidos drift / hook │
└───────────────────────────────────┘
# Install globally as a standalone CLI tool with uv (recommended)
uv tool install eidos-ai
# Or install with optional local Harrier ONNX Hybrid RRF semantic search support (Python 3.11–3.14)
uv tool install --python 3.14 "eidos-ai[semantic]"
# Or install with pipx
pipx install eidos-ai
# Or run ephemerally without installing
uvx --from eidos-ai eidos --help
# Initialize Eidos in your repository
eidos init
# (Optional) Provision local Harrier-OSS-v1-0.6B ONNX model for Hybrid RRF semantic search
eidos index semantic setup
# Synchronize SQLite + FTS5 + AST knowledge graph (and semantic embeddings when provisioned)
eidos index sync
# Inspect structural repo map or find code symbols and their owning specs
eidos index repo-map --max-tokens 1500
eidos index find-symbol "ArchitecturalIndex" --json
# Extract a token-budgeted architectural context slice for a file or task
eidos context -t "authentication and drift detection"
# Inspect v1 YAML frontmatter schema constraints & templates for any spec type
eidos spec schema capability
# Validate living specifications
eidos validate eidos
# Verify zero drift between code, tests, and living specs
eidos drift
# Launch interactive C4 architecture portal
eidos portal serve --path eidos --port 8080
# Install AI agent plugin (4 skills for Antigravity, Claude, Cursor, Copilot, Aider, Cline, Kilo Code, OpenCode, Codex)
eidos plugin install allAdd the official Eidos Dev Container Feature (ghcr.io/mchawa/eidos/eidos:1) to .devcontainer/devcontainer.json:
{
"features": {
"ghcr.io/mchawa/eidos/eidos:1": {
"version": "latest",
"semantic": true,
"pythonVersion": "3.14"
}
}
}By default, Eidos runs with zero model weights using SQLite FTS5 BM25, architectural synonym expansion, and recursive CTE graph traversal (< 4ms). To enable Hybrid Reciprocal Rank Fusion (RRF) combining lexical BM25 with local dense embeddings (microsoft/harrier-oss-v1-0.6b ONNX, 100% offline):
Note (Python Version):
onnxruntimecurrently publishes prebuilt wheels only for Python 3.11–3.14 (python_version < '3.15'). If your default interpreter is Python 3.15, pass--python 3.14when installing or syncing the[semantic]extra; on Python 3.15, Eidos automatically falls back to lexical FTS5 BM25 retrieval.
# 1. Install optional ONNX Runtime + Tokenizers + NumPy extra (Python 3.11–3.14)
uv tool install --python 3.14 "eidos-ai[semantic]" # or: uv sync --python 3.14 --extra semantic
# 2. Download Harrier ONNX artifacts into eidos/.cache/models/harrier-oss-v1-0.6b/
eidos index semantic setup # --model quantized (default INT8, 706 MB) | fp16 | fp32
# 3. Sync the index (automatically builds & refreshes spec_embeddings whenever Harrier is provisioned)
eidos index sync
eidos index semantic statusOnce provisioned, eidos context -t "<task>", eidos index search "<query>", and eidos drift automatically fuse FTS5 BM25 and Harrier cosine similarity (or pass --no-semantic for pure lexical retrieval).
eidos/
├── pyproject.toml # Modern Python package definition (eidos-ai on PyPI)
├── zensical.toml # Zensical documentation site configuration
│
├── src/eidos/ # [THE ENGINE / SOLUTION]
│ ├── cli/ # CLI commands (`eidos validate`, `eidos drift`, `eidos context`, etc.)
│ ├── core/ # Spec parser, validator, scaffolder, DeltaEngine & knowledge graph (`index/`)
│ ├── plugin/ # Agent plugin installer (`TargetAdapter`), validator, and lifecycle hooks
│ ├── portal/ # Interactive Living Architecture server & static portal generator
│ └── vcs/ # Git spec-to-code drift detection, AST symbol diffing & invariant verification
│
├── assets/ # [BUNDLED SCHEMAS, SKILLS & PORTAL ASSETS]
│ ├── schemas/v1/ # 16 canonical JSON/YAML schemas + shared `common/defs.yaml`
│ ├── plugin_reference/ # Canonical `agentskills.io` 4 workflow skills & reference `hooks.json`
│ └── portal/ # Pre-compiled air-gapped portal SPA (`bundle.html.gz`)
│
├── eidos/ # [THE LIVING SPECIFICATION / DOGFOODED CATALOG]
│ ├── system.adoc # Root system descriptor (SYS-*)
│ ├── personas/ # Human & AI actor roles (PER-*)
│ ├── policies/ # Non-negotiable architectural policies (POL-*)
│ ├── domains/ # Bounded contexts (DOM-*) & capabilities with test-bound invariants (CAP-*, INV-*)
│ ├── architecture/ # Arc42/C4 architecture (ARCH-*), containers (CNT-*), components (CMP-*), contracts (CTR-*)
│ ├── design/ # Multi-Design Systems (DS-*), W3C tokens, UI components (UIC-*), clients (CLT-*), screens (SCR-*), flows (FLOW-*)
│ ├── explorations/ # Hypothesis-driven technical spikes (EXP-*) & archive/
│ └── deltas/ # Active and recent SpecDelta mutations (DLT-*) & archive/
│
├── docs/ # User documentation site (Zensical)
└── tests/ # Engine & invariant verification test suites
| Dimension | Traditional / Existing Tools | Eidos Approach |
|---|---|---|
| Scope | Coding loop only (Aider, Claude Code) or monolithic bot (Devin) | Full SDLC: Exploration → Product Baseline → SpecDelta → Code → CI |
| Specifications | Ephemeral Jira tickets, stale Confluence/Notion pages | Versioned YAML frontmatter + AsciiDoc living in Git |
| Change Management | Narrative RFC essays that rot in archive folders | Declarative SpecDelta mutations applied automatically upon merge |
| Agent Support | Vendor-locked to a single proprietary LLM | Agent-agnostic via agentskills.io CLI-first Agent Skills across 9 coding clients |
| VCS Support | Tied to a single SaaS platform or closed web UI | 100% Git-native local repository engine |
- Root System:
eidos/system.adoc - Product Domains:
- Policies:
- Technical Architecture:
- SpecDeltas:
- User Documentation: https://mchawa.github.io/eidos/
- Interactive Living Architecture Portal: https://mchawa.github.io/eidos/portal/
- PyPI Package: https://pypi.org/project/eidos-ai/
- AI Agent Plugin Guide: https://mchawa.github.io/eidos/guides/agent-plugin/
Licensed under the MIT License.