---
eeco is the AI-agnostic ecosystem for autonomous project housekeeping
— an intelligent, system-level framework that sits as a meta-layer
above modern software development. Its purpose is to radically
automate project housekeeping so developers can focus entirely on
creative implementation and problem-solving.
This document states where eeco is headed. The README and USAGE
describe what it does today.
## The vision
eeco is not a reactive tool — it is a proactive background process
that continuously analyses, understands, and actively maintains a
project. Through pattern recognition, eeco identifies recurring
development and maintenance patterns and derives workflows from
them automatically — proactively, or on explicit user request.
## Core concepts
### Model-agnostic interoperability — the context compiler
eeco is a universal abstraction layer. It ensures that every AI —
from specialised small models to high-end LLMs like Gemini, Claude,
or GPT — receives exactly the project context it needs. eeco acts
as a **context compiler** that translates complex project
documentation into a form any AI can process, in a standardised
shape.
### Autonomous housekeeping
With built-in standard workflows — a bug finder for error analysis,
a hygiene keeper for code-standards enforcement, drift detectors
across memory and docs — eeco takes the administrative load. The
system learns from the developer workflow and evolves through
AI-assisted self-optimisation.
### Intelligent context steering — AI guardrails
eeco is a **guardrail** for AI agents. It delivers cross-model
binding rules — language policies, attribution rules, project
conventions — that minimise hallucinations and keep project
quality consistent without the user repeating explicit
instructions on every call.
## The goal
eeco aims to become the standard for AI-assisted project steering:
the interface where human software architecture and AI-driven
implementation meet. Through the handshake between eeco and any
AI model, a seamless environment emerges in which the AI acts not
just as a code generator, but as part of a self-organising,
highly efficient development system.
## Operating principles
The vision above is the destination. These principles hold on the
way there and are never traded away:
- **Human-in-the-loop.** eeco proposes; the operator decides. It
never commits to, pushes, or activates a workflow on your project's
tracked tree without explicit consent.
- **Init exception.** `eeco init` is the single verb permitted to make
one initial commit and one initial push to the HOST repo, both
restricted to the `.gitignore` line that scopes eeco's workspace out
of the tracked tree — plus the private workspace-history repo described
below, which is local-only and confined to the gitignored workspace.
Every other verb — `run`, `gc`, `hooks`, `gates`, `add`, etc. —
continues to never commit to or push the tracked tree, and never write
outside the workspace.
- **Workspace history (the AI's logbook).** eeco may keep a private,
**local** git repository inside its own gitignored workspace directory
(`/`) to version its knowledge layer — memory, queue,
decisions, manifests — over time. This repository **never leaves the
machine** (no remote, no push by default) and **never touches the host
project's tracked tree**: it records only what eeco already writes
inside its own gitignored workspace. It is created opt-out at `eeco
init` (`workspace_history`: `manual` by default, `auto` to commit on
every change, `off` to disable) and removed at `eeco uninstall`. Inside
this private repo eeco has a free hand — commit, squash, gc — because
nothing there is shared or tracked by the host; every other verb still
never commits to the tracked tree, pushes, or writes outside the
workspace.
- **Opt-in AI spend.** Every AI call is consent-gated and
budget-capped. The default automation level is manual.
- **Local-first and private.** eeco reads anywhere in the repo,
writes only inside its gitignored workspace. No telemetry, no
hosted service.
- **Reversible.** Every escape from the workspace — the pre-commit
hook, the session-start integration, the commit-msg hook, the
commit-guard PreToolUse hook — is opt-in, ledgered, and removable
byte-for-byte.
## Non-goals
- Not a CI service, not a hosted product — it runs on your machine.
- Not tied to one AI vendor — the knowledge layer is
provider-agnostic.
- Not a replacement for operator judgment — eeco surfaces and
proposes; the operator approves.
## Roadmap
eeco follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
over the frozen surface in [`docs/PUBLIC_API.md`](docs/PUBLIC_API.md).
The next stretch deepens the context compiler and grows the
autonomous-housekeeping workflows. See [`CHANGELOG.md`](CHANGELOG.md)
for what has shipped.
## See also
- [README.md](README.md) — quick start and install
- [docs/USAGE.md](docs/USAGE.md) — full user reference
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — architecture overview
---
[← Prev: README](README.md) · [Next: Cockpit →](docs/COCKPIT.md)
