Git-native issue tracker for AI agent workflows.

Replaces beads in the overstory/mulch ecosystem. No Dolt, no daemon, no binary DB files. The JSONL file IS the database.

bun install -g @os-eco/seeds-cli

Or try without installing:

npx @os-eco/seeds-cli --help

git clone https://github.com/jayminwest/seeds
cd seeds
bun install
bun link              # Makes 'sd' available globally

bun test              # Run all tests
bun run lint          # Biome check
bun run typecheck     # tsc --noEmit

# Initialize in your project
sd init

# Create an issue
sd create --title "Add retry logic to mail client" --type task --priority 1

# List open issues
sd list

# Find work (open, unblocked)
sd ready

# Claim and complete
sd update seeds-a1b2 --status in_progress
sd close seeds-a1b2 --reason "Implemented with exponential backoff"

# Commit .seeds/ changes to git
sd sync

Every command supports --json for structured output. sd list, sd ready, sd search, sd show, sd blocked, and sd stats also accept --format <markdown|compact|plain|ids|json>; --json is an alias for --format json. The ids mode prints issue IDs one per line for shell pipelines, e.g. sd list --label bug --format ids | xargs sd close. Global flags: -v/--version, -q/--quiet, --verbose, --timing. ANSI colors respect NO_COLOR.

See Planning below for the end-to-end workflow.

sd plan adds structured planning that spawns child seeds. Use it when work is large or ambiguous enough that an LLM benefits from decomposing it before implementing — for small, well-scoped tasks just sd create directly.

The walkthrough is a three-step loop: prompt → fill → submit.

sd plan prompt seeds-9c4d --json

Returns a structured prompt request the LLM can fill in:

{
  "plan_request": {
    "seed": "seeds-9c4d",
    "template": "feature",
    "instructions": "Fill every section. Required fields are marked.",
    "sections": [
      { "name": "context", "required": true, "kind": "text", "min_length": 50, "prompt": "Why does this work need to happen?", "prior_art": [] },
      { "name": "approach", "required": true, "kind": "text", "prompt": "What's the chosen approach, and why this over alternatives?", "prior_art": [] },
      { "name": "steps", "required": true, "kind": "steps", "min": 2, "prompt": "Decompose into ordered, independent implementation steps." },
      { "name": "acceptance", "required": true, "kind": "list", "min": 1, "prompt": "Concrete, verifiable conditions for plan completion." }
    ],
    "validation": { "all_required_present": true, "min_steps": 2, "min_acceptance": 1 }
  }
}

The LLM produces a submission JSON in the same shape, with concrete content. Each steps[] entry becomes a child seed; blocks: [step_index] translates into seed-level blockedBy dependencies.

{
  "template": "feature",
  "sections": {
    "context": "...",
    "approach": "Use AJV to validate template-driven plans, mirroring mulch's custom_types pipeline.",
    "steps": [
      { "title": "Schema generator", "type": "task", "priority": 1, "blocks": [] },
      { "title": "Submit command", "type": "task", "priority": 1, "blocks": [0] },
      { "title": "Show command",   "type": "task", "priority": 2, "blocks": [0] }
    ],
    "acceptance": ["End-to-end submit + show works"]
  }
}

sd plan submit seeds-9c4d --plan plan.json

Validates against the template, spawns one child seed per step, wires blockedBy from step.blocks, and writes a plans.jsonl row with status approved.

sd plan show pl-a1b2                   # sections, children, recursive sub-plans
sd plan outcome pl-a1b2 --result success
sd plan review pl-a1b2 --by alice      # optional, informational

Outcomes (success | partial | failure) are storage-only — aggregation and retros are out of scope and left to teams. Review is suggested but never gating: sd plan show prints a "review suggested" hint when the plan is approved/active and no reviewer is recorded.

refactor is opt-in via --template refactor — it has no matching seed type so seeds does not auto-route to it. Custom templates declared under plan_templates: in .seeds/config.yaml override the built-ins.

A step can declare plan_template: <name> to spawn a child seed that requires its own sub-plan. The child is created with requires_plan: true and is hidden from sd ready until its plan is submitted. sd plan show recursively renders nested plans up to max_plan_depth (default 3).

Full spec: see PLAN_SPEC.md.

Seeds stores all data in JSONL files inside a .seeds/ directory — one JSON object per line, fully diffable and mergeable via git. Advisory file locks (O_CREAT | O_EXCL) and atomic writes (temp file + rename) ensure safe concurrent access from multiple agents. The merge=union gitattribute handles parallel branch merges; dedup-on-read (last occurrence wins) resolves any duplicates. See CLAUDE.md for full technical details.

Beads works but carries baggage overstory doesn't need:

.seeds/
  config.yaml          # Project config: project name, version
  issues.jsonl         # All issues, one JSON object per line
  templates.jsonl      # Template definitions
  .gitignore           # Ignores *.lock files

Add to your .gitattributes (done automatically by sd init):

.seeds/issues.jsonl merge=union
.seeds/templates.jsonl merge=union

The merge=union strategy handles parallel agent branch merges. Seeds deduplicates by ID on read (last occurrence wins), so conflicts resolve automatically.

Success:

{ "success": true, "command": "create", "id": "myproject-a1b2" }

Error:

{ "success": false, "command": "create", "error": "Title is required" }

Seeds is safe for concurrent multi-agent use:

• Advisory file locks — O_CREAT | O_EXCL, 30s stale threshold, 100ms retry with jitter, 30s timeout
• Atomic writes — temp file + rename under lock
• Dedup on read — last occurrence wins after merge=union git merges

Overstory wraps sd via Bun.spawn(["sd", ...]) with --json parsing, identical to how it wraps bd:

Seeds is part of the os-eco AI agent tooling ecosystem.

Contributions are welcome! See CONTRIBUTING.md for guidelines.

MIT