A personal, portable team of AI agents. Each is a named specialist with its own methodology, identity, and boundaries. They work alone when the task is sharp; they work in harmony when the task is big; they travel together, from project to project, codebase to codebase, host to host.
Most AI coding tools ship a single generalist that tries to plan, scout, build, and document all at once — a ceiling that arrives fast. Eidolons is a different shape: six independently-versioned specialists, one CLI, drop into any project. You get sharp boundaries instead of one confused generalist — plan, build, document, debug, and reason with the right specialist for each phase. They travel with you across projects and hosts (Claude Code, Copilot, Cursor, OpenCode, Codex).
Evaluation, not commitment — this drops a read-only ATLAS into a throwaway folder:
curl -sSL https://raw.githubusercontent.com/Rynaro/eidolons/main/cli/install.sh | bash
cd /tmp && mkdir eidolons-demo && cd eidolons-demo
eidolons init --preset minimal --non-interactiveExplore, then rm -rf /tmp/eidolons-demo and walk away. For the full install flow, see Install below.
| Eidolon | What it does for you | When to reach for it | Repo | Latest |
|---|---|---|---|---|
| ATLAS A→T→L→A→S |
Maps an unfamiliar codebase without writing a single line. Evidence-anchored findings, read-only by construction. | Auditing a new repo, onboarding, before any change. | Rynaro/ATLAS | 1.2.2 |
| SPECTRA S→P→E→C→T→R→A |
Turns a scout report or rough idea into a decision-ready spec — scoring rubrics, validation gates, GIVEN/WHEN/THEN stories. | Planning a feature before you build it. | Rynaro/SPECTRA | 4.2.10 |
| APIVR-Δ A→P→I→V→Δ/R |
Implements features in brownfield code — pattern-first, test-anchored, bounded failure-recovery loop. | Shipping the change SPECTRA planned. | Rynaro/APIVR-Delta | 3.0.5 |
| IDG I→D→G |
Synthesizes documentation from sessions, specs, and deltas — provenance-first, with [GAP] / [DISPUTED] markers. |
Chronicling what you (or the team) just built. | Rynaro/IDG | 1.1.5 |
| FORGE F→O→R→G→E |
Deliberates on ambiguous trade-offs and novel problems. Names alternatives, surfaces assumptions, returns verdict + confidence. | Two patterns apply and the choice isn't obvious. | Rynaro/FORGE | 1.2.1 |
| VIGIL V→I→G→I→L |
Forensic debugger for failures resistant to normal repair. Reproduction-gated, counterfactual-verified, dependency-graph-ranked. | Flaky test, heisenbug, or a regression you can't explain. | Rynaro/VIGIL | 1.0.3 |
Versions and detailed handoff contracts live in roster/index.yaml — the machine-readable source of truth.
The team has a default shape: ATLAS scouts, SPECTRA plans, APIVR-Δ builds, IDG chronicles. FORGE and VIGIL are lateral specialists — consultable at any stage, not always in-line. Partial teams are first-class; bring just ATLAS to an audit, the full pipeline to a greenfield, or any slice that fits your project. See methodology/composition.md#partial-team-deployment for the full matrix and common configurations.
Canonical pipeline
ATLAS ───▶ SPECTRA ───▶ APIVR-Δ ───▶ IDG
scout plan build chronicle
▲ │ ▲
│ │ │
FORGE ◀─── (ambiguity, trade-offs, novel problems)
│ │
VIGIL ◀─── (failure resisted repair; forensic attribution)
Handoffs between members are structured artifacts written to disk — not free-form messages. See methodology/composition.md for the handoff contract table and invariants.
One-time, global:
curl -sSL https://raw.githubusercontent.com/Rynaro/eidolons/main/cli/install.sh | bashThis installs the eidolons CLI to ~/.local/bin/eidolons and caches the nexus at ~/.eidolons/nexus.
Per project — works on empty folders or running projects:
cd <any-project>
eidolons init # interactive — choose members and preset
eidolons add forge # add a single member later
eidolons sync # reconcile installed members to eidolons.yaml
eidolons verify # re-check installed Eidolons against the roster's signed metadataKeep the nexus itself up to date with:
eidolons upgrade self # upgrade to latest stable nexus release
eidolons upgrade self --check # read-only: see what would change, no writes
eidolons upgrade self --rollback # revert to the previous install (nexus.prev)upgrade self is atomic and rollback-safe: it clones the new version alongside your current install, verifies integrity (commit SHA, tree SHA, archive SHA-256 from roster/index.yaml), runs a smoke test, then renames atomically. On any failure before the rename, the candidate is discarded and your current install is untouched. The previous install is retained as ~/.eidolons/nexus.prev for one-step rollback.
To upgrade installed Eidolons (ATLAS, SPECTRA, etc.), use eidolons upgrade (no self) — see the CLI reference.
MCP server scaffold (Atlas-ACI). If you use the Atlas-ACI code-graph MCP server alongside ATLAS, run the nexus scaffold step once per project before starting the MCP server. It writes a per-project .mcp.json with the correct bind-mount paths and pre-creates .atlas/memex/ so the sqlite codegraph DB has a writable host-side surface — skipping this step is the most common cause of sqlite3.OperationalError: unable to open database file on fresh clones.
eidolons mcp atlas-aci [--force] [--image-digest <sha256>]If the image isn't on your host yet, run eidolons mcp atlas-aci pull first; the generator refuses to write .mcp.json until the image is loadable. Use --skip-image-check only in CI where the image is loaded after scaffolding. If eidolons atlas aci --install ever fails with the in-container index error, run eidolons doctor to diagnose; the most common cause is a missing or unwritable .atlas/memex/ directory.
Note that atlas-aci is an external Python MCP package (a tool Eidolons consume); it is not an Eidolon and does not appear in roster/index.yaml. The atlas Eidolon (scout methodology) and the atlas-aci MCP server are distinct — see docs/architecture.md for the boundary.
Commit eidolons.lock alongside eidolons.yaml — the lockfile pins resolved versions and integrity checksums (commit, tree, archive_sha256, manifest_sha256) for reproducible, tamper-evident installs. For the full flow, read docs/getting-started.md.
Every shipped Eidolon publishes attestation-backed releases through a canonical workflow (eidolon-release-template.yml) hosted in this nexus. Each release records its commit, tree, and archive SHA-256 into roster/index.yaml via Roster Intake, with GitHub artifact attestations bound to the canonical signer workflow.
eidolons sync and eidolons verify enforce that contract on the consumer side. Under the default integrity.enforcement: strict posture, any installed Eidolon whose commit/tree/archive checksum drifts from the roster's signed metadata aborts with exit 1 — same gate Roster Health runs nightly against every shipped Eidolon. Read the trust model end-to-end at docs/release-integrity.md.
Nexus releases use the same commit/tree/archive-SHA-256 model. Each eidolons upgrade self re-verifies the downloaded nexus against the nexus.versions.releases.<v> block in roster/index.yaml before swapping it in. The release workflow (.github/workflows/release-nexus.yml) produces these artefacts automatically on each vX.Y.Z tag.
Auto-merge of routine roster bumps. Roster bumps that pass attestation verification + required checks now auto-merge once Roster Intake opens the PR (via gh pr merge --auto --squash). First-shipped Eidolon transitions are held as DRAFT for manual review. Bad merges revert with git revert <merge-sha>; the next nightly roster-health re-validates. See docs/release-integrity.md § "Auto-merge of routine roster bumps".
| Area | What it contains |
|---|---|
roster/ |
Machine-readable registry of every Eidolon, their versions, repos, handoff contracts |
methodology/ |
Aggregated design principles, composition contracts, vocabulary |
research/ |
Papers, citations, production patterns, scientific backing |
cli/ |
The eidolons command-line tool — installs and orchestrates the team |
schemas/ |
JSON Schemas for eidolons.yaml, eidolons.lock, roster entries |
docs/ |
Getting started, architecture, CLI reference |
examples/ |
Worked examples: greenfield, brownfield, solo-member, partial-team |
Each Eidolon is independently installable and independently versioned — that's a hard design invariant. The nexus exists because:
- Discovery. Without a roster, nobody knows which Eidolons exist or how they relate.
- Composition. The team is more than the sum of its members. Handoff contracts, pipeline conventions, and partial-team deployment patterns live here, not in any individual Eidolon's repo.
- Research. The scientific backing for the whole program — papers, production precedents, evidence-to-design mappings — is a shared asset. Duplicating it across five repos is wasteful and drifts.
- Installation orchestration. A single
eidolons add atlas,spectra,apivris worth fifty lines of documentation explaining how to clone three repos and run three installers. - Supply-chain integrity. The release-integrity contract is a shared asset: one canonical signing workflow (
eidolon-release-template.yml) every Eidolon adopts, one ingestion path (Roster Intake) that verifies attestations, one consumer-side gate (eidolons verify) that enforces them. Six independent repos with six independent signing schemes would defeat the trust model.
Each Eidolon remains a first-class repo. This nexus is a coordinator, not an owner. The four-layer architecture (install standard → Eidolon repos → this nexus → consumer project) is documented in docs/architecture.md.
- Nexus CLI self-versioning +
eidolons upgrade self— the nexus now carries a realVERSIONfile and release process.eidolons --versionreports version + commit SHA + install date + source ref.eidolons upgrade selfreplaces the re-curl flow with an atomic, integrity-verified, rollback-safe upgrade. See CHANGELOG.md. - Ecosystem normalized — supply-chain integrity end-to-end. All six shipped Eidolons (ATLAS, SPECTRA, APIVR-Δ, IDG, FORGE, VIGIL) now publish attestation-backed releases via the canonical
eidolon-release-template.yml. Everyversions.releases.<v>block inroster/index.yamlcarriescommit,tree,archive_sha256, and a GitHub-signed provenance attestation, ingested viaRoster Intake.integrity.enforcementisstrictby default — any consumer install with a checksum mismatch aborts with exit 1. Seedocs/release-integrity.md. - ATLAS v1.3.0 — registry-prefixed canonical body for
eidolons atlas aci --container; container-runtime security hardening. See CHANGELOG.md. eidolons upgradeis fully implemented —--checkfor read-only diffs, applies member upgrades withineidolons.yamlSemVer constraints, idempotent on repeat runs. See CHANGELOG.md.- EIIS bumped to v1.1 with an external standalone conformance checker. See Rynaro/eidolons-eiis.
The Eidolons Individual Install Standard (Rynaro/eidolons-eiis) defines the contract every Eidolon repo satisfies — file layout, install.sh interface, manifest schema.
This nexus (Rynaro/eidolons) depends on EIIS. Every Eidolon listed in roster/index.yaml must be EIIS-conformant; the CLI refuses to install non-conformant members.
They version independently. EIIS v1.x is the contract; eidolons v1.x is the orchestrator.
Per-Eidolon bugs and feature requests belong in that Eidolon's repo (e.g. an ATLAS finding goes to Rynaro/ATLAS, not here). CLI bugs, roster issues, and composition-contract changes belong in this repo (Rynaro/eidolons). Questions about the install standard itself belong in Rynaro/eidolons-eiis. If you're unsure which layer owns a concern, docs/architecture.md maps the four layers and their responsibilities.
Apache-2.0. See LICENSE.