Skip to content

BLERBZ/absoloop

BranchesTags

Repository files navigation

Absoloop

Absoloop

Synergetic Loops
Evidence wins. Budgets bind. The critic does not take your word.

Quick start · Setup · Surfaces · Mission loop · Harness · Docs · Contribute

Python 3.9+ License MIT Stdlib runtime Providers CI

Synergetic Loops

AbsoLoop is Synergetic Loops — bounded cycles where builder, critic, human, and local agent CLIs compound so the mission outcome is stronger than any single agent alone.

It is an open-source orchestrator for local agent CLIs. You state an objective; Absoloop runs a checkpointed repair loop until three things agree:

  1. the builder claims done with evidence
  2. an independent critic finds no blocking issue
  3. you approve

No cloud Absoloop service. No mystery SaaS. Your machine, your providers, your ledger.

 objective ──► /goal contract ──► builder iterates (thinking escalates)
                                      │
                     done? ──► integrity ──► critic ──► human gate
                                      │
                               delivery: git · local · out

Why Absoloop

Principle What it means in practice
Evidence-gated Narratives and “looks good” diffs are not acceptance.
Adversarial critic A read-only reviewer tries to disprove the result.
Hard budgets Iterations, wall clock, and dollars — resume or extend anytime.
Provider-native Grok Build, Claude Code, and Codex keep their own auth, tools, and sessions.
Two-layer teams Absoloop owns outer orchestration; each builder fans out with native Agent Teams / subagents.
Observable Live stream + watch + optional ZComb Kanban (--zcomb) + Markdown report.
Stdlib-first Core CLI + runner: Python 3.9+, zero pip deps to install.

Absoloop pixel mark

Two surfaces

Absoloop ships one CLI with two complementary workflows:

Surface When to use Entry points
Mission loop Long-running, checkpointed repair toward a /goal contract with a human gate absoloop "…", status, watch, approve / reject, resume / extend
Multi-provider harness One-shot / race / council / cross-provider review in isolated git worktrees absoloop run, build, review, inspect, apply, cancel

Both preserve provider-native auth and tooling. The mission loop is the default day-to-day path; the harness is for competitive or multi-agent one-shots.

Quick start

Requirements: Python 3.9+ and at least one provider CLI (claude, codex, and/or grok).

git clone https://github.com/BLERBZ/absoloop.git
cd absoloop
export PATH="$PWD/bin:$PATH"       # Windows: add absoloop\bin to User PATH

absoloop setup                     # guided wizard — PATH, providers, defaults
# or just:  absoloop               # first run offers the wizard automatically

The wizard walks you through five short steps, then can open Mission Briefing in the same session. Re-run anytime with absoloop setup --force.

absoloop doctor                    # health check anytime
absoloop "Make all tests pass"     # Mission Briefing → review card → Enter

Mission Briefing keys: Enter launch · o objective · e engine · m model · d delivery · n rename · g preview /goal · q abort · -y skip review.

absoloop status · watch · report   # see, stream, then open the report viewer
absoloop --zcomb                   # same briefing/launch as absoloop + ZComb UI
absoloop zcomb                     # browser Kanban for a running mission
absoloop approve                   # accept at the human gate
absoloop reject "use the v2 API"   # steer the next iteration
absoloop resume · extend
absoloop abort                     # stop a live loop
absoloop restart                   # factory reset: wipe runs/objectives (asks first)
absoloop schedule add|tick|daemon  # cron / interval triggers (never auto-approves)

Runner exit codes: 0 completed · 3 awaiting your approval · 2 stopped safely.

Full walkthrough: docs/getting-started.md.

Multi-provider harness

Same UX, three first-class backends — isolated git worktrees, normalized events, deterministic gates, cancelable runs:

absoloop run --provider grok "Fix the failing tests"
absoloop build --strategy race --providers grok,claude,codex "Implement #123"
absoloop review --implementer claude --reviewer codex "Harden this change"
absoloop inspect <run-id> · cancel <run-id> · apply <run-id>
Strategy Behavior
single One provider, one worktree, gates, patch
review Implementer works; another provider reviews read-only; fix pass; gates
race Parallel implementers; gates rank; winner re-verified
council Planner → parallel implementers → reviewer → integrator + gates

Guides: docs/multi-provider.md · architecture: docs/architecture/multi-provider-harness.md · config: absoloop.toml.example.

Shortcuts & Codex Micro

Keyboard, CLI, or a Work Louder Codex Micro HID pad (defaults on F13–F24 so typing never collides):

absoloop shortcuts list · layout · listen
absoloop do status
absoloop shortcuts export --format input -o micro-input.md

Full guide: docs/shortcuts.md.

How the loop closes

Deep dive: docs/mission-loop.md.

/goal contract

Every mission gets a generated .absoloop/goal.md: objective classification (tests / bugfix / feature / refactor / perf / docs), definition of done, strategy ladder, and a thinking escalation ladder shared by the contract and the runner.

absoloop goal · goal --regen · goal --check

Skills — loopers-toolbox

Scaffolded projects receive mission skills in each engine’s native path (.claude/skills/, .codex/skills/, .grok/skills/). Upstream sources include anthropics/skills, openai/skills, addyosmani/agent-skills, johnpapa/ai-ready, vercel-labs/agent-browser, and LobeHub game-development. See templates/skills/toolbox.json.

Delivery

Mode Result
local Changes stay unstaged (default)
git Commit to absoloop/<loop_id>
out Export files + report to ~/absoloop/out/<loop_id>/

Observability

absoloop watch     # live terminal dashboard (phase, budgets, activity feed)
absoloop status    # snapshot + exact next command
absoloop report    # regenerates report.md + opens lite infographic viewer
                   #   --terminal · --no-open · --md-only

ZComb Kanban UI (optional)

Browser dashboard with agent cards, Kanban board, and activity feed — vendored from ZComb. Requires Node.js 18+.

absoloop --zcomb                       # same briefing/launch as absoloop + Kanban
absoloop "Make all tests pass" --zcomb # objective + launch with Kanban UI
absoloop zcomb -C ./my-mission         # dashboard only (monitor a running mission)

On launch, opens http://localhost:3141 and bridges .absoloop/tmp/monitor.json + live.jsonl into .absoloop/zcomb/state/. Use absoloop zcomb anytime to open the dashboard without starting a mission. Details: zcomb/README.md · docs/mission-loop.md.

Telemetry lives under .absoloop/tmp/ while running; the ledger and report.md are the durable story of the mission.

Repo layout

bin/absoloop                 Public CLI (mission briefing + harness entry)
bin/absoloop_logo.py         Terminal infinity mark
absoloop_harness/            Multi-provider harness, briefing UX, report viewer,
                             shortcuts, schedules, ZComb bridge
zcomb/                       Optional Kanban UI (vendored from BLERBZ/zcomb)
templates/absoloop-run       Reference loop runner (copied into projects)
templates/skills/            Loopers-toolbox skill pack
tests/                       Characterization + harness suites
docs/                        Guides, architecture, brand assets
.github/                     CI, issue/PR templates

Documentation

Doc Contents
docs/getting-started.md Wizard, PATH, providers, first mission
docs/mission-loop.md Briefing, /goal, skills, delivery, watch/report, ZComb
docs/multi-provider.md Harness user guide
docs/architecture/multi-provider-harness.md Adapter contract, events, security
docs/schedule.md Cron / interval mission triggers
docs/shortcuts.md Keyboard + Codex Micro
docs/assets/BRAND.md Logos and palette

Index: docs/README.md.

Contributing

Absoloop is built for people who want Synergetic Loops — honest, compounding cycles with receipts. Patches welcome.

  1. Read CONTRIBUTING.md
  2. Keep bin/ + templates/absoloop-run stdlib-only
  3. Do not weaken integrity → critic → human gate
  4. Run python3 -m unittest discover -s tests before you push
git clone https://github.com/BLERBZ/absoloop.git
cd absoloop && export ABSOLOOP_HOME="$PWD"
python3 -m unittest discover -s tests -v

Community standards: CODE_OF_CONDUCT.md · security reports: SECURITY.md.

Good first issues

  • Docs clarifications and examples
  • Characterization tests for edge cases you’ve hit
  • Provider adapter hardening (probe / resume / cancel)
  • Report viewer and Mission Briefing UX polish
  • Shortcut catalog / Micro layout improvements

GitHub profile setup

A ready-to-publish org/profile README lives in docs/github-profile/ — logos included, with install steps for a BLERBZ/.github profile repo (or a personal username/username profile).

License

MIT © BLERBZ and Absoloop contributors.

Brand marks under docs/assets/ — see docs/assets/BRAND.md.

About

Make AI agents prove the work—not just produce it. Verifiable goals, bounded repair loops, and adaptive reasoning for Claude and Codex.

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages