Eidos by mayneyao: a single-file SQLite spreadsheet for you and your agent

What Eidos File is, and the problem it picks up

Most spreadsheets store a cell as a string and leave meaning to the person reading it. Most databases store types and relations but make you run a server and write migrations. Eidos File sits between the two. It is an open, single-file format built on standard SQLite, and the README describes it as a relational spreadsheet. That means fields carry types, tables can relate to each other, and the whole thing is one file you can move, copy or keep in a folder.

The audience is narrower than a general spreadsheet. It is for someone who wants a personal library, a task list or a small dataset with relations, wants it to stay local, and wants a program to be able to read and write it. The README points at two entry points for that person: Eidos Lite, the desktop app, and the eidos CLI, which the README frames around agent and automation workflows. The browser editor at editor.eidos.space covers the case where you do not want to install anything.

Where it is not a fit: the README does not describe any hosted collaboration, sharing or access-control model. A team that needs concurrent editing by people who are not on the same machine is not the target here.

How the format, the runtime and the editor UI are split

The repository layout is unusually explicit about the split, and that split is the most interesting design decision in the project. packages/eidos-file implements the format and the Runtime. packages/eidos-file-ui provides the shared React editor UI. The desktop app in apps/eidos-lite-desktop and the browser editor in apps/eidos-file-web both sit on top of those two packages rather than each carrying their own table logic.

There is a second shared piece. packages/markdown provides a Lexical-based WYSIWYG editor for what the README calls Eidos Flavored Markdown. The README is specific about the contract: markdown remains the canonical value, and the package owns import, editing, serialization, fidelity checks and its plugin API, while hosts own persistence and attachment storage. That is a clean boundary, and it explains why there is a separate apps/markdown-editor-playground for isolated development and compatibility work on the editor.

Two more entries round out the picture. apps/cli contains the agent-first CLI and local server. apps/sqlite-web-viewer is a standalone, read-only SQLite viewer. Version history and optional Sync come from Graft, which the README describes as an independent, developer-facing version-control system for application state, used rather than reimplemented. The consequence for a reader: the interesting reusable parts are the two MIT packages, and the app is the assembly.

Installing the eidos CLI and creating your first .eidos file

The README gives three ways in. The desktop app is a download from eidos.space, with no account required for local use. The browser editor needs no install at all. The CLI is the one with copyable steps, and it is the path worth taking first because it shows you what the file actually is.

On macOS or Linux the README gives a shell installer:

curl -fsSL https://download.eidos.space/cli/install.sh | sh

On Windows the equivalent is PowerShell:

irm https://download.eidos.space/cli/install.ps1 | iex

After installing, the README's own example creates a file with one table and two typed fields. The --label-field flag names the field used as the record label, and --fields takes JSON describing the schema:

eidos create example.eidos \
  --table Tasks \
  --label-field Title \
  --fields '[{"name":"Title","type":"text"},{"name":"Status","type":"select"}]'

Then serve it locally and open it:

eidos serve example.eidos --open

What you should see is a local server that opens the file in a viewer. The README lists the CLI's verbs as create, inspect, query, update and serve, so after the first create you can go back at the same file with inspect or query rather than opening the app. Because the format is standard SQLite, the same file is also readable by ordinary SQLite tooling, and the repository ships apps/sqlite-web-viewer as a read-only viewer if you want to look at the raw structure without the Eidos UI in the way.

Local version history is delegated, not built in

One thing the README does not present as a feature of the format itself is history. Eidos Lite uses Graft for local version history and optional Sync, and Graft is described as an independent, developer-facing version-control system for application state. So version history is a property of the app, not of the .eidos file.

That has a practical consequence. If you drive the file from the CLI or from your own code, the README does not say that Graft is in the path. A script that updates rows is writing to a SQLite file; nothing in the README suggests the CLI records a revision for you. Anyone who wants undo or history outside the desktop app should check the CLI guide in apps/cli/README.md before assuming it is there, because the top-level README is silent on it.

The .graftignore file at the repository root is a hint that Graft has its own ignore semantics, but the README does not document what belongs in it for an Eidos project. Treat history as an app-level convenience until the specs under docs/specs say otherwise.

Limits, and the cases where a plain SQLite file wins

The clearest limitation is maturity of the contract, not of the code. The default branch is dev. The README points readers at the normative Eidos File specifications in docs/specs for detail, which implies the format is specified, but it does not promise stability across releases, and there is no compatibility statement in the README. If you are building something that must keep reading files written by a future version, that is a risk you are taking on.

Second, the licensing is split in a way that matters to some users. The repository is AGPL v3, while the reusable packages @eidos.space/eidos-file and @eidos.space/eidos-file-ui are released under MIT. That is a deliberate separation: the format implementation is meant to be embedded, the application is not. Anyone planning to ship a modified Eidos Lite should read the LICENSE file rather than assume the MIT terms extend to the app.

Third, and this is the honest case against it: if your data is flat, has no relations, and will never be touched by a program, a plain SQLite file with a schema you wrote yourself is simpler. Eidos adds a field-type system, an editor and a runtime. If you do not want those, you are carrying them for nothing. Likewise, if what you actually need is a hosted, multi-user database, this is the wrong tool, and the README does not pretend otherwise.

Compared with a Notion-style workspace

The repository tags include notion-alternative, so the comparison is fair to make. The difference is in where the data lives and what shape it is in. A Notion-style workspace keeps your tables on someone else's servers and gives you an API to reach them. Eidos keeps the table in a file you hold, in SQLite, and gives you a CLI and a desktop app.

That changes the failure modes rather than removing them. You do not depend on a service being up, and you do not need an account for local use, which the README states explicitly. In exchange, you own backup, you own moving the file between machines, and you own any sync you want beyond the optional Sync the README mentions through Graft. There is no README claim about how Sync behaves, so do not read the word as a promise of a hosted service.

The second difference is the agent angle. The README's framing, a single-file relational spreadsheet for you and your agent, and the description of apps/cli as agent-first, suggest the CLI is meant to be the interface a model calls. A file path and a set of verbs is a much smaller surface for a tool to drive than a web API with authentication. That is the strongest argument for Eidos over a hosted workspace, and it is also the part of the project with the least documentation in the top-level README.

Editorial conclusion

Adopt Eidos if you want a relational, typed table that lives in one .eidos file on your disk and you are comfortable driving it from a CLI or a desktop app; the format is plain SQLite underneath, so an existing SQLite toolchain can read what you make. Do not adopt it if you need a hosted multi-user service, or if you want a stable schema contract, because the repository is on the dev branch and publishes no compatibility guarantees. Before committing, open the normative specs under docs/specs and confirm the field types and relation semantics you need are specified there, then run eidos create on a scratch file and inspect it with the read-only sqlite-web-viewer app to see exactly what the format writes.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. mayneyao/eidos on GitHub
3. Project website
4. README
5. Releases