eeco

Single-binary workflow ecosystem and knowledge layer for any AI assistant.

README · Vision · Cockpit · Usage · Architecture · Public API · Extending · Contributing · Upgrading · Versioning · Changelog · Security

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 <name>. A pre-1.0 cockpit-sync workflow additionally keeps the generated AI cockpit in step (see 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 §4a.
• Diagnostics (eeco doctor), clean removal (eeco uninstall), and friction capture (eeco report-bug).

Install

Pick the route you prefer. See docs/USAGE.md 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 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.

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

See also

• FlashOS — AArch64 bare-metal kernel for the Raspberry Pi 4 Model B.
• the-way-out — top-down pixel-art escape-room shooter.
• Flash — a systems language and Zig transpiler.

Next: Vision →