Evidence, not claims.
An autonomous, multi-tenant, AI-native software factory
Most AI tools tell you what they did. Eva writes it down first.
Every question you ask, every answer that comes back, every retry, and every token counted is appended to a file on your disk as it happens. What you see on screen is read back out of that file. If Eva shows you an answer, the file already had it. There is no second version of events.
That sounds like a small thing. It is the whole design.
$ eva
EVA
Evidence, not claims
version 0.1.0+e839c8a
model claude-sonnet-4-5
branch main
cwd ~/code/eva
type /help for slash commands
› what's the difference between a cache write and a cache read?
A cache write stores your prompt prefix so later calls can skip re-reading
it. A cache read is one of those later calls hitting the stored copy…
› /cost
session 1.2k in / 340 out · cache 2.0k write / 1.1k read · cost unreported
Notice cost unreported
. Neither Anthropic nor OpenAI returns a dollar figure with a response. So Eva says so, rather than multiplying tokens by a price it looked up somewhere. A number you can argue with a bill about has to come from the bill.
Note
Eva is early. Today it is a good terminal chat client with a very carefully built foundation. It can read your question and answer it. It cannot read your files, run your tests, or touch your shell — there are no tools yet.
Eva is being built toward a control plane for coding agents. Work arrives as a spec with acceptance criteria a machine can check. Several harnesses race the same spec in isolated environments. A verifier Eva owns decides what actually passed, and the whole race is scored from the same record everything else is scored from.
The reason for building the foundation this carefully first is the ladder in docs/explanation/the-ladder.md. The usual story goes model → agent → harness → factory. That chain skips five rungs, and each omission is a known way this fails:
| The rung that gets skipped | What breaks without it |
|---|---|
| Workflow | |
| Control flow is handed to the model before the model can hold it | |
| Environment + verifier | |
| Nothing tells the agent it is wrong, so it never converges | |
| Scheduler + spec format | |
| More agents is not a factory. A factory needs a queue and a spec | |
| Learning loop + economics | |
| No evals, and no cost per merged change | |
| Intent + authority | |
| Nobody owns what was decided, and nobody answers for it |
Nineteen stages, each with an exit test it can fail. One of them is built. The plan is a draft; the stage that shipped is not.
You need Go 1.26 or newer. Nothing else.
git clone git@github.com:missingstudio/eva.git
cd eva
go build -o eva ./cmd/eva
That produces a single binary in the current directory. Put it on your PATH
if you want it everywhere.
Eva talks to Anthropic and OpenAI. Pick one.
export ANTHROPIC_API_KEY=sk-ant-...
./eva
That's the whole setup. Anthropic is the default, so nothing needs configuring.
For OpenAI, create a settings file and name the provider:
./eva init # writes ~/.eva/config.toml
export OPENAI_API_KEY=sk-...
[provider]
name = "openai"
One line is enough. The model and the key variable follow the provider you picked, so you get gpt-5.6-terra
reading OPENAI_API_KEY
without saying either out loud.
If you pay OpenAI monthly, you can use that instead of an API key:
./eva login
It prints a URL and a short code, you approve it in a browser, and the credential is saved to ~/.eva/auth.json
. Then set the mode in ~/.eva/config.toml
:
[provider]
name = "openai"
auth = "subscription"
Check what Eva will actually use at any time:
./eva auth status
provider: openai
auth: subscription
store: /Users/you/.eva/auth.json
login: account acct_1a2b, valid until Mon, 11 Aug 2026 09:14:00 IST
Important
** auth decides, and nothing overrides it.** If it says
subscription
, an exported OPENAI_API_KEY
is ignored, and eva auth status
will tell you so rather than quietly using it. Most tools try the environment first, which is how people bill the wrong account for a month without noticing. (why)
Your key is never written to a settings file. Eva reads it from the environment, or gets it when you log in. It never appears in the history file, a log, or anything sent to a model.
Run eva
with no arguments and type. Answers stream in as they arrive.
| Key | What it does |
|---|---|
| enter | |
| Send | |
| shift+enter or alt+enter | |
| New line without sending | |
| ctrl+c | |
| Stop the answer in progress, keep what you typed | |
| ctrl+d | |
| Quit | |
| tab | |
| Finish a slash command | |
| shift+↑ ↓, pgup pgdn | |
| Scroll back | |
| ctrl+home / ctrl+end | |
| Jump to the top / back to live |
Interrupting is safe. The conversation stays usable and the history file records that you stopped it.
Type /
at the start of a line. These are handled locally and never reach a model, so they cost nothing.
| Command | What it does |
|---|---|
/help |
|
| List the commands | |
/cost |
|
| What this conversation has cost so far | |
/clear |
|
| Start a fresh conversation | |
/model |
|
| Show which model is answering | |
/model gpt-5.6-terra |
|
| Switch models, keeping the conversation | |
/login |
|
| Explains that logging in happens outside the chat |
/model
swaps the model mid-conversation without dropping context, so the next answer still knows what you talked about. Eva doesn't keep a list of valid model names, because a list compiled last month would reject a model released last week. If the provider doesn't recognise the name, that answer fails and tells you.
/clear
starts a new conversation rather than deleting messages from the current one. Your old messages are still in the history file either way. (why)
eva -p
answers one question, prints it to stdout, and exits.
eva -p "explain this error" > answer.md || echo "that failed"
It exits non-zero when the answer failed, and writes the reason to stderr. That makes it safe to use in a pipeline: stdout is the answer and nothing else.
› what is this?
No response — the credential was refused
provider.auth is "api_key", so what anthropic refused is the key in
$ANTHROPIC_API_KEY
Two lines, both true. The first names the kind of failure, in Eva's own words rather than the vendor's error document. The second appears only when Eva checked something about your machine, and only when that fact leaves exactly one next step. A missing login says run eva login
because that is certainly the fix. A refused key says which key was sent and stops, because revoked, wrong organisation, and suspended account all look identical from here. Sending you to fix something that was never broken costs you every later hint that would have been right. (why)
| Command | What it does |
|---|---|
eva |
|
| Open the chat | |
eva -p "<question>" |
|
| Answer once, print to stdout, exit | |
eva init |
|
| Write a starter settings file | |
eva login |
|
| Sign in to a subscription | |
eva auth status |
|
| Show how Eva will authenticate | |
eva help |
|
| Show this list |
Two flags, and that's deliberate: --config <path>
picks a settings file, -p <question>
asks one question. Everything else is a setting, because settings are reviewable and flags are not.
| Environment variable | What it's for |
|---|---|
ANTHROPIC_API_KEY |
|
| Your Anthropic key | |
OPENAI_API_KEY |
|
| Your OpenAI key | |
EVA_CONFIG |
|
A different settings file (default ~/.eva/config.toml ) |
|
EVA_HOME |
|
A different home for Eva's files (default ~/.eva ) |
eva init
writes ~/.eva/config.toml
with every option present but commented out, and a note beside each saying what happens without it. Nothing is chosen for you. Uncomment a line to change it.
Here is what Eva does with none of it written down:
model = "claude-sonnet-4-5" # follows the provider if you leave it out
[provider]
name = "anthropic" # anthropic or openai
auth = "api_key" # api_key or subscription
api_key_env = "ANTHROPIC_API_KEY"
base_url = "" # a proxy, gateway, or local server
max_tokens = 0 # 0 lets the provider decide
[trace]
path = "~/.eva/trace.jsonl" # where the history goes
kind = "jsonl" # which writer keeps it
[identity]
tenant = "local"
actor = "local"
actor_kind = "human" # human, agent, or system
Colours, glyphs, spacing, and key bindings live under [theme]
and [keymap.bind]
, and the starter file lists those too. Set none of them and Eva looks exactly as it did before any of it was configurable. Colours follow your terminal's background and what it can display, so it fits in without being told.
Settings are read from four places, each overriding the one before: built-in defaults, your file, the project's file, then --config
. Eva works fine with none of them.
A typo is an error, not a shrug. Write modl = "..."
and Eva refuses to start and names the key. A settings file that silently ignores what you wrote is worse than one that won't load.
A repo can carry .eva/config.toml
, found by walking up from wherever you are. Handy for sharing a team's look:
[theme.colors]
person = "#7AA6DC"
[theme.symbols]
prompt = "› "
[keymap.bind]
follow = ["ctrl+g"]
Warning
A repo can change how Eva looks, never what it does. You clone a repo from the internet, and Eva reads that file before your first question, in a process holding your API key. So the list of what it may set is a short allow-list: appearance and key bindings. It cannot pick the model provider, point traffic at another server, rename the variable your key is read from, or move your history file. Anything else in that file is refused by name. (why)
Eva is strict about naming, because the same concept under three names is how a codebase rots. Five of them show up in the docs and the code:
| Word | Plain English |
|---|---|
| Session | |
| One conversation. Survives a crash. What resume and rewind will act on. | |
| Run | |
| One question and its answer. A conversation has many. | |
| Turn | |
| One round trip to the model. A single Run may need several once tools exist. | |
| Trace | |
| The history file. The single source of truth for what happened. | |
| Provider | |
| A model behind one interface: Anthropic, OpenAI, whatever comes next. |
The full list is CONTEXT.md, including the words that were tried and retired.
One Go module. Data flows one way, and the compiler enforces it.
you type you read
│ ▲
▼ │
┌──────┐ ┌──────┐ ┌───────────┐ ┌────────┐
│ tui │───▶│ loop │───▶│ providers │ │ render │
└──────┘ └──┬───┘ └───────────┘ └───▲────┘
│ │
▼ committed first │
┌───────┐ ───────────────────────────┘
│ trace │ then shown
└───────┘
The important part is the bottom. Nothing reaches your screen that didn't go through the file first. The rendering layer physically cannot talk to a model, a conversation, or the history file. It takes records and returns strings, and that's all it's allowed to import.
| Package | What lives there |
|---|---|
events |
core
trace
config
auth
providers
anthropic
and openai
.loop
render
,theme
tui
cli
Those boundaries are an allow-list per package in .golangci.yml, running in strict mode. An import nobody explicitly permitted fails the build. Widening a list is a visible line in a diff with a reason next to it, not something that happens by accident.
Three decisions do most of the work:
A provider only knows how to dial, read a chunk, and hang up. Queueing, retrying, and counting are written once and shared. Adding a provider is a few hundred lines, not a copy of the machinery. (0034)Things register themselves. Providers and file writers add themselves to the set that settings choose from. So the wiring layer names no implementation, and the error listing your options cannot go stale. (0028)The screen is a read-only view. It renders records and nothing else. (0015)
make check
That is exactly what CI runs: formatting, build, vet, lint, tests, every package.
| Target | What it does |
|---|---|
make check |
|
| Everything below, in order | |
make fmt |
|
| Fails if anything isn't gofmt-clean | |
make lint |
|
| golangci-lint, where the package boundaries are enforced | |
make test |
|
| Every package | |
make eva |
|
| Build the binary into the repo root | |
make tidy |
|
| Tidy dependencies |
The linter version is pinned and run via go run
, so you don't install anything and your results match CI.
Tests drive the real Anthropic and OpenAI code against a local server speaking the real protocol. There's no mock provider, because a mock is a second implementation that can disagree with the first and be believed. (0036)
|
docs/how-to/docs/Product.mddocs/roadmap.mddocs/decisions.mddocs/adr/ls
is the index.CONTEXT.mdAGENTS.mddocs/agents/design-rules.mddocs/agents/project-structure.mdNothing in docs/adr/
is ever rewritten or deleted. When a later decision overturns an earlier one, the old file says so in its own status line and stays. Being wrong is part of the record too.
MIT. See LICENSE.