Skip to content
soft-fig

Growlight Overview

A garden is never finished. Packages drift from their notes, a decision goes unrecorded, a snapshot goes stale, an incident never gets written up. That upkeep is small, well-shaped work that piles up while you do something else. Growlight is a tool the garden ships to drain it: an autonomous work loop that takes items off a backlog, session after session, while you are away.

It is not a second product. The garden is what you own and live in; growlight is one way to keep it growing. You can use a garden without it.

The core bet: a curated baton beats a lossy summary

Section titled “The core bet: a curated baton beats a lossy summary”

Long assistant sessions rot: the context fills with dead ends and compacting it throws away the details you needed. Growlight never /compacts. Each iteration is a fresh session reseeded from a small baton that points at durable state instead of carrying it:

  • the garden, read through softfig-mcp;
  • code repos, read through git.

The baton says what was just done, what to do next, and what a human still owes an answer on. Because it points rather than accumulates, every session starts clean and reads only what the next step needs.

The pieces

Section titled “The pieces”

The backlog. The work queue lives in the garden under growlight/backlog/. Items are milestones (a body of work split into ordered slices) or standalone tasks, each with a status such as queued, active, blocked (needs a human decision) or deferred (done except for a human-only step, such as a hardware test or a merge). See Customizing for the shape.

The protocol. A fixed operating contract injected at the top of every session: boot from the baton, check budgets, do one coherent chunk, hand off. The baton changes each roll; the protocol does not.

The baton-log. An append-only, numbered record of every iteration in growlight/baton-log/. Audit history, never re-injected.

Budgets. A context budget rolls the session before the window fills. A 5-hour budget stops new work near the account’s rolling limit, leaving room for a clean handoff, and a weekly guard is the outer backstop. All are tunable.

Reports. Things an agent notices but should not fix mid-chunk (a misbehaving verb, a flaky test, doc drift, a question for you) are filed as tagged reports under growlight/reports/. List them with softfig growlight reports.

growlightd. The one control plane. A user daemon that runs every growlight session, whether you arm one agent or several; a single agent is a fleet of one. See Running.

Why a garden suits a loop

Section titled “Why a garden suits a loop”
  • The work is legible and bite-sized. Small, semantically named files, a map at the root, and a backlog of upkeep: a shape a patient agent can chip away at one slice at a time.
  • Writes are typed. Every change goes through soft-fig’s write verbs, which stamp the conventions and record an intentional commit. An unattended agent inherits that safety: it mutates the garden through the same narrow surface you do and never touches sealed secrets or keys. A fleet of writers stays safe because they cannot write any other way.

What it can drain

Section titled “What it can drain”

Backlog items can be bound to a code repository, so the same machinery that tidies the garden also builds project work on feature branches. The loop never merges and never pushes; landing work is your call.

Next

Section titled “Next”