Receipt

Receipt is an event-native runtime and orchestration plane for long-lived agents and software objectives.

Instead of treating traces and job state as incidental logs, Receipt stores immutable, hash-linked receipts and derives runs, jobs, memory, objectives, replay, and operator views from them by folding the same receipts.

Install

Prerequisite: Receipt requires the Bun runtime (v1.0+).

# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

# Install Receipt globally
npm install -g @kentronai/receipt-cli
# OR
bun add -g @kentronai/receipt-cli

# Verify
receipt --help

Configuration

Receipt reads environment variables directly and also loads .env files from your working directory automatically (built-in Bun behavior).

Required

| Variable | Description | |----------|-------------| | OPENAI_API_KEY | OpenAI API key for LLM and embedding calls. Get one at platform.openai.com/api-keys |

Optional

| Variable | Default | Description | |----------|---------|-------------| | OPENAI_MODEL | gpt-5.2 | Default model for agent calls | | PORT | 8787 | HTTP server port | | JOB_BACKEND | local | Job backend: local (SQLite queue) or resonate | | RECEIPT_DATA_DIR | .receipt/data | Custom data directory | | RECEIPT_CODEX_BIN | codex | Path to codex binary | | AWS_ACCESS_KEY_ID | — | AWS credentials for Factory cloud features | | AWS_SECRET_ACCESS_KEY | — | AWS credentials for Factory cloud features | | AWS_REGION | — | AWS region override |

Copy the included .env.example to .env in your project directory and fill in your keys:

cp .env.example .env
# Edit .env with your OPENAI_API_KEY

Quick Start

# Set your API key
export OPENAI_API_KEY=sk-...

# Start the Receipt server (opens Factory UI at http://localhost:8787/factory)
receipt dev

# Or use the interactive Factory CLI
receipt factory

# Scaffold a new agent
receipt new my-agent --template basic

# Run an agent
receipt run my-agent --problem "Hello world"

# Create a Factory objective
receipt factory create --prompt "Plan a README refresh"

Common Commands

# Factory operations
receipt factory                     # Interactive Factory CLI
receipt factory create --prompt "..." # Create objective
receipt factory run --prompt "..."    # Create and run objective
receipt factory steer <job-id> --message "..." # Redirect a running job
receipt factory follow-up <job-id> --message "..." # Add context to a job

# Agent operations
receipt new <agent-id> --template basic  # Scaffold agent
receipt run <agent-id> --problem "..."   # Run agent

# Inspection
receipt jobs --status running --limit 20
receipt inspect <run-id-or-stream>
receipt trace <run-id-or-stream>
receipt replay <run-id-or-stream>
receipt fork <run-id-or-stream> --at 12

# Memory
receipt memory read <scope> --limit 5
receipt memory search <scope> --query "search term"

Web Surfaces

When the server is running (receipt dev or receipt start):

| URL | Description | |-----|-------------| | /factory | Main operator UI — chats, objectives, task state, live output | | /receipt | Receipt stream browser | | /healthz | Runtime health check | | /jobs | Queue inspection and live updates | | /memory/* | Memory read/search/summarize APIs |

Troubleshooting

command not found: bun — Install Bun: curl -fsSL https://bun.sh/install | bash

OPENAI_API_KEY is not set — Set the key via export OPENAI_API_KEY=sk-... or add it to a .env file in your project directory.

receipt: command not found — Ensure the npm global bin directory is on your PATH. Run npm bin -g to find the location.

Windows — The receipt binary uses a #!/usr/bin/env bun shebang which may not work natively on Windows. Use bun receipt <command> directly instead.

Out of Scope (v1)

• Node.js runtime support (Receipt requires Bun due to bun:sqlite, Bun.serve())
• Windows native support
• Docker image publishing
• Resonate distributed mode auto-setup

Development

The sections below are for contributors working on Receipt itself.

Prerequisites (Development)

• bun for development and CLI execution
• codex on PATH for Factory task execution
• resonate on PATH for the optional distributed runtime
• OPENAI_API_KEY for model-backed features

Dev Setup

git clone <repo-url>
cd receipt
bun install
bun run build

# Local SQLite mode (default)
bun run dev

# Optional: multi-process runtime + local Resonate
bun run dev:resonate

Core Concepts

Receipt is the event-native substrate. Everything durable — agent runs, jobs, memory, Factory objectives — is replayed by folding the same receipts.

• Primitives: src/core/ — createRuntime, hashing, fold, branching, and Store / BranchStore contracts.
• Persistence: SQLite (src/adapters/jsonl.ts, backing receipts and streams tables). Projections via Drizzle ORM (drizzle/).
• Domain Modules: Typed events, reducers, and decide functions in src/modules/.

Factory is the receipt-native control plane for software objectives. It provides task DAG, worker dispatch, candidate review, integration, validation, and promotion — all recorded as Factory receipts.

Architecture Layers

flowchart TD
  subgraph Data
    RS[(Receipt Store / SQLite)]
    PS[(Projections / Drizzle)]
  end

  subgraph Workers
    CQ[Queue: Resonate / Local]
    CW[Workers: Factory, Codex]
    CQ --> CW
  end

  subgraph Application
    Srv[Hono Server]
    FS[Factory Service]
    AM[Agent Modules]
    Srv --> FS
    FS --> AM
    FS --> CQ
    FS --> RS
    RS --> PS
  end

  subgraph Presentation
    UI[Web UI / HTMX]
    CLI[Terminal UI / Ink]
    UI --> Srv
    CLI --> Srv
  end

Technologies

| Area | Stack | |------|--------| | Runtime | Bun (bun:sqlite), TypeScript | | HTTP Framework | Hono | | Validation | Zod, @hono/zod-validator | | Database | Drizzle ORM + SQLite | | Queue | Resonate (@resonatehq/sdk, optional) or Local SQLite Queue | | LLM | OpenAI SDK | | CLI / Workers | Ink, React, @clack/prompts | | Web UI | HTMX, htmx-ext-sse, Vanilla JS/TS | | Styling | Tailwind CSS v4 |

Repository Map

| Path | Responsibility | |------|----------------| | src/core/ | Receipt chain, runtime, graph types | | src/sdk/ | Agent authoring API | | src/modules/ | Agent, job, factory reducers/events | | src/engine/runtime/ | Agent loop, job worker, control receipts, Resonate actions | | src/adapters/ | SQLite store, queue, Codex, OpenAI, memory, Git helpers | | src/services/ | Factory service, planners, artifacts, workers | | src/agents/ | Orchestrator, factory route, capabilities, codex supervisor | | src/factory-cli/ | Factory-focused CLI/TUI | | src/views/, src/client/, src/styles/ | Server HTML, browser TS, Tailwind assets | | src/db/ | Schema, client, projectors, importer | | src/framework/ | Agent loader, HTTP helpers, SSE hub | | .receipt/ | Repo-local config and data roots | | docs/ | Deep documentation and architecture records |

Runtime Modes

Local SQLite (default) — single-process, persists in ${DATA_DIR}/receipt.db:

bun run dev
bun run start

Resonate (optional) — multi-process with distributed job dispatch:

bun run dev:resonate
bun run start:resonate

Docker

# Dev container (bind-mounts repo)
bun run docker:dev:up
bun run docker:dev:down

# Prod-style container
bun run docker:prod:up
bun run docker:prod:down

Testing

bun run build
bun run test:smoke
bun run verify        # build + type check + smoke tests

Docs

• architecture.md
• docs/api/README.md
• docs/agent-framework.md
• docs/context-management.md
• docs/create-agent.md
• docs/factory-on-receipt.md
• docs/factory-agent-orchestration.md
• docs/factory-profile-orchestration.md
• docs/factory-infrastructure-engineer.md
• docs/factory-self-improvement.md