---
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.
## 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 `. 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 ""`
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 `
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)
