@fuiste/iterate

@fuiste/iterate is a local-first issue tracker for long-horizon agent workflows. It is designed for a Ralph-loop style workflow where a human frames a large initiative, approves the planning and documentation shape, and agents repeatedly pick up ready tasks, report progress, and move work toward verification.

The package is built with Bun, TypeScript, and Effect. It exposes a JSON-first CLI for agent harnesses and a lightweight local web UI for visualizing project status.

Goals

• Keep the coordination surface simple enough for agents to use reliably.
• Preserve structure for long-running initiatives: docs, implementation, tests, and verification.
• Support local-first development today while keeping a clean backend abstraction for future hosted coordination.
• Integrate with Cursor and similar tools through an AGENTS.md contract installed by the CLI.

Install

Requires Bun 1.3+.

bun add -g @fuiste/iterate
# or
npm install -g @fuiste/iterate

You can also run it without a global install:

bunx @fuiste/iterate init --json
# or
npx @fuiste/iterate init --json

Development

bun install
bun run check
bun test
bun run build

CLI

iterate init --json
iterate plan --title "Build iterate" --prompt "Create a local-first issue tracker for async agents." --actor planner --json
iterate ready --json
iterate claim <task-id> --actor cursor-agent --json
iterate update <task-id> --status blocked --note "Waiting on review." --json
iterate close <task-id> --verified --note "Validated against the initiative." --json
iterate board --json
iterate ui --port 3000
iterate install-agent-instructions --json

Ralph Loop Workflow

1. Initialize the workspace.

iterate init --json

2. Create an initiative from a large prompt.

iterate plan \
  --title "Ship async agent issue tracker" \
  --prompt "Build a local-first issue tracker npm package for long-running agent workflows, with docs, implementation tasks, test gates, and a lightweight status UI." \
  --actor planner \
  --json

3. Let agents pick up ready work.

iterate ready --json
iterate claim <task-id> --actor cursor-agent --json

4. Record progress and evidence.

iterate update <task-id> \
  --status in_progress \
  --note "Implemented the SQLite repository and claim semantics." \
  --artifact-kind file \
  --artifact-value src/backend/sqlite.ts \
  --artifact-label "Repository implementation" \
  --actor cursor-agent \
  --json

5. Close and verify work.

iterate close <task-id> --verified --note "Reviewed against the approved initiative." --actor reviewer --json

6. Inspect the project board.

iterate board --json
iterate ui

What plan Creates

Each initiative is materialized as a small workflow graph:

• a requirements and success-criteria task
• a design task
• an implementation task
• a unit test task
• an integration or workflow test task
• a verification task

Dependencies ensure agents can always ask the system what is ready next.

Web UI

iterate ui launches a minimal local status board backed by the same application services as the CLI. It is intentionally read-mostly in v1 and focuses on:

• initiative summaries
• task columns by effective status
• blockers
• claims
• verification progress

AGENTS.md Integration

iterate init and iterate install-agent-instructions install an AGENTS.md block that tells agents how to:

• initialize the tracker
• discover ready work
• claim exactly one task at a time
• record notes and artifacts
• close and verify tasks

Architecture

• src/domain: domain types, schemas, and workflow rules
• src/application: Effect use-cases over the repository port
• src/backend: backend interface plus SQLite implementation
• src/commands: CLI parsing and render helpers
• src/docs: workspace paths and AGENTS.md instruction generation
• src/ui: lightweight local web UI
• test: domain, backend, CLI, and UI coverage

Notes

• Storage is local-first in v1, using SQLite under .iterate/iterate.sqlite.
• The repository is designed behind an interface so a hosted backend can be added later.
• The CLI JSON output is intended to be stable and easy for agents to consume.