Loopkit

Loopkit is a small TypeScript SDK for observable multi-agent workflows. It gives workflow authors simple primitives like agent, parallel, serial, loopUntil, and artifact, while the runtime records a live flow graph, agent logs, outputs, and durable artifacts.

The first adapter runs Codex behind the scenes through codex exec --json. A Codex SDK adapter can be added behind the same AgentProvider interface.

Install locally

From another project during development:

npm install /Users/viswa/code/loopkit

Or use a file dependency:

{
  "dependencies": {
    "@viswa-abe/loopkit": "file:/Users/viswa/code/loopkit"
  }
}

Example workflow

import { agent, artifact, defineWorkflow, parallel } from "@viswa-abe/loopkit";

export default defineWorkflow<{ issue: string }>({
  id: "root-cause",
  title: "Root cause investigation",
  async run(input) {
    const firstPass = await agent("classify", {
      prompt: `Classify this issue and identify evidence streams: ${input.issue}`,
    });

    const findings = await parallel("investigate", [
      () => agent("logs", { prompt: `Inspect logs using this classification:\n${firstPass.text}` }),
      () => agent("code", { prompt: `Inspect code using this classification:\n${firstPass.text}` }),
      () => agent("state", { prompt: `Inspect persisted state using this classification:\n${firstPass.text}` }),
    ]);

    const final = await agent("synthesize", {
      prompt: `Synthesize a final answer from these findings:\n${JSON.stringify(findings, null, 2)}`,
    });

    await artifact("final-report", final.text, { contentType: "text/markdown" });
    return final;
  },
});

Run a workflow

import workflow from "./workflow";
import { codexCliAgent, createFileStore, createLoopRuntime } from "@viswa-abe/loopkit";

const runtime = createLoopRuntime({
  store: createFileStore(".loopkit"),
  agentProvider: codexCliAgent({ cwd: process.cwd() }),
});

const run = await runtime.run(workflow, { issue: "Flaky auth test" });
console.log(run.id);

Observability server

import { createLoopServer } from "@viswa-abe/loopkit/server";
import { createFileStore } from "@viswa-abe/loopkit";

const server = createLoopServer({ store: createFileStore(".loopkit") });
await server.listen(4377);

Endpoints:

• GET /runs
• GET /runs/:runId
• GET /runs/:runId/flow
• GET /runs/:runId/events for SSE live updates
• GET /agent-runs/:agentRunId/logs
• GET /artifacts/:artifactId

Try the viewer

After running a workflow, start the local observability server:

npx loopkit serve 4377

Open http://127.0.0.1:4377/ to inspect runs, flow status, agent logs, and artifacts.

Publish to npm

For a scoped public package, npm currently requires --access public because scoped packages default to private visibility.

cd /Users/viswa/code/loopkit
npm install
npm run build
npm pack --dry-run
npm login
npm publish --access public

For a private package under a paid npm account/org:

npm publish --access restricted

For updates:

npm version patch
npm publish --access public

Before publishing, review npm pack --dry-run output and keep secrets, local run data, auth files, and test fixtures out of the package.

References:

• npm scoped public package publishing: https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/
• npm publish command: https://docs.npmjs.com/cli/v10/commands/npm-publish/