# davebcn87/pi-autoresearch architecture

> Architecture diagram of the GitHub repository davebcn87/pi-autoresearch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/davebcn87/pi-autoresearch
- Repository: https://github.com/davebcn87/pi-autoresearch

## Overview

##### What this project is (type + purpose)

This repo is a **pi agent add-on** consisting of:

- A **pi extension** (`extensions/pi-autoresearch`) that provides **domain-agnostic experiment-loop infrastructure**:
- tools: `init_experiment`, `run_experiment`, `log_experiment`
- UI: a **status widget** and a **`/autoresearch` dashboard**
- persistent storage: appends run results to `autoresearch.jsonl` in the user’s target project
- A **pi skill** (`skills/autoresearch-create`) that provides **domain-specific orchestration**:
- asks/infer experiment goal, command, metric, scope
- writes session artifacts: `autoresearch.md` and `autoresearch.sh`
- starts the autonomous loop

##### What the file tree implies architecturally

From the tree:

- `extensions/pi-autoresearch/index.ts`
- single extension entrypoint (likely registers tools + UI routes/panels + reads/writes session files)
- `skills/autoresearch-create/SKILL.md`
- skill definition/instructions (pi skill metadata + prompt-like behavior)
- Root `package.json` / `package-lock.json`
- Node/TypeScript packaging for the extension

Key architectural inference: **two-layer separation**
- **Extension = platform capabilities** (tooling, persistence, UI)
- **Skill = policy + domain knowledge** (what to optimize, how to benchmark, which files matter)

##### What the README adds (runtime components + data flow)

Runtime loop described:

##### Skill writes
- `autoresearch.md` (human/agent resumable “session doc”)
- `autoresearch.sh` (benchmark runner that emits `METRIC name=number`)
##### Repeated loop
- edit → commit → `run_experiment` → `log_experiment` → keep/revert → repeat
##### Extension persists
- `autoresearch.jsonl` append-only history (per branch)
##### UI surfaces
- widget (always visible)
- `/autoresearch` dashboard (results table, best run)

External dependencies that matter in architecture:
- **Shell execution environment** (runs arbitrary commands)
- **Git** (auto-commit, branch-aware sessions, revert/keep decisions)
- **Target project repo** (where files live and are mutated)

##### Pi Agent Runtime
- hosts skills + extensions, provides tool invocation and UI surface
##### Skill: `autoresearch-create`
- config gathering / inference
- session bootstrap (branch creation, file creation)
- loop controller (decision logic: keep vs revert)
##### Extension: `pi-autoresearch` (TypeScript)
- Tool handlers:
- `init_experiment`
- `run_experiment`
- `log_experiment`
- UI:
- status widget
- `/autoresearch` dashboard
- Session I/O:
- read/write `autoresearch.md`
- append `autoresearch.jsonl`
##### User Project Workspace (the optimized repository)
- source files under test
- generated artifacts:
- `autoresearch.md`
- `autoresearch.sh`
- `autoresearch.jsonl`
##### Git (VCS)
- branches per session
- auto-commit after changes
- revert/checkout when discarding runs
##### Shell / Command Runner
- executes the benchmark command(s) (e.g., `pnpm test`, `lighthouse …`)
- returns stdout/stderr + exit code + wall-clock duration

- **Metric parser** (extracts `METRIC name=number` from output)
- **Result evaluator** (compares best/kept vs discarded given direction ↑/↓)

**Bootstrap phase**
- Pi Agent → Skill (`/skill:autoresearch-create`)
- Skill → User Project Workspace (writes `autoresearch.md`, `autoresearch.sh`)
- Skill → Git (create branch, initial commit)
- Skill → Extension tool: `init_experiment` (store config / initialize session)

**Loop phase (repeat)**
- Skill → User Project Workspace (edits files / applies changes)
- Skill → Git (commit changes)
- Skill → Extension tool: `run_experiment`
- Extension `run_experiment` → Shell/Command Runner (exec command)
- Shell → Extension (stdout/stderr, duration, exit code)
- Extension → (Metric parser) → numeric metric
- Skill (or extension) decides keep/revert (make this explicit)
- Skill → Git (revert/checkout if discard, or keep commit if good)
- Skill → Extension tool: `log_experiment`
- Extension `log_experiment` → User Project Workspace (append `autoresearch.jsonl`)
- Extension UI (widget/dashboard) ← reads from `autoresearch.jsonl` (and maybe `autoresearch.md`)

**Monitoring**
- Developer (human) → Pi UI (`/autoresearch`, widget)
- UI → Extension → reads `autoresearch.jsonl` → renders results/best run

##### Key architectural patterns

- **Separation of concerns**
- *Skill* = policy/orchestration (domain knowledge)
- *Extension* = infrastructure (tools, persistence, UI)
- **Event log / append-only history**
- `autoresearch.jsonl` as the durable run ledger
- **Resumability**
- `autoresearch.md` + `autoresearch.jsonl` allow continuation after restarts/context loss
- **Branch isolation**

##### Relevant technologies

- Extension: **TypeScript/Node** (`index.ts`, `package.json`)
- Skill: pi **Skill definition** (`SKILL.md`)
- Persistence: **JSONL** log + Markdown session doc
- Execution: **shell commands** + parsing `METRIC name=number`
- SCM: **Git** (commit, branch, revert)

##### Labels
- `init_experiment`, `run_experiment`, `log_experiment`
- `autoresearch.md`, `autoresearch.sh`, `autoresearch.jsonl`

- Payloads:
- “stdout/stderr + duration”
- “parsed metric (name, value, unit, direction)”
- “commit hash, status, description”

##### Don’t under-model: recommended component breakdown (maximally clear)

- Tool: `run_experiment` (exec + timing + output capture + metric parsing)
- Tool: `log_experiment` (append JSONL + auto-commit + notify UI)
- UI: widget
- UI: dashboard route `/autoresearch`
- Storage: jsonl reader/writer

**High-level (static)**
- Pi Agent Runtime
- Skill: `autoresearch-create`
- Extension: `pi-autoresearch`
- tools: init/run/log
- UI: widget + dashboard
- User Project Workspace
- `autoresearch.md`, `autoresearch.sh`, `autoresearch.jsonl`
- Git
- Shell/Command Runner

**Sequence (one iteration)**
Human → Skill → (edit files) → Git commit → run_experiment → Shell exec → metric parse → keep/revert via Git → log_experiment → append JSONL → UI refresh.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Global actors / entrypoints
    %% =========================
    Human["Developer (Human)"]:::actor

    %% =========================
    %% Pi Platform
    %% =========================
    subgraph "Pi Agent Runtime (hosts skills + extensions + UI surface)"
        Pi["Pi Agent Runtime"]:::pi

        subgraph "Skill Layer (policy + domain orchestration)"
            Skill["Skill: autoresearch-create"]:::skill
            SkillCfg["Config gathering/inference\n(goal,command,metric,scope)"]:::skill
            SkillBootstrap["Session bootstrap\n(branch+files)"]:::skill
            SkillLoop["Loop controller\n(keep vs revert)"]:::skill
        end

        subgraph "Extension Layer (infrastructure: tools + UI + persistence)"
            Ext["Extension: pi-autoresearch (TypeScript/Node)"]:::ext

            subgraph "Tool Handlers"
                ToolInit["Tool: init_experiment"]:::tool
                ToolRun["Tool: run_experiment"]:::tool
                ToolLog["Tool: log_experiment"]:::tool
            end

            subgraph "Execution + Parsing"
                OutputCap["Output capture\n(stdout/stderr,exit code,duration)"]:::ext
                MetricParser["Metric parser\nextracts METRIC name=number"]:::ext
                ResultEval["Result evaluator\n(compare best,↑/↓)"]:::ext
            end

            subgraph "UI Surfaces"
                Widget["Status widget (always visible)"]:::ui
                Dash["Dashboard: /autoresearch"]:::ui
            end

            subgraph "Session Storage I/O"
                JsonlRW["JSONL reader/writer\n(append-only ledger)"]:::storage
                MdRW["Markdown session doc I/O"]:::storage
            end
        end
    end

    %% =========================
    %% User workspace + external deps
    %% =========================
    subgraph "User Project Workspace (target repo under optimization)"
        Workspace["Workspace (source files + artifacts)"]:::workspace

        ARMD["autoresearch.md\n(resumable session doc)"]:::artifact
        ARSH["autoresearch.sh\n(benchmark runner)"]:::artifact
        ARJSONL[("autoresearch.jsonl\n(append-only history, per-branch)")]:::artifact
    end

    Git["Git (VCS)\n(branches,commit,revert/checkout)"]:::external
    Shell["Shell / Command Runner\n(exec benchmark command)"]:::external

    %% =========================
    %% Control + data flows (vertical)
    %% =========================
    Human -->|"uses /skill:autoresearch-create"| Skill
    Human -->|"views results"| Dash
    Human -->|"glance status"| Widget

    Skill -->|"runs within"| Pi
    Ext -->|"runs within"| Pi

    %% Bootstrap
    Skill -->|"creates branch"| Git
    Skill -->|"writes"| ARMD
    Skill -->|"writes"| ARSH
    Skill -->|"invokes"| ToolInit
    ToolInit -->|"initialize session/config"| MdRW
    MdRW -->|"read/write"| ARMD

    %% Loop
    Skill -->|"edits source files"| Workspace
    Skill -->|"commit changes"| Git
    Skill -->|"invokes"| ToolRun
    ToolRun -->|"exec command"| Shell
    Shell -->|"returns stdout/stderr+exit+duration"| OutputCap
    OutputCap -->|"parse METRIC"| MetricParser
    MetricParser -->|"metric (name,value,dir)"| ResultEval

    ResultEval -->|"decision signal"| SkillLoop
    SkillLoop -->|"keep commit"| Git
    SkillLoop -->|"revert/checkout discard"| Git

    Skill -->|"invokes"| ToolLog
    ToolLog -->|"append run result"| JsonlRW
    JsonlRW -->|"append-only write"| ARJSONL

    %% UI reads
    Dash -.->|"reads history"| ARJSONL
    Widget -.->|"reads current/best"| ARJSONL
    Dash -.->|"may read session doc"| ARMD

    %% Workspace containment
    Workspace -->|"contains"| ARMD
    Workspace -->|"contains"| ARSH
    Workspace -->|"contains"| ARJSONL

    %% Notes/annotations as nodes (kept vertical)
    subgraph "Key Patterns"
        Sep["Separation of concerns\nSkill=policy, Extension=infrastructure"]:::note
        Log["Event log durability\nJSONL append-only ledger"]:::note
        Resume["Resumability\n.md + .jsonl enable continuation"]:::note
        Branch["Branch isolation\nsession scoped per Git branch"]:::note
    end

    Sep -.-> Skill
    Sep -.-> Ext
    Log -.-> ARJSONL
    Resume -.-> ARMD
    Resume -.-> ARJSONL
    Branch -.-> Git
    Branch -.-> ARJSONL

    %% =========================
    %% Click events (from component_mapping)
    %% =========================
    click Ext "https://github.com/davebcn87/pi-autoresearch/tree/main/extensions/pi-autoresearch/"
    click ToolInit "https://github.com/davebcn87/pi-autoresearch/blob/main/extensions/pi-autoresearch/index.ts"
    click ToolRun "https://github.com/davebcn87/pi-autoresearch/blob/main/extensions/pi-autoresearch/index.ts"
    click ToolLog "https://github.com/davebcn87/pi-autoresearch/blob/main/extensions/pi-autoresearch/index.ts"
    click Widget "https://github.com/davebcn87/pi-autoresearch/blob/main/extensions/pi-autoresearch/index.ts"
    click Dash "https://github.com/davebcn87/pi-autoresearch/blob/main/extensions/pi-autoresearch/index.ts"
    click Skill "https://github.com/davebcn87/pi-autoresearch/blob/main/skills/autoresearch-create/SKILL.md"
    click SkillBootstrap "https://github.com/davebcn87/pi-autoresearch/tree/main/skills/autoresearch-create/"
    click SkillLoop "https://github.com/davebcn87/pi-autoresearch/tree/main/skills/autoresearch-create/"
    click Pi "https://github.com/davebcn87/pi-autoresearch/tree/main/extensions/"
    click Sep "https://github.com/davebcn87/pi-autoresearch/blob/main/README.md"
    click Log "https://github.com/davebcn87/pi-autoresearch/blob/main/README.md"
    click Resume "https://github.com/davebcn87/pi-autoresearch/blob/main/README.md"
    click Branch "https://github.com/davebcn87/pi-autoresearch/blob/main/README.md"

    click Human "https://github.com/davebcn87/pi-autoresearch/blob/main/README.md"
    click Workspace "https://github.com/davebcn87/pi-autoresearch/blob/main/README.md"
    click Git "https://github.com/davebcn87/pi-autoresearch/blob/main/README.md"
    click Shell "https://github.com/davebcn87/pi-autoresearch/blob/main/README.md"

    click JsonlRW "https://github.com/davebcn87/pi-autoresearch/blob/main/extensions/pi-autoresearch/index.ts"
    click MdRW "https://github.com/davebcn87/pi-autoresearch/blob/main/extensions/pi-autoresearch/index.ts"
    click OutputCap "https://github.com/davebcn87/pi-autoresearch/blob/main/extensions/pi-autoresearch/index.ts"
    click MetricParser "https://github.com/davebcn87/pi-autoresearch/blob/main/extensions/pi-autoresearch/index.ts"
    click ResultEval "https://github.com/davebcn87/pi-autoresearch/blob/main/extensions/pi-autoresearch/index.ts"

    click ToolInit "https://github.com/davebcn87/pi-autoresearch/blob/main/extensions/pi-autoresearch/index.ts"
    click Ext "https://github.com/davebcn87/pi-autoresearch/tree/main/extensions/pi-autoresearch/"
    click SkillCfg "https://github.com/davebcn87/pi-autoresearch/tree/main/skills/autoresearch-create/"
    click Skill "https://github.com/davebcn87/pi-autoresearch/tree/main/skills/autoresearch-create/"

    click Pi "https://github.com/davebcn87/pi-autoresearch/blob/main/README.md"
    click Skill "https://github.com/davebcn87/pi-autoresearch/blob/main/README.md"
    click Ext "https://github.com/davebcn87/pi-autoresearch/blob/main/README.md"

    click Sep "https://github.com/davebcn87/pi-autoresearch/blob/main/package.json"
    click Log "https://github.com/davebcn87/pi-autoresearch/blob/main/package-lock.json"
    click Resume "https://github.com/davebcn87/pi-autoresearch/blob/main/package.json"
    click Branch "https://github.com/davebcn87/pi-autoresearch/blob/main/package-lock.json"

    click Skill "https://github.com/davebcn87/pi-autoresearch/tree/main/skills/"
    click Ext "https://github.com/davebcn87/pi-autoresearch/tree/main/extensions/"

    click Pi "https://github.com/davebcn87/pi-autoresearch/blob/main/package.json"
    click Ext "https://github.com/davebcn87/pi-autoresearch/blob/main/package.json"

    click Human "https://github.com/davebcn87/pi-autoresearch/blob/main/README.md"
    click Dash "https://github.com/davebcn87/pi-autoresearch/blob/main/README.md"
    click Widget "https://github.com/davebcn87/pi-autoresearch/blob/main/README.md"

    click Ext "https://github.com/davebcn87/pi-autoresearch/blob/main/extensions/pi-autoresearch/index.ts"
    click Pi "https://github.com/davebcn87/pi-autoresearch/tree/main/extensions/"

    %% =========================
    %% Styles (color critical)
    %% =========================
    classDef actor fill:#ffffff,stroke:#111827,stroke-width:2px,color:#111827
    classDef pi fill:#1d4ed8,stroke:#0b2a6f,stroke-width:2px,color:#ffffff
    classDef skill fill:#2563eb,stroke:#0b2a6f,stroke-width:1.5px,color:#ffffff
    classDef ext fill:#1e40af,stroke:#0b2a6f,stroke-width:1.5px,color:#ffffff
    classDef tool fill:#0ea5e9,stroke:#075985,stroke-width:1.5px,color:#082f49
    classDef ui fill:#38bdf8,stroke:#075985,stroke-width:1.5px,color:#082f49
    classDef storage fill:#60a5fa,stroke:#1e3a8a,stroke-width:1.5px,color:#0b1b3a
    classDef artifact fill:#16a34a,stroke:#065f46,stroke-width:2px,color:#052e16
    classDef workspace fill:#22c55e,stroke:#065f46,stroke-width:2px,color:#052e16
    classDef external fill:#9ca3af,stroke:#374151,stroke-width:2px,color:#111827
    classDef note fill:#fbbf24,stroke:#92400e,stroke-width:2px,color:#111827
```
