<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/eeco_logo_dark.png">
    <img src="assets/eeco_logo_light.png" alt="eeco" width="420">
  </picture>

<h3>Single-binary workflow ecosystem and knowledge layer for any AI assistant.</h3>

<p>
    <a href="https://github.com/ajhahnde/eeco/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/ajhahnde/eeco/ci.yml?branch=main&style=flat-square&label=ci" alt="CI"></a>
    <a href="https://codecov.io/gh/ajhahnde/eeco"><img src="https://img.shields.io/codecov/c/github/ajhahnde/eeco?style=flat-square&label=coverage" alt="Coverage"></a>
    <a href="https://github.com/ajhahnde/eeco/releases/latest"><img src="https://img.shields.io/badge/version-v0.2.1-3b82f6?style=flat-square" alt="Version"></a>
    <img src="https://img.shields.io/badge/go-1.24-lightgrey?style=flat-square" alt="Go 1.24">
    <img src="https://img.shields.io/badge/binary-single--static-lightgrey?style=flat-square" alt="single-static binary">
    <img src="https://img.shields.io/badge/license-Apache--2.0-lightgrey?style=flat-square" alt="License">
  </p>

<p>
    <b>README</b> ·
    <a href="VISION.md"><b>Vision</b></a> ·
    <a href="docs/COCKPIT.md"><b>Cockpit</b></a> ·
    <a href="docs/USAGE.md"><b>Usage</b></a> ·
    <a href="docs/ARCHITECTURE.md"><b>Architecture</b></a> ·
    <a href="docs/PUBLIC_API.md"><b>Public API</b></a> ·
    <a href="EXTENDING.md"><b>Extending</b></a> ·
    <a href="CONTRIBUTING.md"><b>Contributing</b></a> ·
    <a href="docs/UPGRADING.md"><b>Upgrading</b></a> ·
    <a href="VERSIONING.md"><b>Versioning</b></a> ·
    <a href="CHANGELOG.md"><b>Changelog</b></a> ·
    <a href="SECURITY.md"><b>Security</b></a>
  </p>

</div>

---

eeco adds two things to any coding project, from the terminal: a
self-maintaining workflow ecosystem, and a deterministic, no-AI-spend
knowledge layer any AI assistant can read. It ships as a single static
binary. The workflow side is a control-center TUI, repeatable workflows
that keep the tracked tree hygienic and surface issues, and a memory
store with garbage collection. The knowledge side is a project brief and
targeted Q&A, both built by a local deterministic pass with no model
call. New workflows are added opt-in over time — proposed for review
rather than applied unilaterally.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/demo-dark.gif">
    <img src="assets/demo-light.gif" alt="eeco demo" width="780">
  </picture>
</p>

## Design

- **Single static binary, zero runtime dependencies.** Install via a
  package manager or drop the binary on `PATH`; nothing to provision on
  the host.
- **Local-first and private.** eeco reads anywhere in a target repo but
  writes only inside that repo's gitignored workspace. The sole
  exception is `eeco init`, which may make one initial commit and push
  of the workspace `.gitignore` line; no other verb ever commits or
  pushes.
- **Pluggable AI, opt-in by default.** A provider interface with a
  generic CLI provider wired in; every AI pass is gated by explicit
  consent (`--ai` or `automation=auto`) and a per-invocation budget cap.
- **Runs only when invoked.** A single queue is the only channel that
  asks for a decision.
- **Reversible.** The two integrations that touch outside the workspace
  (a local pre-commit hook, one entry in an AI CLI's user settings) are
  opt-in and recorded in a ledger so they can be removed cleanly.

## What eeco gives you

- **Control-center TUI** (`eeco`). A home screen lists the slash
  commands one line each; output streams above the input.
- **Ten builtin workflows.** `comment-hygiene`, `leak-guard`,
  `version-sync`, `gate`, `memory-drift`, and `doc-drift` keep the
  tracked tree hygienic and catch drift; `bug-sweep` keeps a triage
  ledger; `handover-refresh` drafts dated handovers; `manifest-refresh`
  keeps per-directory `.ai.json` manifests current; `evolve` proposes
  new workflows from observed repetition. Run via `eeco run <name>`. A
  pre-1.0 `cockpit-sync` workflow additionally keeps the generated AI
  cockpit in step (see [`docs/COCKPIT.md`](docs/COCKPIT.md)).
- **Knowledge layer for AI assistants.** `eeco go` prints a
  deterministic project brief, built with no model call (with `--json`,
  `--brief`, `--write`, and `--copy` delivery axes); `eeco ask "<question>"`
  answers a targeted question with ranked `path:line` pointers;
  `eeco add fact` / `eeco add task` let an assistant record what it
  learns back into memory and the queue. The delivery channels are
  brand-free — point Claude Code at `CLAUDE.md`, Gemini CLI at
  `GEMINI.md`, Codex at `AGENTS.md`, Cursor at `.cursorrules`, or
  paste `eeco go --copy` into any chat-only assistant.
- **Memory store with garbage collection** (`eeco gc`). One fact per
  file with flat frontmatter and a regenerated index.
- **The queue.** Every decision-bearing finding lands in one
  Markdown checklist under a presence lock — never email, never a
  notification, never a silent edit.
- **Opt-in self-update** (`eeco update --apply`). Verifies the
  release archive against the `SHA256SUMS` cosign signature, the
  archive sha256, and the GitHub build-provenance attestation before
  atomically replacing the running binary. Bare `eeco update` is
  read-only.
- **Cross-project settings** (`eeco config`). `eeco config list|get|set`
  edits the per-project config; `eeco config set --global <key> <value>`
  writes a user-global layer every project inherits, with per-repo
  overrides — the git `--global` model. See
  [`docs/USAGE.md`](docs/USAGE.md) §4a.
- **Diagnostics** (`eeco doctor`), **clean removal** (`eeco uninstall`),
  and **friction capture** (`eeco report-bug`).

## Install

Pick the route you prefer. See
[`docs/USAGE.md`](docs/USAGE.md#1-install) for the full platform matrix,
checksum verification, and the cosign signature + build-provenance
checks.

**Homebrew (macOS, Linux).**

```
brew install ajhahnde/eeco/eeco
```

**Scoop (Windows).**

```
scoop bucket add eeco https://github.com/ajhahnde/scoop-eeco
scoop install eeco
```

**Pre-built binary.** Download the archive for your platform from the
[releases page](https://github.com/ajhahnde/eeco/releases) and extract
the `eeco` binary onto your `PATH`. `SHA256SUMS` is cosign-signed and
the archives carry build provenance.

**From source.** Requires Go 1.24+.

```
git clone https://github.com/ajhahnde/eeco
cd eeco
make build        # produces ./eeco with version metadata
```

**In-place upgrade.** Once eeco is installed, future releases
upgrade in place:

```
eeco update --apply
```

Verifies the cosign signature on `SHA256SUMS`, the archive sha256, and
the GitHub build-provenance attestation before swapping the binary.
Refuses on Homebrew- or Scoop-managed install roots in favour of the
package manager's upgrade verb.

`make verify` runs `go build ./... && go vet ./... && go test ./...`;
`make release` cross-builds the published matrix into `dist/`.

## License

Apache License, Version 2.0. See [`LICENSE`](LICENSE).

_Public history starts at v0.1.0; eeco was developed in a private repo and published here._

## See also

- [FlashOS](https://github.com/ajhahnde/FlashOS) — AArch64 bare-metal kernel for the Raspberry Pi 4 Model B.
- [the-way-out](https://github.com/ajhahnde/the-way-out) — top-down pixel-art escape-room shooter.
- [Flash](https://github.com/ajhahnde/Flash) — a systems language and Zig transpiler.

---

[Next: Vision →](VISION.md)