# seed

> A minimal self-growing agent that starts with a single shell-execution tool and builds its own memory, tools, and behavior session by session into a local directory.

Seed is a minimalist AI agent framework created by Vivek Haldar, designed to be the smallest possible starting point from which an autonomous agent can grow. It ships as a single Python file (`seed.py`) that calls a language model with one tool — `exec` — which runs shell commands. Everything else the agent needs must be grown by the agent itself, session by session, into a local `self/` directory.

## What It Is

Seed is a self-bootstrapping agent harness: rather than providing a pre-built set of tools, memory systems, and conventions, it gives the agent a blank slate and the ability to execute shell commands. The agent reads its system prompt from `self/SELF.md` and can write anything it wants to retain — tools, notes, behavioral rules — back into `self/`. This design means each agent instance diverges based on its own experiences, making every planted directory a distinct individual.

## How the Growth Model Works

The core philosophy is that everything an agent normally receives from a framework — tools, memory, skills, conventions — must instead be *grown* by the agent itself. On first run, Seed copies `seed.py` and `run_seed.sh` into the working directory, initializes `self/SELF.md`, and commits those files into a fresh git repo. The git history becomes part of that individual agent's record. Sessions are ephemeral: nothing outside `self/` survives between runs, so the agent must actively write what it wants to keep.

- A verbatim transcript of every session is recorded to `self/sessions/*.json` as a flight recorder — not loaded at boot, but readable by the user or by tools the agent grows to study its own past.
- One seed, many individuals: each directory planted grows a different agent.

## Setup Path

Installation uses `uvx` and requires no local clone:

```
mkdir my-agent && cd my-agent
uvx --from git+https://github.com/vivekhaldar/seed.git seed
```

Subsequent sessions use the local runner (`./run_seed.sh`) without needing `uvx` again. Model selection is handled entirely by Simon Willison's `llm` library. The default model is `openai-codex/gpt-5.6-sol`, using the ChatGPT login from the Codex CLI. Bundled providers include OpenAI (via Codex subscription or API key), Anthropic, Gemini, and OpenRouter — the last of which unlocks hundreds of additional models with a single key.

## Design Influences and Tradeoffs

The README points to a dedicated `docs/DESIGN.md` that covers the conceptual lineage: McCarthy's metacircular evaluator, homoiconicity, prior art in self-modifying agents, and the risks consciously accepted. The design deliberately avoids framework abstractions, betting that a sufficiently capable language model can construct its own scaffolding more flexibly than any pre-built framework could anticipate. The tradeoff is that early sessions may be unproductive until the agent has grown useful tools, and the `exec` tool gives the agent broad shell access — a deliberate but significant security surface.

## Current Status

The repository was created in late August 2025 and had 97 stars within days of creation, signaling early community interest. It is licensed under the Sovereign Source License (SSL) v0.3, a non-standard license maintained by the Smart Assets project — not an OSI-approved open-source license. Active development is ongoing, with the last push recorded shortly after creation.

## Features
- Single-file agent core (seed.py)
- Shell command execution via exec tool
- Self-modifying self/ directory for persistent memory and tools
- Session transcripts recorded as JSON flight recorder
- Git-tracked agent history from first run
- Model-agnostic via Simon Willison's llm library
- Supports OpenAI, Anthropic, Gemini, and OpenRouter providers
- One-command bootstrap with uvx
- Local runner script for repeat sessions
- Each planted directory grows an independent agent instance

## Integrations
OpenAI (via Codex CLI or API key), Anthropic, Google Gemini, OpenRouter, llm (Simon Willison's library)

## Platforms
API, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/vivekhaldar/seed
- Documentation: https://github.com/vivekhaldar/seed/blob/master/docs/DESIGN.md
- Repository: https://github.com/vivekhaldar/seed
- EveryDev.ai: https://www.everydev.ai/tools/seed-agent