AgentraLoop

AgentraLoop is an agent-centric runtime for queueing, executing, and supervising long-running AI work. Instead of treating execution as a single chat transcript, it models pipelines, queues, tasks, runs, providers, and user workspaces as explicit runtime objects.

Status: active development, usable for local experimentation and self-hosted workflows.

License: ISC

Repository health:

• npm run verify passes
• npm audit --omit=dev reports 0 production vulnerabilities
• docs, REST API reference, and contribution guides are included

Community:

• Contributing guide
• Support
• Security policy
• Changelog

Quick start:

npm install
npm run verify
npm run serve

Default local URL:

http://127.0.0.1:8787

The project combines:

• a Node.js/TypeScript runtime and HTTP server
• a React-based Web Studio for operations and editing
• queue-backed task dispatch
• provider-aware agent execution across Codex and Claude integrations

Why AgentraLoop

Most AI applications still center everything around a live conversation. That works for short interactions, but it is a poor fit for continuous software work that needs:

• durable task intake
• queue ordering and pause/resume semantics
• explicit run state and history
• user-scoped workspaces
• operator-visible runtime control
• reusable workflow definitions

AgentraLoop is designed for that operational model.

Core Concepts

• Pipeline: a directed graph of agent nodes and edges
• Queue: the intake and ordering boundary for a pipeline
• Task: a queued unit of requested work
• Run: a concrete execution instance with node-level status and history
• Provider: the backend that executes each node, such as codex-cli, codex-sdk, or claude-agent-sdk
• User Scope: isolated workspace, data, logs, queues, and pipelines per user

Features

• Queue-driven execution for long-running AI work
• Pipeline graph editing in the browser
• Run inspection with node-level status and event history
• Task queue management with reorder, pause, resume, edit, and delete operations
• User-scoped runtime isolation
• REST API for automation and external integrations
• VitePress documentation site with architecture, design, and API references

Repository Layout

• src/: runtime, server, storage, schema validation, provider integrations, CLI entry points
• web/: Vite + React Web Studio
• pipelines/: checked-in pipeline definitions
• examples/: small API/client examples
• test/: Node test suite
• docs/: VitePress documentation source
• public/app/: production Web Studio assets generated by the build

Requirements

• Node.js >= 20.11
• npm
• sqlite3 on PATH if you want the full queue-backed test suite to pass
• codex on PATH if you use codex-cli or codex-sdk pipeline nodes
• appropriate provider credentials and local setup for any agent backend you enable

Installation

Install dependencies:

npm install

Build the runtime and Web Studio:

npm run build

Running the Server

Start the local HTTP server:

npm run serve

Default base URL:

http://127.0.0.1:8787

The server hosts both the REST API and the Web Studio.

CLI Usage

Run the bundled default pipeline once:

npm run dev

After publishing to npm, the packaged CLI can be started directly with:

npx agentraloop serve

You can also run:

npx agentraloop run

Environment Variables

Common runtime configuration:

• PORT: HTTP server port
• PIPELINE_PATH: explicit default pipeline file
• PIPELINE_CWD: default workspace directory
• PIPELINE_DB_PATH: SQLite database path
• PIPELINE_MODEL_PROFILE: default model profile (fast or standard)
• AGENTRALOOP_USERS_ROOT: root directory for user-scoped data
• AGENTRALOOP_USERS_FILE: user registry JSON path
• AGENTRALOOP_DEFAULT_USER_ID: default user scope
• AGENTRALOOP_PUBLIC_DIR: override built web asset directory

Development Commands

• npm run build: compile src/ and build the web app into public/app
• npm run build:web: rebuild only the Web Studio assets
• npm run lint: run the TypeScript typecheck gate
• npm test: rebuild and run the Node test suite
• npm run verify: run lint, tests, and docs build together
• npm run serve: start the HTTP server from src/server.ts
• npm run dev: run the default pipeline entry point from src/main.ts
• npm run docs:dev: start the VitePress docs site locally
• npm run docs:generate: build the docs site once
• npm run docs:preview: preview the generated docs site
• npm run docs:site: build and preview the docs in one command

Contributing

Contribution workflow and repository expectations are documented here:

• CONTRIBUTING.md
• SUPPORT.md
• SECURITY.md
• CODE_OF_CONDUCT.md
• CHANGELOG.md

If you are changing runtime behavior, run npm test before opening a PR. For docs-only changes, run npm run docs:build.

Documentation

Documentation is organized as a VitePress site under docs/.

• Docs home: docs/index.md
• Getting started: docs/getting-started.md
• REST API reference: docs/api/rest-api.md
• Architecture: docs/architecture/index.md
• Design notes: docs/design/index.md
• Research notes: docs/research/index.md

Build and preview locally:

npm run docs:generate
npm run docs:preview

Do not open docs/.vitepress/dist/index.html with file://. VitePress output should be previewed through an HTTP server.

REST API

The server exposes JSON-over-HTTP endpoints for:

• health and workspace inspection
• user scope management
• pipeline CRUD and graph saves
• queue and task operations
• run creation, control, inspection, and retry

See the full API reference here:

• REST API Reference

Example Workflow

1. Start the server with npm run serve.
2. Open the Web Studio in the browser.
3. Select or create a user scope.
4. Choose a pipeline in the Editor or Queue page.
5. Submit a task into the selected queue.
6. Watch the run progress in Runtime and inspect output in History.

Runtime Artifacts

These directories are typically local runtime state and should not be committed unless the change is intentional:

• data/
• users/
• runtime-workspaces/
• logs/
• public/app/assets/

Status

AgentraLoop is under active development. The runtime model, Web Studio, and documentation are usable, but parts of the system still depend on local host setup, provider availability, and environment-specific tooling.

License

ISC. See LICENSE. ISC