UI: CLI + Dashboard

[brillout]

Status: brainstorming.

Note

Some of the features below won't make it for the MVP

CLI

I suggest that running $ framework does the following:

• Ensures the background process is running
  • The background process runs the local dashboard (e.g. localhost:4200), and background jobs
• Prints the list of commands (just convenience commands like framework run [prompt], framework logs, ... — not important since the UI already implements all features)
• Prints the CLI version
  • [Only if trivial to implement] Show whether the version is up-to-date (by using $ npm info).
    • Should be async (show static info first, then await npm server and show "up-to-date" label)
    • The CLI regularly auto-updates itself
    • Also show (✅ auto-update enabled).

Database

• .the-framework/LOGS.md contains the list of AI loops/prompts that were run via The Framework
  • We therefore don't need any real database, the .the-framework/ directory is the database (it isn't .gitignore so it's persisted)
  • A log entry can be a loop or a standalone prompt
    • A loop is a list of standalone prompts
  • Each log entry contains the Claude Code session ID (with a link such as https://claude.ai/code/session_01MU13ncNmLi5rz2xySmm5rZ, possible thanks to Claude's Remote Control)
  • We can very effeciently crawl repo files using $ git ls-files.
    • That's what Vike does and is has been working great. Note that it also lists untracked files.
• Commit messages authored by The Framework contain data.
  • For example, if the commit introduces changes that require refactoring, then TO-DO/maintenance is appended:

    [The Framework] Commit message
    
    TO-DO/maintenance
    

    E.g. because the PR introduced a bug fix using that applies minimal changes in order to make reviewing easier, but requires refactoring to be clean.

Dashboard

• Three sidebars:
  • First sidebar (on the left):
    • Three sections: Overview, Projects, Queue
      • Projects: shows the list of all projects where The Framework is activated
        • A project can be a repo, or a package inside a monorepo (but let's skip monorepo support if it's complex)
      • Queue: essentially all the TODO.md entries of all projects
      • Overview: some kind of nice overview of current prompts AI is working on, the queue, and recent projects
  • Second sidebar (on the left): shows the latest AI loops/prompts run via The Framework of the currently selected project (the most recently active project if none is selected)
    • In other words: clicking a project => essentially shows .the-framework/LOGS.md in the second sidebar
  • Thrid sidebar (on the right)
    • Show arbitrary views (e.g. when AI calls the function showMarkdown())
    • Show <Choices>
    • Stick top nav to jump between views (e.g. for jumping between files like PLAN.md and TODO.md)
• Main view: shows the last loop/prompt of the selected project (similar to https://claude.ai/code).
• A project is activated when it has a .the-framework/ directory
  • Installation: the user can click on a button "Add projects" => user can add a directory of repos, or a single repo
    • When adding a directory: we add all child directories (non-recursively) that are Git repos
    • Commits an empty .the-framework/LOGS.md with commit message [The Framework] install The Framework
      • If the Git repo is dirty, then commit the uncommitted changes with a commit message [The Framework] uncommitted changes
    • If easy to implement: support monorepos (project = package in monorepo)
• <Choices>
  • Ideally, choices always have a recommended choice (if a recommendation is missing, then pick first choice)
  • Click green button Accept (or shortcut Ctrl + Enter) => accepts (picks the recommended choices)
  • If [x] autopilot => auto-accepts after 10 seconds (while the UI says "move mouse to abort countdown")
  • All choices are shown at once in the right sidebar (no pagination, scroll instead, with sticky top nav to quick-jump between choices)

[suleimansh]

MVP scope (the cut)

Rom greenlit cutting hard, so this issue is the north-star epic. The MVP builds on what already exists in packages/framework/src/ (the dashboard is already "a pure projection of the FrameworkEvent stream", and store/run-store.ts already persists that stream). We evolve it, we don't rebuild.

In the MVP (3 slices):

• [The Framework] Persistent background dashboard process #302 Persistent background process: $ framework ensures a long-lived local dashboard that outlives a single run.
• [The Framework] Run history in the dashboard (single project) #303 Single-project loop/prompt history in the dashboard.
• [The Framework] Interactive <Choices> panel + autopilot auto-accept #304 Interactive <Choices> panel + autopilot 10s auto-accept (the demo money-shot). PR feat(framework): interactive plan-approval choice + autopilot (#304) #308.

All three slices are built. #302/#303 merged; #304 is PR #308 (open). The MVP dashboard is feature-complete once #308 lands.

Postponed (Rom: "feel free to postpone stuff here"):

• Projects sidebar / multi-project + monorepo support.
• Queue (all TODO.md entries) and Overview sidebars.
• .the-framework/LOGS.md as committed markdown DB. MVP keeps the existing .framework/ store (events.jsonl + run.json); the human-readable committed LOGS.md is a follow-up.
• CLI auto-update / npm info up-to-date check.

Data model decision: MVP ships on the existing .framework/events.jsonl store. The committed-markdown LOGS.md (this directory is the database) is deferred to a follow-up so we can dogfood sooner.

Build order: #302 -> #303 -> #304.

[brillout]

Superseded by:

• CLI #312
• Database #313
• UI #314