Skip to content

jayminwest/os-eco

Repository files navigation

os-eco

Mulch CI Seeds CI Canopy CI Sapling CI Overstory CI License: MIT

An integrated ecosystem of CLI tools for AI agent workflows. Each tool handles one concern — expertise, issues, prompts, agents, or orchestration — and they compose together so multi-agent teams can operate autonomously on real codebases.

os-eco

Tools

Tool CLI npm What it does
Mulch mulch / ml npm Structured expertise management — agents record conventions, patterns, and decisions as they work, then retrieve them at the start of each session
Seeds sd npm Git-native issue tracking — JSONL storage, dependency graphs, templates, zero external dependencies
Canopy cn npm Prompt management — version-controlled prompt composition with inheritance, pinning, and schema validation
Sapling sp npm Headless coding agent — proactive context management between every LLM call, pluggable backends
Overstory overstory / ov npm Multi-agent orchestration — spawn Claude Code agents in git worktrees via tmux, coordinate through SQLite mail, merge with conflict resolution

How they fit together

overstory (orchestrates agents)
  ├── sapling  (headless coding agent runtime)
  ├── mulch    (stores expertise for agents)
  ├── seeds    (tracks issues agents work on)
  └── canopy   (manages prompts agents use)

Overstory spawns agents (including Sapling) in isolated git worktrees. Those agents pick up work from Seeds, load project expertise from Mulch, and access managed prompts from Canopy. All five tools share the same design principles:

  • Git-native storage — JSONL and YAML files that live in your repo, merge cleanly, and need no external database
  • Zero runtime dependencies — each tool is a single Bun binary with no daemon or server
  • Multi-agent safe — advisory file locking so concurrent agents don't corrupt shared state
  • CLI-first — every operation is a shell command with --json output for scripting and piping
  • Consistent UX — shared color palette, status icons, help screen layout, and flag conventions across all five tools

Quick start

Requires Bun >= 1.0.

# Install all five tools
bun install -g @os-eco/mulch-cli @os-eco/seeds-cli @os-eco/canopy-cli @os-eco/sapling-cli @os-eco/overstory-cli

# Initialize in your project
cd your-project
ml init && sd init && cn init && ov init

# Verify
ml --version && sd --version && cn --version && sp version && ov --version

Or install individually — each tool works standalone:

bun install -g @os-eco/seeds-cli    # just issue tracking
bun install -g @os-eco/mulch-cli    # just expertise management

Example workflow

# An agent starts a session
ml prime                              # load project expertise into context
sd ready                              # find unblocked issues to work on
sd update seed-a1b2 --status in_progress

# Agent does work, then wraps up
ml record testing --type convention \
  --description "Always mock fs in unit tests"
sd close seed-a1b2

# Multi-agent orchestration
ov sling seed-c3d4 --strategy worktree   # spawn an agent for an issue
ov status                                 # monitor running agents
ov merge builder-01                       # merge completed work back

Repo structure

Each tool lives in its own sub-repo with independent git history, CI, and npm versioning. This meta-repo tracks cross-cutting concerns:

os-eco/
  mulch/           # sub-repo: @os-eco/mulch-cli
  seeds/           # sub-repo: @os-eco/seeds-cli
  canopy/          # sub-repo: @os-eco/canopy-cli
  sapling/         # sub-repo: @os-eco/sapling-cli
  overstory/       # sub-repo: @os-eco/overstory-cli
  branding/        # shared visual spec, CLI standards, checklists
  .mulch/          # ecosystem-level expertise
  .seeds/          # ecosystem-level issues
  .canopy/         # shared prompt templates
  .overstory/      # multi-repo orchestration config

Development

# Run tests, lint, and typecheck for any tool
cd mulch && bun test && bun run lint && bun run typecheck
cd seeds && bun test && bun run lint && bun run typecheck
cd canopy && bun test && bun run lint && bun run typecheck
cd sapling && bun test && bun run lint && bun run typecheck
cd overstory && bun test && bun run lint && bun run typecheck

# Check ecosystem health
ov doctor          # checks all tools are installed and healthy
ov ecosystem       # dashboard with versions, health, and status

License

MIT

About

Meta-project for the AI agent tooling ecosystem — Mulch, Seeds, Canopy, and Overstory

Resources

License

Contributing

Security policy

Stars

Watchers

Forks

Releases

No releases published

Packages