Loopee

Loopee lets you define your agent's world as state and react to it at every mutation boundary.

Quickstart

npm i loopee
cp .env.example .env  # add your OpenRouter API key

import { run } from "loopee";

await run("fix the bug", {
  model: "claude-sonnet-4-20250514",
  system: "You are a helpful assistant.",
  tools: myTools,
  hooks: [useBudget(30), useSkills(mySkills, baseSystem, skillTool), useCompact(128_000, summarize)],
});

The idea

An agent is a loop: state goes in, the LLM responds, state updates. Every time state changes — a user message, an assistant response, a tool result — all hooks fire. A hook reads state, optionally returns a patch.

state changes → hooks fire → patches applied → loop continues

Hooks

A hook is (state) => patch | void. Sync or async. Patch anything — messages, tools, system prompt, ext — or set stop: true.

// Stop after 30 turns
const useBudget: Hook = (s) => {
  if (s.turn >= 30) return { tools: [], stop: true };
};

// Inject relevant skills into the system prompt + add the Skill tool
const useSkills: Hook = (s) => {
  const skills = relevantSkills(s);
  return {
    system: base + skills.prompt,
    tools: [...s.tools, skillTool(skills.active)],
  };
};

// Compact old messages when context gets large
const useCompact: Hook = (s) => {
  if (estimateTokens(s.messages) > 80_000) return { messages: compact(s) };
};

A hook checks what the last message is and reacts:

// Block denied tool calls by rewriting the assistant message
const usePermissions: Hook = async (s) => {
  const last = s.messages.at(-1);
  if (last?.role !== "assistant" || !last.tool_calls) return;
  const denied = last.tool_calls.filter((tc) => !isAllowed(tc));
  if (denied.length) return { messages: rewriteDenied(s.messages, denied) };
};

// Nudge the agent if it investigates but never edits
const useNudge: Hook = (s) => {
  const last = s.messages.at(-1);
  if (last?.role !== "assistant" || last.tool_calls) return;
  if (hasToolUse(s) && !hasEdits(s)) return {
    stop: false,
    messages: [...s.messages, { role: "user", content: "Implement the fix now." }],
  };
};

Composition

Build primitives, then compose them:

// Primitive: react before tool execution
const useReadBeforeEdit = useBefore("tool", (s) => {
  const last = s.messages.at(-1);
  if (last?.role !== "assistant" || !last.tool_calls) return;
  for (const tc of last.tool_calls) {
    const args = JSON.parse(tc.function.arguments);
    if (tc.function.name === "Edit" && !s.ext.filesRead?.includes(args.file_path)) {
      return { messages: rewriteToRead(s.messages, tc) };
    }
  }
});

// Group hooks into a custom hook
function useGuardrails() {
  return [usePermissions(myRules), useReadBeforeEdit, useBudget(30)];
}

await run("fix the bug", {
  hooks: [...useGuardrails(), useSkills(mySkills, baseSystem, skillTool), useCompact(128_000, summarize)],
});

External state

Agent state isn't just the transcript. ext holds arbitrary external state — the framework ignores it, hooks read and write it.

An external event source (emails, webhooks, CI, whatever) pushes into ext. A hook sees it and injects a message. The agent reacts.

// Watch for emails outside the loop, push into ext
const emailEvents = new EventSource("/emails/stream");
const pending: Email[] = [];
emailEvents.onmessage = (e) => pending.push(JSON.parse(e.data));

// Hook: when the agent finishes a turn, check for new emails
const emailHook: Hook = (s) => {
  const last = s.messages.at(-1);
  if (last?.role !== "assistant" || last.tool_calls) return; // wait for turn to complete

  if (pending.length === 0) return;
  const emails = pending.splice(0); // drain

  return {
    stop: false, // keep the loop alive
    ext: { ...s.ext, inbox: emails },
    messages: [
      ...s.messages,
      { role: "user", content: `New emails:\n${emails.map((e) => `- ${e.from}: ${e.subject}\n  ${e.body}`).join("\n\n")}\n\nDraft replies.` },
    ],
  };
};

await run("You are an email assistant. Wait for emails and draft replies.", {
  hooks: [emailHook, useBudget(100)],
});

Same pattern works for anything: Slack messages, GitHub webhooks, CI status, sensor data. The event source lives outside the loop, the hook bridges it into state.