super-duper

super-duper is a planning and execution CLI. It turns a goal into a hierarchical plan, fulfills the leaf tasks, and writes validated artifacts to disk.

It is a Python CLI built on LiteLLM and ChromaDB, with workspace tools. You can read the code on GitHub or skip ahead and see the proof.

View on GitHub See the proof

The problem

Most autonomous coding agents either dump a whole solution in one pass or keep spending tokens with no plan tree you can inspect.

I needed a path from a natural-language goal to files on disk. The plan had to stay hierarchical with each leaf as a bounded unit of work, and nothing could be marked done until local checks and an LLM validation passed. 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 and get a plan I can read, then generate it leaf by leaf with state kept in ChromaDB so an interrupt does not throw away the run.

A local CLI was enough for that. LiteLLM talks to the provider, and 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. It walks the 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, and multi-file package planning. It also has a --product mode that does the layout first and then ordered vertical slices, plus 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, and non-secret knobs live in app.yaml. A pytest suite covers the core paths.

Three decisions

These are the three choices I would defend in a design review.

1. The plan is a tree, and the agent fulfills 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), and generates an artifact, then validates it 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 run before LLM validation.

Local checks run first, covering the FILE header, placeholders, syntax, failed RUN results, and an optional workspace compileall. Only then does LLM validation run. I wanted to catch obviously broken files without another model call every time, because paying for validation on output that never should have left the tool loop is a waste. Cheap validation is the default in app.yaml. The model still judges semantic completion, but it does not get the first look at a syntax error.

3. New, continue, replan, and resume are modes I own.

Startup resolves NEW GOAL, CONTINUE, REPLAN, or RESUME (including --checkpoint). --replan cannot combine with --resume or --checkpoint, and --confirm-plan can pause for layout approval before codegen. max_agent_rounds caps the loop, and 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 and does not turn into 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/

The public repo also confirms config via app.yaml plus .env, LiteLLM models, and ChromaDB under ./chroma_db/ by default. It documents the READ / RUN / PATCH tools, --repo for checkout-aware runs, and --product for automatic MVP layout and slices, and the architecture notes are in docs/ARCHITECTURE.md.

super-duper runtime architecture: Entry through config and run modes into hierarchical ChromaDB plan, agent loop over leaves with cheap then LLM validation, workspace writes
The runtime map starts at Entry (python app.py) and goes through config and run modes into a hierarchical plan stored in ChromaDB. From there an agent loop walks the open leaves, runs cheap validation before LLM validation, and writes to workspace/ and the session logs, with explicit stop outcomes that include needs_replan and round_limit.

Why I built it this way

I hold these boundaries whenever an agent is allowed to touch a workspace. I want a plan I can read and a grade that starts with local checks before a model pass, and I want modes that make spend a choice.

Keeping the work as a tree of leaves makes progress reviewable, and running cheap validation first keeps obvious failures cheap. Exposing new, continue, replan, and resume means I decide when the loop burns another round. If I am going to let an agent write files, I want the plan and the stop conditions to be things I can name out loud.