blog index

Agentropy System Guide

What the system is, what problem it solves, and how the pieces fit.

snapshot 2026-05-05 source README.md, install/README.md, loop/README.md local worktree guide
Agentropy high-level system map The operator steers proxyd through the web or phone. proxyd composes replies through the Skills Engine, which runs learned skills with no vendor call and falls back to an LLM vendor only on a miss, then learns the vendor reply as a new skill. Local evidence feeds decisions, briefs, approvals, and growth loops. operator judgment and goals Web UI and iPhone chat, decide, dashboard proxyd on Mac control plane Skills Engine composes the reply from learned skills on the host, with no vendor call LLM vendors fallback + teacher Decision proxy decisions, soul, psyche notes Local state and skills ~/.agentropy/proxy, ~/.skg JSONL, Markdown, graph Collectors files, browser, phone Briefs and loops daily, weekly, growth Visible outputs answers, approvals, roadmap, dashboard on a miss learn
The Skills Engine is the centre: it composes replies from learned skills on the host with no vendor call. An LLM vendor is the fallback and teacher, used only on a miss, and its reply becomes a new skill. Local evidence feeds decisions, briefs, approvals, and growth loops.

System Operating Flow

LLM model-involved step
1Intent Or SignalA chat request, phone action, schedule, file event, or collector signal enters agentropy.
what it is
A chat request, phone action, schedule, file event, or collector signal enters agentropy.
triggered by
the operator, launchd, a mobile action, a file event, or a scheduled collector.
hands off to
Local Control
2Local Controlproxyd, launchd, or a loop script receives the work and selects the local path.
what it is
proxyd, launchd, or a loop script receives the work and selects the local path.
triggered by
The route selected by the entry surface or the scheduled job definition.
hands off to
Policy And Context
3Policy And ContextRules, local state, collector output, and prior decisions shape what can happen next.
what it is
Rules, local state, collector output, and prior decisions shape what can happen next.
triggered by
The local state needed before work leaves the Mac or changes state.
hands off to
Skills Engine Or Tool Path
4Skills Engine Or Tool PathLLMChat composes through the Skills Engine from learned skills with no vendor call; other work runs a local reader, browser recipe, or deterministic tool. A vendor is the fallback and teacher on a miss.
what it is
Chat composes through the Skills Engine from learned skills with no vendor call; other work runs a local reader, browser recipe, or deterministic tool. A vendor is the fallback and teacher on a miss.
triggered by
The selected path after policy and context checks finish.
hands off to
Approval Boundary
5Approval BoundaryRisky external, sensitive, destructive, or identity-bearing work waits for the operator.
what it is
Risky external, sensitive, destructive, or identity-bearing work waits for the operator.
triggered by
Invariant ceilings, approval rules, or action kind rules.
hands off to
Recorded Outcome
6Recorded OutcomeThe result lands in chat, dashboard, roadmap, brief, inbox, or local JSONL state.
what it is
The result lands in chat, dashboard, roadmap, brief, inbox, or local JSONL state.
triggered by
Tool completion, model reply, approval decision, or collector write.
hands off to
The next local run, dashboard view, or review loop.
A request or signal enters locally, gets routed through policy and context, then returns as a visible output or a recorded result.

Definition

What The System Is

Agentropy is a local personal operating system for supervised AI work.

The Mac is the agent host. The web UI and iPhone app are control surfaces. Agentropy routes routine decisions, collects local evidence, builds weekly briefs, tracks outcomes, and asks the operator only when judgment or approval is required.

Answers come from the Skills Engine, a local skill knowledge graph (SKG). The Skills Engine composes a reply on the fly from learned skills that run against the host (clock, files, network reads, gated actions), with no vendor call. An external AI vendor is used only when the Skills Engine has not yet learned a skill for the request; that reply is then captured as a new skill, so the next equivalent request composes locally.

The system is not a cloud SaaS product. It is a single-user local stack that keeps state under ~/.agentropy/proxy/ and the Skills Engine under ~/.skg/, serves the dashboard through proxyd, and treats external vendors as a fallback and a teacher, not the engine.

Problem

The Problem It Solves

AI assistants stop too often for low-risk choices, but they also should not act alone on destructive, external, sensitive, or identity-bearing work.

Personal context also lives in too many places: code, phone events, chat sessions, decisions, venture work, and public writing. Without a system, the operator either babysits the assistant or lets it act with too little context.

Agentropy solves that by creating a supervised loop: local context is collected, routine choices are delegated to rules, risky actions are approval-gated, and outcomes feed the next brief or review.

Contract

The Operating Contract

  • Routine decisions go to decision-proxy before they interrupt the operator.
  • Approvals that affect people, money, credentials, data, or git history escalate.
  • Chat, roadmap, decisions, and dashboard views use the same local state.
  • Collectors and loops write evidence first, then briefs and reviews synthesize it.
  • External messages stay staged until an approval record exists.

Map

What Runs Where

Mac: proxyd, launchd jobs, collectors, the Skills Engine, router, local files, and browser automation.

Skills Engine: a local skill knowledge graph under ~/.skg/ that composes chat answers from learned skills with no vendor call. It is the primary engine for replies.

Phone and browser: chat, approve, deny, reply, roadmap, drift, calls, dashboard, and device management.

Vendors: Claude, Codex, OpenAI, and future adapters enter only through agent_router, as a fallback when the SKG has no skill yet and as the teacher that seeds new skills.

Local memory: append-only JSONL and Markdown files under ~/.agentropy/proxy/ hold the audit trail and working state.

Startup

How Processes Start And When

install/setup.sh writes com.agentropy.proxyd into ~/Library/LaunchAgents. launchd starts it at login with RunAtLoad and restarts it with KeepAlive.

loop/loop-setup.sh writes the scheduled loop agents. They run only while the macOS user session is logged in, and their times use the Mac's local timezone.

  • At login: proxyd, watchdog, chat-watchdog, heartbeat, and collectors.orchestrator start.
  • Every minute: chat-watchdog checks proxyd and recent chat errors.
  • Every 30 minutes: teacher-loop and growth-governor run.
  • Morning: compounding-loop runs at 06:50 and venture-loop at 07:10.
  • Weekly: weekly-agent-orchestrator runs bin/orchestrate Sunday 08:00 when installed, proxy-research runs Sunday 21:00, proxy-review Sunday 22:00, and growth loops add Monday weekly passes.
  • Monday: growth-agent runs Monday 07:00 when installed and reads bucketed LinkedIn/Facebook signals for the weekly brief.

Manual commands such as growth-governor run-now and teacher-loop run-now run the same paths outside launchd.

Manual

How To Start Each System By Hand

Run these from ~/Workspace/agentropy unless the command starts with launchctl.

  • launchctl kickstart -k gui/$(id -u)/com.agentropy.proxyd restarts the web control plane.
  • launchctl kickstart -k gui/$(id -u)/com.agentropy.watchdog restarts the reachability watchdog.
  • launchctl kickstart -k gui/$(id -u)/com.agentropy.orchestrator restarts collector orchestration.
  • loop/proxy-status.sh prints daemon and loop status.
  • python3 loop/proxy-learn.py runs rule-learning review for recent decisions.
  • python3 loop/proxy-research.py runs the research brief.
  • python3 loop/proxy-review.py runs the weekly review.
  • bin/orchestrate --phase collect --task "collect all configured surfaces" --json runs the agent-orchestrator collect phase once.
  • bin/browser-surface-workflow linkedin facebook whatsapp --json runs the login-aware social browser workflow once.
  • bin/compounding-loop run-now --notify writes the compounding packet.
  • bin/venture-loop run-now --notify writes the venture packet.
  • bin/teacher-loop run-now --notify evaluates drift and teacher nudges.
  • bin/growth-governor run-now --notify selects the next growth action.
  • bin/growth-governor status previews the governor state without sending a notification.
  • curl http://127.0.0.1:4877/status.json reads the dashboard status snapshot.

Use launchctl kickstart for always-on agents. Use the script commands for one-shot jobs, because they run the same code path without changing the schedule.