EpiphanyAgent

Epiphany is an opinionated fork of Codex built around one demand: the model must model the thing it is changing.

The problem this repo is chasing is not "LLMs can't write code." They can. The problem is that they can keep making plausible local moves after the global design has already wandered off and died in a ditch.

Epiphany answers that by moving important state out of transcript fog and into typed, inspectable surfaces: maps, evidence, retrieval state, graph/frontier state, churn pressure, and compact client reflections. The goal is not maximal output. The goal is a machine whose parts visibly deserve to exist.

Project Direction

Epiphany is moving toward project-native agency.

The user should not have to write a perfect brief, name every subsystem, and pre-plan the code flow for the whole architecture before the machine can help. That is just outsourcing project management to the human and calling the agent smart because it waited politely.

The intended shape is simpler and stranger: you talk to the project.

Each Epiphany owns one or more repos, carries durable memory and jurisdiction for them, and can grow one or more Faces. A Face is the public mouth and situated personality of that project: visible in Aquarium, addressable in Discord, suitable for voice or stream presence, and backed by the same typed state, heartbeat initiative, repo map, evidence, and review gates as the rest of the swarm.

VoidBot is already showing the small version: repo identities such as Nibu, Aqua, and Mimir have Discord roles, repo-local Face state, proposal authority, pending mentions, and heartbeat turns. Epiphany is the larger native substrate: projects should notice pressure, ruminate, ask questions, schedule modeling or verification, advocate for their own repo needs, and structure work without requiring the human to spell out the implementation graph first.

Aquarium is the most direct client because it can show the swarm, its Faces, its heartbeat, its memories, and its decisions. It is not the only mouth. A project should also be reachable through Discord, voice/WebRTC surfaces, stream overlays, native CLIs, and CultNet-speaking tools. The interface contract is not "prompt an agent." It is "speak to the project; inspect how it thinks; grant or refuse authority when it wants to act."

What Exists Now

The current spine is real, not aspirational:

• durable EpiphanyThreadState in the vendored Codex protocol/core session
• rollout snapshots and replay for resume, rollback, fork, and compaction
• bounded <epiphany_state> prompt injection
• typed client reads through Thread.epiphanyState
• read-only retrieval through thread/epiphany/retrieve
• explicit semantic indexing through thread/epiphany/index
• durable typed writes through thread/epiphany/update
• read-only observation distillation through thread/epiphany/distill
• read-only map/churn proposal through thread/epiphany/propose
• verifier-backed promotion through thread/epiphany/promote
• successful-write notifications through thread/epiphany/stateUpdated
• durable jobBindings as a thin Epiphany-owned launcher seam over runtime job backends
• explicit launch and interrupt authority through thread/epiphany/jobLaunch and thread/epiphany/jobInterrupt, still backed by runtime agent_jobs
• a bounded reorient-guided worker launch through thread/epiphany/reorientLaunch
• read-only CRRC next-action recommendations through thread/epiphany/crrc
• live bound-job progress notifications through thread/epiphany/jobsUpdated
• read-only reflection surfaces through thread/epiphany/scene, jobs, freshness, context, pressure, and reorient
• a first dogfood CLI operator view through tools/epiphany_mvp_status.py, including explicit implementation, modeling/checkpoint, verification/review, and reorientation lanes
• durable investigation checkpointing for compaction-safe planning
• Ghostlight/VoidBot-derived heartbeat initiative with heat, active-turn freeze, idle rumination, sleep/dream maintenance, and Face as a first-class public-surface participant
• repo personality/birth initialization that can seed role dossiers and heartbeat pressure from repo terrain before a project starts speaking
• CultNet schema contracts for runtime, heartbeat, Face, character-turn, Discord-persona, repo-initialization, Rider, Unity, and operator surfaces
• repo-owned heavy Epiphany organs in epiphany-core/, with vendored Codex kept as the host seam where practical

Phase 1 through Phase 6 are landed enough for the current experiment. The open questions are now about observability, invalidation, coordination, authority, and safe capability growth, not whether typed state can exist at all.

Where This Leads

The architectural goal is not one giant agent that does archaeology, design, patching, and self-grading in a single token fog. It is also not a chat box where the human must already know the solution architecture before asking.

The goal is a maintained project organism:

• graph and source-modeling agents keep the machine map current
• freshness, watcher input, pressure, and reorientation signals decide whether that map still deserves trust
• verifier agents check claims, diffs, and outcomes against reality
• coding agents work from bounded packets of graph context, evidence, code refs, and local source reads instead of re-spelunking the repo from scratch every turn
• Faces translate project state into conversation, voice, stream presence, and Discord/Aquarium discussion without becoming omniscient hidden operators
• initiative scheduling decides which repo, Face, or internal organ should think next, and heat lets the operator turn up one agent, one project, one group, or the whole swarm

That still leaves direct source reading where it belongs: at the last mile, when a patch has to be grounded in the real files. The difference is that broad exploration, coherence maintenance, social interface, scheduling, and verification stop living in the same overworked skull.

Repo Tour

If you want the human-readable map of the project, start here:

• notes/architecture-rationale.md: why the map/scratch/evidence architecture exists
• notes/epiphany-current-algorithmic-map.md: source-grounded control flow of the live machine
• notes/epiphany-fork-implementation-plan.md: distilled forward plan
• notes/epiphany-safety-architecture.md: capability, authority, interruption, and anti-cage doctrine
• state/map.yaml: canonical current project map and accepted design

If you want the code:

• epiphany-core/: repo-owned Epiphany logic
• vendor/codex/: vendored Codex host substrate
• tools/: smoke tests and state helpers

If you are an agent or you are steering one, read AGENTS.md. That file is for operating discipline, re-entry protocol, and session hygiene. The README is for people, which is a lower-crime use of everyone's time.

Design Stance

Epiphany is built on a few stubborn ideas:

• externalized state is better than pretending the transcript is a brain
• local plausibility is not the same thing as global coherence
• evidence should survive, but activity feed sludge should not
• cognition should grow faster than authority
• interruption, legibility, and explicit permissions matter more as the machine becomes more coherent

This repo is not trying to make the model louder. It is trying to make it less likely to build a Jenga tower and call it understanding.

License

The root LICENSE is the operative repository notice. In short: vendor/codex/** and other third-party material keep their upstream licenses; project-authored material outside vendor/codex/** is publicly available under PolyForm Noncommercial 1.0.0 and is intended to be available under separate commercial terms by written agreement.

External contributions require CONTRIBUTOR_LICENSE_AGREEMENT.md or a separate written agreement accepted by the project steward.

The publishing stance is:

• FOSS where that is viable
• source-available where the economics or capability profile make unrestricted release a bad idea
• commercial terms where organizations are extracting real enterprise value