super-duper
A planning and execution CLI that turns a goal into a hierarchical plan, fulfills leaf tasks, and writes validated artifacts to disk.
The problem
Most autonomous coding agents either dump a whole solution in one pass or keep spending tokens with no clear plan tree you can inspect.
I needed a path from a natural-language goal to files on disk where the plan stays hierarchical, each leaf is a bounded unit of work, and nothing is marked done until local checks and an LLM validation pass. What was missing was an agent loop I can pause, resume, and replan without treating the whole run as one opaque burn.
Why I built it
Day to day, I wanted to state a goal, get a plan I can read, generate leaf by leaf, and keep state in ChromaDB so an interrupt does not throw away the run.
A local CLI was enough for that. LiteLLM talks to the provider. ChromaDB holds plans, artifacts, and checkpoints. Validated files land under workspace/, with session logs under logs/.
What I built
super-duper is a CLI agent that plans a hierarchical task tree from a goal, walks open leaves with context retrieval and codegen, validates with cheap local checks before LLM validation, persists state in ChromaDB, and writes artifacts to a workspace. It supports workspace tools (READ / RUN / PATCH), optional --repo awareness for discovery and in-place edits, multi-file package planning, --product mode for layout then ordered vertical slices, and run modes for new goal, continue, replan, and resume.
You start with python app.py run-agent or python app.py plan, after copying app.yaml.example to app.yaml and .env.example to .env. Secrets stay in .env. Non-secret knobs live in app.yaml. A pytest suite covers the core paths.
Three decisions
These are the craft bets I would defend in a design review, each one about readable plans, honest completion, or human control of spend.
1. Plan as a tree; fulfill leaves.
The LLM decomposes a goal into a hierarchical plan with normalized JSON, depth and leaf caps, and optional package-aware leaves (one leaf per module). The agent loop always picks the next open leaf, retrieves context (and optional repo files), generates an artifact, then validates before marking that leaf complete. I was counting on a plan I can inspect in ChromaDB outliving a single chat response, because the failure I care about is a flat todo list that hides how big the work actually is. Hierarchical planning with smarter post-processing keeps the tree from exploding while still naming the real modules.
2. Cheap gates before LLM validation.
Local checks run first: FILE header, placeholders, syntax, failed RUN results, and optional workspace compileall. Only then does LLM validation run. I was counting on catching obvious broken files without another model call every time, because the failure I care about is paying for validation on output that never should have left the tool loop. Cheap validation is the default in app.yaml. The model still judges semantic completion; it does not get the first look at a syntax error.
3. Modes you own: new, continue, replan, resume.
Startup resolves NEW GOAL, CONTINUE, REPLAN, or RESUME (including --checkpoint). --replan cannot combine with --resume or --checkpoint. --confirm-plan can pause for layout approval before codegen. max_agent_rounds caps the loop; stop outcomes include complete, blocked, needs_replan, and round_limit. The bet was that unsupervised burn is a mode failure, not a feature. I keep replan and resume as explicit human choices so an interrupt or a bad plan becomes a decision, not an endless retry.
Proof
You can follow the same paths from the public README and docs/OPERATOR-GUIDE.md.
python app.py run-agent --goal "Write a hello-world Python script" python app.py plan --plan_goal "Write a hello-world Python script" python app.py run-agent --replan --goal "…" python app.py run-agent --resume ls workspace/
From the public repo you can also confirm: config via app.yaml plus .env, LiteLLM models, ChromaDB under ./chroma_db/ by default, tools READ / RUN / PATCH, --repo for checkout-aware runs, --product for automatic MVP layout and slices, and architecture notes in docs/ARCHITECTURE.md.
python app.py) through
config and run modes into a hierarchical plan stored in ChromaDB, then
an agent loop over open leaves with cheap validation before LLM
validation, writing to workspace/ and session logs, with
explicit stop outcomes including needs_replan and round_limit.
Why I built it this way
These boundaries are the same ones I hold when an agent is allowed to touch a workspace: a plan you can read, a grade that starts with local checks and then a model pass, and modes that make spend a choice.
I keep the work as a tree of leaves so progress stays reviewable. I run cheap validation before LLM validation so obvious failures stay cheap. I expose new, continue, replan, and resume so I own when the loop burns another round. If you are going to let an agent write files, the plan and the stop conditions should still be something you can name out loud.