From CLI Harness to Product

The route

5 steps to Done

1. 01

   Implement persistent sessions

   Sessions turn a script into a tool people trust with long work.

   Preview prompt + verify gate ▾ Hide ▴

   Add session persistence to the harness. Each session stores: a generated ID and user-friendly title (derived from the first task), the full message history, todo/plan state, the working directory, model and config snapshot, timestamps, and status (active, completed, escalated, cancelled). Store as JSON files under a sessions directory (or SQLite if already available). Implement: session creation on run start, incremental saving after every turn (crash-safe), `list` showing recent sessions with title/status/age, and `show <id>` printing a readable transcript summary. Verify a killed process leaves a loadable session file.

   • ✓ Saved after every turn, not on exit
   • ✓ Session includes plan state and cwd
   • ✓ Kill -9 mid-run leaves a loadable session
2. 02

   Build true resume

   Resume is the feature that proves your state model is honest.

   Preview prompt + verify gate ▾ Hide ▴

   Implement `resume <id>`. Requirements: restore message history, todo state, and working directory; re-render the plan reminder block from restored state; inject a brief resume preamble telling the model it is continuing a previous session with a one-line status summary; validate the environment still matches (cwd exists, git branch check with a warning on mismatch); then continue the loop normally. Test the acceptance case: start a 4-step task, kill the process after step 2, resume, and verify the agent continues from step 3 without redoing or forgetting work.

   • ✓ History, plan, and cwd all restored
   • ✓ Environment mismatch warns clearly
   • ✓ Continuation starts at the correct step
3. 03

   Layer the configuration system

   Every serious tool answers 'where do I change that?' the same way.

   Preview prompt + verify gate ▾ Hide ▴

   Implement layered configuration with precedence: built-in defaults < user config file (~/.config/<agent>/config) < project config file (./.<agent>.toml or similar) < environment variables < command-line flags. Configurable at minimum: model name, max turns, tool permissions (e.g. allow run_command), session directory, and API key source (env var name - never the key itself in files). Add `config show` printing the effective merged config with each value's source layer, and `config set` for the user file. Validate on load with actionable errors ('unknown key X, did you mean Y?').

   • ✓ Precedence order implemented and tested
   • ✓ Effective config shows value origins
   • ✓ API keys referenced by env name only
4. 04

   Polish first-run and errors

   The first two minutes decide adoption.

   Preview prompt + verify gate ▾ Hide ▴

   Build the first-run experience. On first invocation without config: greet briefly, check for the API key env var and explain exactly how to set it if missing, run a one-token connectivity test with a clear pass/fail, write a starter user config, and suggest a first command. Then do an error-message pass over the whole CLI: every failure a new user can hit (bad key, no network, missing directory, invalid flag) must state what happened and the exact next action. Test by running as a fresh user on a machine without setup and noting every point of confusion.

   • ✓ Missing key produces exact setup instructions
   • ✓ Connectivity test gives clear pass/fail
   • ✓ Fresh-machine walkthrough documented
5. 05

   Package and version it

   Distribution is part of the architecture.

   Preview prompt + verify gate ▾ Hide ▴

   Package the agent for distribution. Requirements: proper package metadata (name, version, entry point) so users install with one command and get an `agent` binary on PATH; `--version` reporting version and model defaults; a CHANGELOG.md started with the current version's notable behavior (people track agent behavior changes like API changes); a README with the 2-minute quickstart matching the first-run flow; session/config directories created on demand with sane permissions. Verify on a clean environment (fresh virtualenv or container): install, first run, one task, resume - all green.

   • ✓ One-command install produces a PATH binary
   • ✓ Version and changelog in place
   • ✓ Clean-environment test passes end to end

Research-backed

Sources behind this flow