Agent Learner

agent-learner

Reusable learning control plane for coding-agent workflows.

`agent-learner` helps you:

• capture learned rules from agent work
• keep repo-scoped and global learning assets in one canonical global store
• review candidates and promote useful rules
• use a dashboard UI for history, rules, and promotions

It is a learning system, not a unified wiki layer.

It is designed to layer onto existing agent environments rather than replace them.

Start here

If you want the shortest one-line setup, use one of these:

pipx install "agent-learner[web]" && agent-learner dashboard --project-root "$PWD" --open
npx @cafitac/agent-learner@latest dashboard --project-root "$PWD" --open

If you want a preflight check first, run `doctor` before `dashboard`.

The dashboard defaults to `127.0.0.1:8766` to avoid common local MCP/gateway ports such as `8765`.

`doctor` tells you whether the dashboard can run now, what is missing, and the next command to use.

Choose your path

1. Published Python package

pipx install "agent-learner[web]" && agent-learner dashboard --project-root "$PWD" --open

2. npm / npx wrapper

npx @cafitac/agent-learner@latest dashboard --project-root "$PWD" --open

3. Source checkout

./bin/dashboard.sh doctor
./bin/dashboard.sh --open

4. Optional Docker path

docker compose up --build

Docker is optional convenience only. It is not the primary OSS install path.

Typical workflow

1. Install the adapter you want to use first
   • Codex is the most established path
   • Hermes is available as an explicit experimental opt-in
2. Run doctor
3. Open the dashboard
4. Review rules, candidates, and history
5. Promote reusable learning assets after review; repo scoping is tracked by metadata, not separate local stores

Core concepts

Global-first learning storage

• canonical durable learning lives under AGENT_LEARNER_HOME (default ~/.agent-learner/)
• events,