context-garden

Drive autonomous agent development by tending a context garden. You maintain principles, product overviews, phase goals, and specs as Markdown; context-garden turns that context into plans, working code, and reviewed pull requests. As your project grows, you refine the documents that guide the agents, and the agents carry the work through implementation, checks, review, and revision. Your job is to shape the goals, make decisions, and choose what ships.

You can change the direction of the project in the same place you define it. Each worker gets a focused brief built from the shared context, and each phase leaves evidence you can use to improve the next one: what shipped, where agents got stuck, how reviewers responded, and what the work cost.

Watch Context Garden build itself — one-minute video · Reproduce the film

Features · See it in action · Ontology · Getting started · Operating guide · Contributing · All documentation

What you can do

• Keep context useful as the project changes. Maintain principles, product overviews, goals, and specs in Git. Each worker's brief includes the shared context and its task's reading list, so the direction you set reaches the work being done.
• Turn goals into coordinated work. Plan a phase as tasks with acceptance criteria and dependencies. Run agents in parallel worktrees; stack related PRs and advance dependent tasks as changes merge.
• Close the review loop. Configured tests and lint gate PR creation. Automated reviewers check the task's criteria, and failed checks or review feedback drive bounded revisions. Add persona reviews for another perspective.
• Handle decisions without losing the thread. Answer a worker's question, approve scope, send a PR back, or recover a stopped task. The task keeps its brief, run output, review evidence, and history together.
• Watch autonomous work as it happens. Now shows runs in flight, progress excerpts, what is queued next, and where the phase stands. The Board gives you columns, a task list, and a backlog you can reorder across phases.
• Compare models by the work they get accepted. Inspect cost per accepted task, first-pass approval, revision rounds, and lead time by model and difficulty. Compare per-run costs, run model trials, set budgets, and account for delegated operator spend.
• Use each phase to improve the next. Retrospectives bring together outcomes, friction, costs, and persona reviews. They can propose follow-up work or identify blockers before a phase closes; you refine the context for what comes next.
• Bring your existing project and tools. Onboarding drafts context and a first phase from your repository. Use Claude Code, Codex, or a custom CLI harness with your project's setup, test, and lint commands; choose local, SSH, remote lease-based, or manual workers.

The scheduler itself uses no model tokens: it polls, orders tasks, collects results, and advances state in Python. Models do the planning, implementation, reviews, agent-assisted revisions, and retrospectives. A delegated operator session also uses tokens. Waiting for CI does not require an agent to sit in a chat polling it.

Feature tour

Watch the work move

Now is the live view of the loop: workers and reviewers in flight, progress from their output, the next tasks, and phase progress. Open a run to inspect its evidence. Below is the garden developing context-garden itself.

Handle the decisions that need you

The Inbox brings worker questions, draft approvals, and PR triage together. Answer a question to resume the work, approve the next tasks, or send a draft PR back with feedback.

This small example garden shows a worker asking about export behavior and two tasks awaiting approval.

Shape the plan across phases

The Board backlog puts upcoming work in phase order, with controls to change priority and move tasks between phases. Switch to columns for state or to the list for a compact view of tasks and PRs.

See which models work well for your tasks

The comparison charts lower down Now connect model choices to outcomes. Cost per accepted task, first-pass approval, revision rounds, and lead time are broken out by difficulty. Cells include sample counts; sparse results are marked so a small sample does not look like a reliable winner.

The per-run comparison separates work, revision, review, and other activities by harness and model. Use it alongside the outcome charts when tuning model assignments and the amount of review a task needs. The Costs page provides spending history and additional filters.

These are snapshots of this project's development history over the selected 24-hour window, not controlled model benchmarks or estimates for your project.

Keep the context and decisions within reach

The Trellis makes dependencies visible. Task pages keep the brief, acceptance criteria, worker questions, and recorded usage together. Phase pages connect the work to goals and specs; closed phases remain available in the Herbarium.

What you maintain

Your garden is a git repository of Markdown files. It holds the context and task history; each product points to its code repository. The garden driving this tool lives at joshmarcus/garden.

my-garden/
  garden.yaml                    # products, harnesses, capacity, checks
  principles/00-index.md          # shared rules included in every brief
  widget/
    product.md                   # product context and development conventions
    phase-01/
      goals.md                   # outcomes, scope, definition of done
      specs/                     # designs and requirements
      tasks/                     # task briefs and scheduler-managed state
  .garden/                       # local run records and working state (gitignored)

Edit and version the context in your usual editor. Use garden commands or the UI for task status changes.

Install

You need Python 3.11+, git, a logged-in Claude Code or Codex CLI, and GitHub access through authenticated gh or GITHUB_TOKEN. Linux and macOS are supported; on Windows, run garden inside WSL. Your product repository needs a committed base branch, a GitHub remote you can push to, and a configured git author identity.

Install the released command and library from PyPI:

python -m pip install context-garden
garden --help

The supported library surface currently consists of the documented modules under garden. For example, task-document tools can parse and render the YAML frontmatter used by a garden:

from garden import __version__
from garden.model import join_frontmatter, split_frontmatter

document = join_frontmatter({"id": "CG-1", "status": "ready"}, "## Goal\n\nShip it.")
metadata, body = split_frontmatter(document)
print(__version__, metadata["id"], body.strip())

Other modules are implementation details unless they are documented here or in the linked guides. Source contributors can instead use an editable checkout:

git clone https://github.com/joshmarcus/context-garden
cd context-garden
uv venv
uv pip install -e .
source .venv/bin/activate
garden --help

Without uv, create the environment with python3 -m venv .venv, activate it, and run python -m pip install -e .. Keep that environment active when you move into your garden directory.

Your first project

The steps below are a compact preview. The getting-started guide adds platform notes, expected outcomes, command explanations, and setup recovery.

1. Create a garden and choose a harness

From the tool checkout, with its environment active:

garden init ../my-garden --name my-garden

The default harness is Claude. To use Codex, set harness: codex in ../my-garden/garden.yaml before onboarding. See Codex setup for authentication and model configuration.

Workers use a private HOME and a scrubbed environment. Saved harness credentials are copied into private directories for each dispatch. If your credentials live elsewhere, configure worker_env.config_dirs; individual approved tool files use worker_env.config_files. Keep secrets out of tracked YAML. See worker environment and configuration.

2. Draft context from your repository

Replace the path below with your project's local checkout:

garden onboard /absolute/path/to/widget --into ../my-garden
cd ../my-garden
git init

Onboarding attempts GitHub discovery and calls the configured planner, so this step uses a model. It infers a product name and creates phase-01 with draft tasks. The examples below assume that name is widget.

Read widget/docs/onboarding.md to see what was found, inferred, or left unresolved. Review widget/product.md, the principles, phase goals, and tasks. Correct the scope and the product's setup.command, setup.test, and setup.lint in garden.yaml. Onboarding does not install project dependencies or prove those commands work; validate them in a disposable checkout before approving work.

cd ../my-garden
garden new-product widget --repo /absolute/path/to/widget --base-branch main
garden new-phase widget phase-01

garden plan widget/phase-01 --draft

3. Review the plan before starting work

Merge these settings into the generated garden.yaml, keeping its product and harness configuration. They make approval explicit and start with one work slot and one review slot:

max_parallel: 1
review_parallel: 1
plan:
  auto_approve: false
discovered:
  auto_approve_blocking: false
review:
  enabled: true
github:
  draft_pr: true
  project_users: [] # additional PR authors to observe; the authenticated user is always included
  automerge: false
  # Tier pools may spread work across harness/model members.
models:
  medium:
    - {harness: claude, model: claude-sonnet-5, weight: 2}
    - {harness: codex, model: gpt-5.6-terra, weight: 1}
dispatch: {spread: quota_aware}   # round_robin | weighted | quota_aware
harnesses:
  claude: {models: {easy: haiku, medium: sonnet, hard: opus}}
  codex:  {models: {easy: gpt-5.6-luna, medium: gpt-5.6-terra, hard: gpt-5.6-sol}}
checks:
  pre_pr: [{name: tests, command: "pytest -q -x"}]

These are suggested first-run settings, not package defaults: planning and blocking discovered work otherwise default to automatic approval. --draft overrides that behavior for one planning call. A phase budget is optional: garden budget widget/phase-01 50 pauses new dispatch at $50; it does not cancel work already running.

garden doctor
garden trellis
garden validate

doctor checks configuration, repositories, the graph, and worker logins. It sends a small harness prompt and executes a configured notification command, so it is not an offline check. Resolve its failures before continuing. validate checks the graph and reading lists; approval also rejects incomplete briefs. Use garden brief ID --stats to inspect a task's context size.

4. Approve work and follow the first PR

garden approve --all widget/phase-01
garden serve

Use garden approve ID instead of --all to start with a single task. Open http://127.0.0.1:8765. serve starts the web UI and the scheduler: approved, unblocked work can now dispatch. For a look around before launching work, use garden serve --no-watch instead.

Follow the task's runs and evidence, answer any questions in the Inbox, and inspect the resulting draft PR and automated review. Mark it ready with the UI or garden triage ID --ready; send it back with garden triage ID --changes "feedback". Once review and CI are satisfactory, merge on GitHub. The next poll records the merge and advances dependent work.

From another terminal with the same environment active, run garden status, garden inbox, or garden observe --profile quiet. garden watch runs the scheduler without the web UI; garden tui opens the terminal interface.

Use the CLI

The CLI operates the same garden as the web UI and TUI. Inspect a plan, follow the workers, handle decisions, and compare outcomes from your terminal:

garden status
garden observe --profile quiet
garden inbox
garden brief WID-003 --stats
garden runs WID-003
garden costs --since 24h --by model
garden metrics widget/phase-01

Run commands from your garden directory with the installed environment active. Replace WID-003 and widget/phase-01 with your task and phase. garden watch runs the scheduler on its own; garden observe --follow follows progress alongside an existing controller. garden --help lists the command groups. Difficulty tiers route each task to a model, so cost follows difficulty. A top-level tier can instead be a pool of harness/model members: round_robin alternates, weighted repeats members by weight, and the default quota_aware behavior halves a member's share for dispatch.quota_window_hours after its usage-limit event, until its probe succeeds, while skipping a paused harness entirely. A task's harness: or model: remains a pin. review.pool accepts the same member list for alternating review accounts, and garden trial -c tier:medium expands a tier pool into contenders. garden.<GARDEN_ENV>.yaml and a gitignored garden.local.yaml layer on top for a work or per-machine setting; examples/garden.work.yaml shows ssh workers, a Jenkins log analyser and a product whose dependencies and tests are not Python.

The CLI guide walks through planning and approval, following runs, answering workers, reviewing PRs, recovering tasks, and exporting JSON for scripts.

Keep the loop running

A dispatch pause still allows collection, checks, reviews, and merges. Installation maintenance uses a separate drain-and-resume protocol. Run one long-lived controller per garden and keep its UI on loopback or behind authenticated access.

The Config page shows effective settings and pending configuration changes.

The operating guide covers merge policy, capacity, remote workers, recovery, maintenance, configuration reloads, GitHub Enterprise, and operator handoffs. The architecture guide explains the full behavior and configuration boundaries.

Development and documentation

• Documentation map: the canonical path for each audience.
• Getting started: installation through the first completed PR.
• Contributor guide: setup, repository structure, tests, and docs.
• CLI guide: day-to-day commands, control modes, and scripting.
• Design: vocabulary and the development loop.
• Architecture: modules, state, scheduling, configuration, and merge policy.
• Worker protocol: briefs, results, transports, and failure recovery.
• Codex setup: harness configuration and interactive workflows.
• Test suites and worker CI: focused checks and the full regression gate.
• Screenshot capture: reproduce this README's example garden and images.

For development, follow the contributor guide. Tests use fake harnesses and spend no model tokens.

MIT licensed. See LICENSE.